История на авто (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. За грешка нищо не се таксува.

401Липсващ или невалиден x-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))

}