Istoric auto (VHR)

Statusuri, erori și webhook-uri

Cum funcționează

01Autentificare

Trimite x-api-key la fiecare cerere. Id-urile surselor și formatele vin din catalogul tău și din verificarea VIN; accesul și prețurile sunt aplicate de API.

02Verifici, apoi alegi o sursă

POST /checks returnează price, available_formats și o previzualizare pentru fiecare sursă. POST /reports primește un source_id, o limbă și unul sau mai multe formate, cu un singur preț per raport. Dacă availability_confirmed este false, citește întâi availability_notice.

03Fișiere, nu un istoric inline

JSON, HTML și PDF vin ca linkuri pe CDN-ul nostru; unele surse păstrează fotografiile sau o pagină HTML gata făcută la adresa lor originală. Tratează fiecare link de raport ca pe o cheie de acces.

04Cereri lungi

HTTP așteaptă până la 10 secunde. HTTP 202 înseamnă că lucrul continuă: interoghează status_url la fiecare 1 până la 2 secunde, până când statusul e final. Nu repeta niciodată o achiziție în așteptare.

05Erori și recuperare

O eroare a sursei nu înseamnă lipsă de date. Un raport se taxează doar când fiecare fișier ales este gata. Dacă fișierele eșuează, POST /reports/{id}/retry refolosește datele salvate, fără a doua taxare.

06Webhookuri

Pentru VIN-uri reale adaugă un webhook_url public pe HTTPS și un webhook_secret (de la 16 la 256 de caractere). API-ul răspunde cu 202 și trimite rezultatul când e gata, semnat în X-VHR-Signature cu X-VHR-Timestamp.

Stări

Un răspuns e final când starea lui e finală; până atunci urmărește status_url.

Verificare

running: Încă lucrează. Interoghează status_url.
completedFinală: Gata. Fiecare sursă a răspuns sau fișierele sunt gata.
partialFinală: Gata, dar unele surse au returnat o eroare.
failedFinală: Oprit cu o eroare. Nu se taxează nimic.

Raport

running: Încă lucrează. Interoghează status_url.
preparing: Datele sursei sunt salvate; fișierele se generează.
rendering: PDF-ul se generează.
completedFinală: Gata. Fiecare sursă a răspuns sau fișierele sunt gata.
not_foundFinală: Sursa nu are nicio înregistrare pentru acest VIN. Nu se taxează nimic.
failedFinală: Oprit cu o eroare. Nu se taxează nimic.

Fiecare sursă dintr-o verificare

available: Înregistrări găsite: sursa poate fi comandată (fără câmp de stare).
pending: Această sursă încă răspunde.
not_found: Sursa nu are nicio înregistrare pentru acest VIN. Nu se taxează nimic.
error: Această sursă nu a putut răspunde acum. Nu e același lucru cu lipsa datelor.
not_checked: Nu a fost verificată de această cerere. Nu înseamnă că nu există date.

Erori

Erorile vin ca JSON cu error_code și message. Nu se taxează nimic pentru o eroare.

401x-api-key lipsește sau nu e valid.

402Sold insuficient de rapoarte pentru acest raport.

403Acest tip de raport nu e activat pentru cheia ta.

409Același raport pentru acest VIN se pregătește deja.

422Corp invalid, de exemplu un VIN, un format sau o limbă, ori un preț schimbat.

429Prea multe cereri. Așteaptă puțin și încearcă din nou.

503Rapoartele sunt oprite pentru moment.

Webhookuri

Adaugă webhook_url și webhook_secret la o verificare sau un raport pentru un VIN real: API-ul răspunde imediat cu 202 și trimite rezultatul când e gata. Verifică semnătura înainte să ai încredere în el.

X-VHR-Signature este sha256= urmat de HMAC-SHA256 al valorii X-VHR-Timestamp, un punct și corpul brut.
Refuză marcajele de timp vechi (de exemplu mai vechi de 5 minute) și valorile X-VHR-Event-Id repetate.
VIN-urile de probă răspund imediat și nu apelează niciodată un webhook.

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

}