История авто (VHR)

Статусы, ошибки и вебхуки

Как это работает

01Аутентификация

Передавайте x-api-key в каждом запросе. Id источников и форматы берутся из вашего каталога и проверки VIN; доступ и цены применяет API.

02Проверка, затем один источник

POST /checks возвращает price, available_formats и превью для каждого источника. POST /reports принимает один source_id, один язык и один или несколько форматов, по одной цене за отчёт. Если availability_confirmed равно false, сначала прочитайте availability_notice.

03Файлы, а не история в ответе

JSON, HTML и PDF приходят ссылками на нашем CDN; некоторые источники хранят фото или готовую HTML-страницу по своему исходному адресу. Считайте каждую ссылку на отчёт ключом доступа.

04Долгие запросы

HTTP ждёт до 10 секунд. HTTP 202 означает, что работа продолжается: опрашивайте status_url каждые 1 или 2 секунды, пока статус не станет финальным. Никогда не повторяйте покупку, которая ещё в работе.

05Ошибки и восстановление

Ошибка источника не то же самое, что отсутствие данных. Отчёт оплачивается только тогда, когда готов каждый выбранный файл. Если файлы не созданы, POST /reports/{id}/retry использует сохранённые данные без повторной оплаты.

06Webhooks

Для реальных VIN добавьте публичный HTTPS webhook_url и webhook_secret (от 16 до 256 символов). API отвечает 202 и отправляет результат, когда он готов, с подписью в X-VHR-Signature и X-VHR-Timestamp.

Статусы

Ответ окончательный, когда его статус финальный; до этого следите за status_url.

Проверка

running: Ещё в работе. Опрашивайте status_url.
completedФинальный: Готово. Ответил каждый источник, или файлы готовы.
partialФинальный: Готово, но некоторые источники вернули ошибку.
failedФинальный: Остановлено с ошибкой. Ничего не списывается.

Отчёт

running: Ещё в работе. Опрашивайте status_url.
preparing: Данные источника сохранены; файлы создаются.
rendering: PDF формируется.
completedФинальный: Готово. Ответил каждый источник, или файлы готовы.
not_foundФинальный: У источника нет записей по этому VIN. Ничего не списывается.
failedФинальный: Остановлено с ошибкой. Ничего не списывается.

Каждый источник в проверке

available: Записи найдены: источник можно заказать (поля статуса нет).
pending: Этот источник ещё отвечает.
not_found: У источника нет записей по этому VIN. Ничего не списывается.
error: Этот источник сейчас не смог ответить. Это не то же самое, что отсутствие данных.
not_checked: Не проверялся в этом запросе. Это не значит, что данных нет.

Ошибки

Ошибки приходят в JSON с error_code и message. За ошибку ничего не списывается.

401x-api-key отсутствует или недействителен.

402Недостаточно баланса отчётов для этого отчёта.

403Этот тип отчёта не включён для вашего ключа.

409Такой же отчёт по этому VIN уже готовится.

422Неверное тело запроса, например VIN, формат или язык, либо изменилась цена.

429Слишком много запросов. Подождите немного и попробуйте снова.

503Отчёты ненадолго приостановлены.

Вебхуки

Добавьте webhook_url и webhook_secret к проверке или отчёту для реального VIN: API сразу отвечает 202 и отправляет результат, когда он готов. Проверьте подпись, прежде чем доверять ему.

X-VHR-Signature это sha256=, за которым следует HMAC-SHA256 от значения X-VHR-Timestamp, точки и исходного тела.
Отклоняйте старые метки времени (например, старше 5 минут) и повторные значения X-VHR-Event-Id.
Примеры VIN отвечают сразу и никогда не вызывают вебхук.

import crypto from 'node:crypto'

// raw: the request body exactly as received (a Buffer or string)

export const verify = (raw, headers, secret) => {

const stamp = headers['x-vhr-timestamp']

const sent = String(headers['x-vhr-signature'] || '').replace('sha256=', '')

const age = Math.abs(Date.now() / 1000 - Number(stamp))

if (!stamp || !Number.isFinite(age) || age > 300) return false

const mac = crypto.createHmac('sha256', secret).update(`${stamp}.${raw}`).digest('hex')

return sent.length === mac.length && crypto.timingSafeEqual(Buffer.from(sent), Buffer.from(mac))

}