Описание
интерфейса сервиса vinfact.comИнтерфейс сервиса vinfact.com предоставляет
возможность автоматизированного получения полных и кратких отчетов AutoCheck и
CARFAX на английском и русском языках на вашем веб-сайте.
Содержание
Предварительные настройки
Интерфейс запроса полных отчетов
Интерфейc запроса кратких отчетов
Интерфейc запроса состояния счета
Предварительные
настройкиВ аккаунте vinfact.com в разделе "Настройки", пункте
"Настройки интерфейса " укажите пароль подписи транзакции - строка длиной
32 символа, состоящая из знаков A-Z, a-z, 0-9. Скачайте архив http://www.vinfact.com/downloads/images.zip
и распакуйте его в корневую директорию вашего сайта (у большинства хостинг-провайдеров
эта папка называется "www", "public_html" или "htdocs").
Расположение изображений, JavaScipt и CSS файлов такое же как на серверах AutoCheck
и CARFAX. Русифицированные изображения имеют постфикс "_r", т.е. "image.gif"
- изображение для отчета на английском языке, "image_r.gif" - на русском. Интерфейс
запроса полных отчетовЗапрос к серверу
Доступ к интерфейсу осуществляется по протоколу HTTP c использованием
метода запроса GET:
http://www.vinfact.com/interface/reports/?action=nAction&login=sLogin&vin=sVIN&report=nReport&crc=sCRC |
Параметр | Значение | Описание |
action | nAction - число |
Значения: 0 - заказать новый отчет или обновить отчет с сервера AutoCheck/CARFAX1-
загрузить копию уже заказанного отчета с сервера vinfact.com (бесплатно)
| login | sLogin -
строка длиной от 1 до 16 символов | Логин от аккаунта vinfact.com |
vin | sVIN - строка длиной 17 символов | VIN-код
транспортного средства | report | nReport
- число | Значения: 0 - отчет AutoCheck1 - отчет CARFAX |
crc | sCRC - строка | MD5
хэш передаваемых параметров, представляет собой 32-значное шестнадцатеричное число.
Формируется по строке, содержащей все параметры запроса, разделенные ‘:’, с добавлением
пароля подписи транзакции sSign (указывается в аккаунте vinfact.com -
раздел "Настройки", пункт "Настройки интерфейса") т.е.
sAction:sLogin:sVIN:nReport:sSign | Ответ сервера
Сервер vinfact.com возвращает XML-документ:
<?xml version="1.0" encoding="windows-1251"?>
<reports> <query_error> <error_code>0</error_code>
<error_description>OK</error_description> </query_error>
<report> <prepaid>1</prepaid> <price>0</price>
<update_date>200804021724</update_date>
<english_report><html><head>{...}</body></html></english_report>
<russian_report><html><head>{...}</body></html></russian_report> </report>
</reports> |
Содержимое элементов Элемент | Содержимое
элемента | error_code | Состояние транзакции/код ошибки
(см. таблицу "Коды ошибок") | error_description | Текстовое
описание ошибки | prepaid | Списание предоплаченных
отчетов: - 0 - отчет не списан (нет предоплаченных отчетов);
- 1
- отчет списан (в этом случае в элементе <price>указывается стоимость этого
отчета в соответствии с тарифами)
|
price | Стоимость отчета | update_date | Строка
с датой последнего обновления файла images.zip | english_report | Отчет
на английском языке | russian_report | Отчет на русском
языке | В элементах <english_report> и <russian_report>
символы "&", "<" и ">" заменены на соответствующие
HTML сущности: Символ | HTML
сущность | & | & | < | < | > | > |
При
возникновении ошибки выводится только элемент <query_error>. Коды
ошибок Номер
ошибки | Описание |
Комментарий |
0 | Нет ошибки | | 1 | Логин
не найден | | 2 | Неправильный VIN-код | Длина
VIN-кода не равна 17 символам или присутствуют посторонние символы (буквы "I",
"O" и "Q") | 3 |
Отсутствуют
записи по указанному VIN-коду | |
4 | Ошибка при получении отчета | При получении
отчета с сервера AutoCheck/CARFAX произошла ошибка или сервер AutoCheck/CARFAX
недоступен | 5 | Неправильный тип отчета | Значение
отличается от 0 или 1 | 6 | Неправильно
указан параметр action | Значение отличается от 0 или 1 | 8 | Неверно
сформирован запрос | В запросе на сервер vinfact.com отсутствует один из
параметров (action, login, vin, report или crc) | 9 | Ошибка
сервера | На сервере vinfact.com произошла внутрення ошибка (недоступна
база данных или т.п.) | 10 | Недостаточно
средств на счете для оплаты отчета | | 11 | Отчет
не был заказан | Ошибка выдается при попытке скачать копию отчета с сервера
vinfact.com (параметр action=1), если он до этого не был заказан |
12 | Ошибка CRC | Ошибка контрольной суммы в запросе
к серверу vinfact.com | 13 | Вывод отчета
AutoCheck или CARFAX отключен | Службой поддержки отключен вывода отчета
из-за профилактических работ на сервере AutoCheck/CARFAX или по другой причине |
14 | Не указан пароль для подписи транзакций | Пароль
для подписи транзакций (указывается в аккаунте vinfact.com - раздел "Настройки",
пункт "Настройки интерфейса") |
Пример реализации запроса на PHP
Для тестирования используйте VIN-код "11111111111111111". При его запросе будут выводиться тестовые отчеты без списания средств со счета.
Версия для PHP с установленным SimpleXML.so
<?
// Для работы примера требуется PHP 5.1.0
// Устанавливаем время выполнения скрипта, равным 480 секунд,
// т.к. отчет может скачиваться более 30 секунд (время выполнения
// скрипта по умолчанию).
set_time_limit(480);
// Загрузить отчет с сервера AutoCheck/CARFAX
$action = 0;
// Логин
$login = 'Ваш_логин';
// VIN-код
$vin = '11111111111111111'; //по этому VIN-коду отчет будет предоставлен бесплатно
// Отчет AutoCheck
$report = 0;
// Пароль для подписи транзакций (указывается в аккаунте vinfact.com - раздел
// "Настройки", пункт "Дополнительные настройки").
$sign = 'Ваш_пароль_подписи_транзакций';
// Контрольная сумма
$crc=md5($action.":".$login.":".$vin.":".$report.":".$sign);
// Строка запроса к серверу vinfact.com
$query="http://vinfact.com/interface/reports/?action=$action&login=$login&vin=$vin&report=$report&crc=$crc";
// Интерпретируем XML в объект
$xml=simplexml_load_file($query);
// Выводим отчет
if ($xml->query_error[0]->error_code==0)
{
// При использовании PHP 5.20 необходимо конвертировать объект из кодировки UTF-8
// В более ранних версиях PHP этого не требуется
print html_entity_decode(iconv('UTF-8', 'CP1251',$xml->report[0]->russian_report));
print html_entity_decode(iconv('UTF-8', 'CP1251',$xml->report[0]->english_report));
}
else print 'Ошибка: '.html_entity_decode(iconv('UTF-8', 'CP1251',$xml->query_error[0]->error_description));
?>
|
Версия для PHP без SimpleXML.so
<?
// Для работы примера требуется PHP 5.1.0
// Устанавливаем время выполнения скрипта, равным 480 секунд,
// т.к. отчет может скачиваться более 30 секунд (время выполнения
// скрипта по умолчанию).
set_time_limit(480);
// Загрузить отчет с сервера AutoCheck/CARFAX
$action = 0;
// Логин
$login = 'Ваш_логин';
// VIN-код
$vin = '11111111111111111'; //по этому VIN-коду отчет будет предоставлен бесплатно
// Отчет AutoCheck
$report = 0;
// Пароль для подписи транзакций (указывается в аккаунте vinfact.com - раздел
// "Настройки", пункт "Дополнительные настройки").
$sign = 'Ваш_пароль_подписи_транзакций';
// Контрольная сумма
$crc=md5($action.":".$login.":".$vin.":".$report.":".$sign);
// Строка запроса к серверу vinfact.com
$query="http://vinfact.com/interface/reports/?action=$action&login=$login&vin=$vin&report=$report&crc=$crc";
// Загружаем XML
$xml = file_get_contents($query);
preg_match('/<error_code>([^<]+)<\/error_code>/', $xml, $error_code);
preg_match('/<error_description>([^<]+)<\/error_description>/', $xml, $error_description);
preg_match('/<prepaid>([^<]+)<\/prepaid>/', $xml, $prepaid);
preg_match('/<price>([^<]+)<\/price>/', $xml, $price);
preg_match('/<update_date>([^<]+)<\/update_date>/', $xml, $update_date);
preg_match('/<english_report>([^<]+)<\/english_report>/', $xml, $english_report);
preg_match('/<russian_report>([^<]+)<\/russian_report>/', $xml, $russian_report);
// Выводим отчет
if ($error_code[1]==0)
{
print '<br>Предоплаченных отчетов: '.html_entity_decode($prepaid[1]);
print '<br>Стоимость отчета: '.html_entity_decode($price[1]);
print '<br>Отчет на русском языке: '.html_entity_decode($russian_report[1]);
print '<br>Отчет на английском языке: '.html_entity_decode($english_report[1]);
}
else print 'Ошибка: '.html_entity_decode($error_description[1]);
?>
|
Интерфейc
запроса кратких отчетовЗапрос к серверу
Доступ к интерфейсу осуществляется по протоколу HTTP c использованием
метода запроса GET:
http://www.vinfact.com/interface/vehicles/?action=nAction&login=sLogin&vin=sVIN&crc=sCRC |
Параметр | Значение | Описание |
action | nAction - число |
Значения: 0 - загрузить краткий отчет с сервера AutoCheck/CARFAX
1
- проверить добавлен ли VIN в аккаунт и вывести краткий отчет с сервера vinfact.com по нему
|
login | sLogin - строка длиной
от 1 до 16 символов | Логин от аккаунта vinfact.com | vin | sVIN
- строка длиной 17 символов | VIN-код транспортного средства |
crc | sCRC - строка | MD5
хэш передаваемых параметров, представляет собой 32-значное шестнадцатеричное число.
Формируется по строке, содержащей все параметры запроса, разделенные ‘:’, с добавлением
пароля подписи транзакции sSign (указывается в аккаунте vinfact.com -
раздел "Настройки", пункт "Настройки интерфейса") т.е.
sAction:sLogin:sVIN:nReport:sSign | Ответ сервера
Сервер возвращает XML-документ (action=0):
<?xml version="1.0" encoding="windows-1251"?>
<vehicles>
<query_error>
<error_code>0</error_code>
<error_description>OK</error_description>
</query_error>
<vehicle>
<vin>SHSRD7888442XXXXX</vin>
<autocheck>
<year>2004</year>
<make>Honda</make>
<model>CR-V EX</model>
<style>SUV / Utility 4D</style>
<engine>2.4L I4 MPI</engine>
<country>Великобритания</country>
<records>1</records>
<status>1</status>
</autocheck>
<carfax>
<year>2004</year>
<make>HONDA</make>
<model>CR-V EX</model>
<style>4 DR. WAGON/SPORT UTILITY</style>
<engine>2.4L L4 PFI DOHC</engine>
<country>Великобритания</country>
<records>0</records>
<status>1</status>
</carfax>
</vehicle>
</vehicles> |
Сервер возвращает XML-документ (action=1):
<?xml version="1.0" encoding="windows-1251"?>
<vehicles>
<query_error>
<error_code>0</error_code>
<error_description>OK</error_description>
</query_error>
<vehicle>
<vin>SHSRD7888442XXXXX</vin>
<year>2004</year>
<make>Honda</make>
<model>CR-V EX</model>
<style>SUV / Utility 4D</style>
<engine>2.4L I4 MPI</engine>
<country>Великобритания</country>
<autocheck>
<records>1</records>
<status>1</status>
</autocheck>
<carfax>
<records>5</records>
<status>1</status>
</carfax>
</vehicle>
</vehicles> |
Содержимое элементов
Элемент | Содержимое
элемента | error_code | Состояние транзакции/код ошибки (см.
таблицу "Коды ошибок") | error_description | Текстовое
описание ошибки | vin | VIN-код транспортного средства | year | Год
производства | make | Производитель | model | Модель | style | Тип
кузова | engine | Двигатель | country | Страна-производитель | records | Количество
записей в отчете | status | Значения элемента status в зависимости от параметра action:
- Параметр action = 0
0 - отчет недоступен для заказа
(отсутствуют записи или VIN-кода нет в базе AutoCheck/CARFAX);
1 - отчет доступен для заказа;
3 - отчет недоступен для заказа
(вывод отчетов временно отключен);
- Параметр action=1
0 - отчет недоступен для заказа
(отсутствуют записи или VIN-кода нет в базе AutoCheck/CARFAX);
1 - отчет не заказан;
2 - отчет заказан;
3 - отчет недоступен для заказа
(вывод отчетов временно отключен);
|
При
возникновении ошибки выводится только элемент <query_error>. Коды
ошибок Номер
ошибки | Описание |
Комментарий |
0 | Нет ошибки | | 1 | Логин
не найден | | 2 | Неправильный VIN-код | Длина
VIN-кода не равна 17 символам или присутствуют посторонние символы (буквы "I",
"O" и "Q") |
4 | Ошибка при получении краткого отчета | При
получении отчета с сервера AutoCheck/CARFAX произошла ошибка или сервер AutoCheck/CARFAX
недоступен | 6 | Неправильно указан параметр
action | |
7 |
VIN-код не был добавлен в аккаунт |
Ошибка выдается при попытке получить информацию о VIN с сервера
vinfact.com (параметр action=1), если он до этого не был добавлен в аккаунт |
8 | Неверно сформирован запрос | В запросе
на сервер vinfact.com отсутствует один из параметров (action, login, vin или crc) |
9 | Ошибка сервера | На сервере vinfact.com
произошла внутрення ошибка (недоступна база данных или т.п.) | 12 | Ошибка
CRC | Ошибка контрольной суммы в запросе к серверу vinfact.com |
13 | Вывод кратких отчетов отключен | Службой
поддержки отключен вывода отчета из-за профилактических работ на сервере AutoCheck/CARFAX
или по другой причине | 14 | Не указан пароль
для подписи транзакций | Пароль для подписи транзакций (указывается в аккаунте
vinfact.com - раздел "Настройки", пункт "Дополнительные настройки") |
Пример реализации запроса на PHP
<?
// Для работы примера требуется PHP 5.1.0
// Загрузить краткий отчет с сервера AutoCheck/CARFAX
$action = 0;
$login = 'Ваш_логин';
$vin = 'VIN-код';
// Пароль для подписи транзакций (указывается в аккаунте vinfact.com - раздел
// "Настройки", пункт "Дополнительные настройки").
$sign = 'Ваш_пароль_подписи_транзакций';
// Контрольная сумма
$crc=md5($action.":".$login.":".$vin.":".$sign);
// Строка запроса к серверу vinfact.com
$query="http://vinfact.com/interface/vehicles/?action=$action&login=$login&vin=$vin&crc=$crc";
// Интерпретируем XML в объект
$xml=simplexml_load_file($query);
// Выводим XML
if ($xml->query_error[0]->error_code==0) print $xml->asXML();
else print 'Ошибка: '.html_entity_decode(iconv('UTF-8', 'CP1251',$xml->query_error[0]->error_description));
?> | Интерфейc запроса
состояния счета
Запрос к серверу
Доступ к интерфейсу осуществляется по протоколу HTTP c использованием
метода запроса GET:
http://www.vinfact.com/interface/accounts/?action=nAction&login=sLogin&crc=sCRC |
Параметр | Значение | Описание |
action | nAction - число |
На данный момент action имеет одно значение, равное 0 |
login | sLogin - строка длиной
от 1 до 16 символов | Логин от аккаунта vinfact.com | crc | sCRC
- строка | MD5 хэш передаваемых параметров, представляет собой 32-значное
шестнадцатеричное число. Формируется по строке, содержащей все параметры запроса,
разделенные ‘:’, с добавлением пароля подписи транзакции sSign (указывается
в аккаунте vinfact.com - раздел "Настройки", пункт "Дополнительные
настройки") т.е. sAction:sLogin:sVIN:nReport:sSign |
Ответ сервера
Сервер vinfact.com возвращает XML-документ:
<?xml version="1.0" encoding="windows-1251"?>
<accounts> <query_error> <error_code>0</error_code>
<error_description>OK</error_description> </query_error> <account>
<money>100.71</money> <reports>10</reports> </account>
</accounts> | Содержимое элементов
Элемент |
Содержимое
элемента |
error_code | Состояние транзакции/код ошибки (см.
таблицу "Коды ошибок") | error_description | Текстовое
описание ошибки | money | Сумма на счету | repots | Количество
предоплаченных отчетов | При возникновении ошибки выводится
только элемент <query_error>. Коды ошибок
Номер ошибки | Описание |
Комментарий |
0 | Нет ошибки | | 1 | Логин
не найден | | 6 | Неправильно указан
параметр action | На данный момент action имеет одно значение, равное 0 |
8 | Неверно сформирован запрос | В запросе
на сервер vinfact.com отсутствует один из параметров (action, login или crc) |
9 | Ошибка сервера | На сервере vinfact.com
произошла внутрення ошибка (недоступна база данных или т.п.) | 12 | Ошибка
CRC | Ошибка контрольной суммы в запросе к серверу vinfact.com |
13 | Вывод информации отключен | Службой поддержки
отключен вывода отчета из-за профилактических работ на сервере или по другой причине |
14 | Не указан пароль для подписи транзакций | Пароль
для подписи транзакций (указывается в аккаунте vinfact.com - раздел "Настройки",
пункт "Дополнительные настройки") | Пример реализации
запроса на PHP
<?
// Для работы примера требуется PHP 5.1.0
// На данный момент action имеет одно значение, равное 0
$action = 0;
$login = 'Ваш_логин';
$sign = 'Ваш_пароль_подписи_транзакций';
// Контрольная сумма
$crc=md5($action.":".$login.":".$sign);
// Строка запроса к серверу vinfact.com
$query="http://vinfact.com/interface/accounts/?action=$action&login=$login&crc=$crc";
$xml=simplexml_load_file($query);
if ($xml->query_error[0]->error_code==0)
{
print 'Денег на счету: '.html_entity_decode(iconv('UTF-8', 'CP1251',$xml->account[0]->money)).'<br>';
print 'Бесплатных отчетов: '.html_entity_decode(iconv('UTF-8', 'CP1251',$xml->account[0]->reports));
}
else print 'Ошибка: '.html_entity_decode(iconv('UTF-8', 'CP1251',$xml->query_error[0]->error_description));
?> |
|