Історія авто (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))

}