Описание интерфейса сервиса 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

ПараметрЗначениеОписание
actionnAction - число

Значения:

  • 0 - заказать новый отчет или обновить отчет с сервера AutoCheck/CARFAX
  • 1- загрузить копию уже заказанного отчета с сервера vinfact.com (бесплатно)
  •  

    loginsLogin - строка длиной от 1 до 16 символовЛогин от аккаунта vinfact.com
    vinsVIN - строка длиной 17 символовVIN-код транспортного средства
    reportnReport - число

    Значения:

  • 0 - отчет AutoCheck
  • 1 - отчет CARFAX
  • crcsCRC - строка

    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>&lt;html&gt;&lt;head&gt;{...}&lt;/body&gt;&lt;/html&gt;</english_report>

    <russian_report>&lt;html&gt;&lt;head&gt;{...}&lt;/body&gt;&lt;/html&gt;</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 сущность
    &
    &amp;
    <
    &lt;
    >
    &gt;

    При возникновении ошибки выводится только элемент <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

    ПараметрЗначениеОписание
    actionnAction - число

    Значения:

  • 0 - загрузить краткий отчет с сервера AutoCheck/CARFAX
  • 1 - проверить добавлен ли VIN в аккаунт и вывести краткий отчет с сервера vinfact.com по нему
  •  

    loginsLogin - строка длиной от 1 до 16 символовЛогин от аккаунта vinfact.com
    vinsVIN - строка длиной 17 символовVIN-код транспортного средства
    crcsCRC - строка

    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Текстовое описание ошибки
    vinVIN-код транспортного средства
    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

    ПараметрЗначениеОписание
    actionnAction - число

    На данный момент action имеет одно значение, равное 0

     

    loginsLogin - строка длиной от 1 до 16 символовЛогин от аккаунта vinfact.com
    crcsCRC - строка

    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));
    ?>