Historia pojazdu (VHR)

Statusy, błędy i webhooki

Jak to działa

01Uwierzytelnianie

Wysyłaj x-api-key w każdym zapytaniu. Id źródeł i formaty pochodzą z Twojego katalogu i sprawdzenia VIN; dostęp i ceny nalicza API.

02Sprawdź, potem wybierz jedno źródło

POST /checks zwraca price, available_formats i podgląd dla każdego źródła. POST /reports przyjmuje jeden source_id, jeden język i jeden lub więcej formatów, w jednej cenie za raport. Jeśli availability_confirmed ma wartość false, najpierw przeczytaj availability_notice.

03Pliki, a nie historia w odpowiedzi

JSON, HTML i PDF przychodzą jako linki w naszym CDN; niektóre źródła trzymają zdjęcia lub gotową stronę HTML pod swoim oryginalnym adresem. Traktuj każdy link do raportu jak klucz dostępu.

04Długie zapytania

HTTP czeka do 10 sekund. HTTP 202 oznacza, że praca trwa dalej: odpytuj status_url co 1 do 2 sekund, aż status będzie końcowy. Nigdy nie powtarzaj zakupu, który jest jeszcze w toku.

05Błędy i odzyskiwanie

Błąd źródła to nie to samo co brak danych. Raport jest płatny tylko wtedy, gdy każdy wybrany plik jest gotowy. Jeśli pliki się nie udadzą, POST /reports/{id}/retry użyje zapisanych danych, bez drugiej opłaty.

06Webhooki

Dla prawdziwych VIN dodaj publiczny webhook_url na HTTPS i webhook_secret (od 16 do 256 znaków). API odpowiada 202 i wysyła wynik, gdy jest gotowy, podpisany w X-VHR-Signature z X-VHR-Timestamp.

Statusy

Odpowiedź jest ostateczna, gdy jej status jest końcowy; do tego czasu śledź status_url.

Sprawdzenie

running: Wciąż w toku. Odpytuj status_url.
completedKońcowy: Gotowe. Każde źródło odpowiedziało albo pliki są gotowe.
partialKońcowy: Gotowe, ale niektóre źródła zwróciły błąd.
failedKońcowy: Zatrzymane z błędem. Nic nie jest pobierane.

Raport

running: Wciąż w toku. Odpytuj status_url.
preparing: Dane źródła są zapisane; pliki są tworzone.
rendering: PDF jest generowany.
completedKońcowy: Gotowe. Każde źródło odpowiedziało albo pliki są gotowe.
not_foundKońcowy: Źródło nie ma rekordu dla tego VIN-u. Nic nie jest pobierane.
failedKońcowy: Zatrzymane z błędem. Nic nie jest pobierane.

Każde źródło w sprawdzeniu

available: Znaleziono rekordy: źródło można zamówić (brak pola statusu).
pending: To źródło jeszcze odpowiada.
not_found: Źródło nie ma rekordu dla tego VIN-u. Nic nie jest pobierane.
error: To źródło nie mogło teraz odpowiedzieć. To nie to samo co brak danych.
not_checked: Nie sprawdzone w tym żądaniu. Nie oznacza to braku danych.

Błędy

Błędy wracają jako JSON z error_code i message. Za błąd nic nie jest pobierane.

401Brak lub nieprawidłowy x-api-key.

402Za mało salda raportów na ten raport.

403Ten typ raportu nie jest włączony dla twojego klucza.

409Ten sam raport dla tego VIN-u jest już przygotowywany.

422Nieprawidłowa treść, na przykład VIN, format lub język, albo zmieniona cena.

429Za dużo żądań. Odczekaj chwilę i spróbuj ponownie.

503Raporty są na chwilę wstrzymane.

Webhooki

Dodaj webhook_url i webhook_secret do sprawdzenia lub raportu dla prawdziwego VIN-u: API od razu odpowiada 202 i wysyła wynik, gdy jest gotowy. Sprawdź podpis, zanim mu zaufasz.

X-VHR-Signature to sha256=, a po nim HMAC-SHA256 z wartości X-VHR-Timestamp, kropki i surowej treści.
Odrzucaj stare znaczniki czasu (na przykład starsze niż 5 minut) i powtórzone wartości X-VHR-Event-Id.
Przykładowe VIN-y odpowiadają od razu i nigdy nie wywołują webhooka.

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

}