Historia e automjetit (VHR)

Statuset, gabimet dhe webhooks

Si funksionon

01Autentikimi

Dërgoni x-api-key në çdo kërkesë. ID-të e burimeve dhe formatet vijnë nga katalogu juaj dhe nga kontrolli i VIN-it; aksesin dhe çmimet i zbaton API.

02Kontrolloni, pastaj zgjidhni një burim

POST /checks kthen price, available_formats dhe një parapamje për çdo burim. POST /reports merr një source_id, një gjuhë dhe një ose më shumë formate, për një çmim për raport. Nëse availability_confirmed është false, lexoni fillimisht availability_notice.

03Skedarë, jo një histori e brendshme

JSON, HTML dhe PDF vijnë si lidhje në CDN-në tonë; disa burime i mbajnë fotot ose një faqe HTML të gatshme në adresën e tyre origjinale. Trajtojeni çdo lidhje raporti si një çelës aksesi.

04Kërkesa të gjata

HTTP pret deri në 10 sekonda. HTTP 202 do të thotë që puna vazhdon: kontrolloni status_url çdo 1 deri në 2 sekonda derisa statusi të jetë përfundimtar. Mos e përsëritni kurrë një blerje në pritje.

05Dështimi dhe rikuperimi

Një gabim i burimit nuk është e njëjta gjë me mungesën e të dhënave. Raporti tarifohet vetëm kur çdo skedar i zgjedhur është gati. Nëse skedarët dështojnë, POST /reports/{id}/retry ripërdor të dhënat e ruajtura, pa tarifë të dytë.

06Webhooks

Për VIN reale shtoni një webhook_url publik me HTTPS dhe një webhook_secret (nga 16 deri në 256 karaktere). API përgjigjet me 202 dhe dërgon rezultatin kur është gati, të nënshkruar në X-VHR-Signature me X-VHR-Timestamp.

Statuset

Një përgjigje është përfundimtare kur statusi i saj është përfundimtar; deri atëherë ndiqni status_url.

Kontrolli

running: Ende në punë. Pyetni status_url.
completedPërfundimtar: Përfundoi. Çdo burim u përgjigj ose skedarët janë gati.
partialPërfundimtar: Përfundoi, por disa burime kthyen gabim.
failedPërfundimtar: U ndal me gabim. Nuk paguhet asgjë.

Raporti

running: Ende në punë. Pyetni status_url.
preparing: Të dhënat e burimit janë ruajtur; skedarët po krijohen.
rendering: PDF-ja po krijohet.
completedPërfundimtar: Përfundoi. Çdo burim u përgjigj ose skedarët janë gati.
not_foundPërfundimtar: Burimi nuk ka regjistrim për këtë VIN. Nuk paguhet asgjë.
failedPërfundimtar: U ndal me gabim. Nuk paguhet asgjë.

Çdo burim në një kontroll

available: U gjetën regjistrime: burimi mund të porositet (pa fushë status).
pending: Ky burim ende po përgjigjet.
not_found: Burimi nuk ka regjistrim për këtë VIN. Nuk paguhet asgjë.
error: Ky burim nuk mundi të përgjigjet tani. Nuk është e njëjta gjë me mungesën e të dhënave.
not_checked: Nuk u kontrollua nga kjo kërkesë. Nuk do të thotë se nuk ka të dhëna.

Gabimet

Gabimet kthehen si JSON me error_code dhe message. Për një gabim nuk paguhet asgjë.

401x-api-key mungon ose është i pavlefshëm.

402Nuk ka bilanc të mjaftueshëm raportesh për këtë raport.

403Ky lloj raporti nuk është aktivizuar për çelësin tuaj.

409I njëjti raport për këtë VIN po përgatitet tashmë.

422Trup i pavlefshëm, për shembull një VIN, format ose gjuhë, ose një çmim i ndryshuar.

429Shumë kërkesa. Prisni pak dhe provoni përsëri.

503Raportet janë pezulluar për pak kohë.

Webhooks

Shtoni webhook_url dhe webhook_secret në një kontroll ose raport për një VIN real: API përgjigjet menjëherë me 202 dhe dërgon rezultatin kur është gati. Kontrolloni nënshkrimin para se t’i besoni.

X-VHR-Signature është sha256= i ndjekur nga HMAC-SHA256 i vlerës X-VHR-Timestamp, një pike dhe trupit të papërpunuar.
Refuzoni vulat kohore të vjetra (për shembull më të vjetra se 5 minuta) dhe vlerat e përsëritura X-VHR-Event-Id.
VIN-et shembull përgjigjen menjëherë dhe nuk thërrasin kurrë 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))

}