Automobilio istorija (VHR)

Būsenos, klaidos ir webhook

Kaip tai veikia

01Autentifikacija

Su kiekviena užklausa siųskite x-api-key. Šaltinių ID ir formatai gaunami iš jūsų katalogo ir VIN patikros; prieigą ir kainas taiko API.

02Patikrinkite, tada pasirinkite vieną šaltinį

POST /checks kiekvienam šaltiniui grąžina price, available_formats ir peržiūrą. POST /reports priima vieną source_id, vieną kalbą ir vieną ar kelis formatus, už vieną kainą už ataskaitą. Jei availability_confirmed yra false, pirmiausia perskaitykite availability_notice.

03Failai, o ne įterpta istorija

JSON, HTML ir PDF pateikiami kaip nuorodos mūsų CDN; kai kurie šaltiniai nuotraukas ar paruoštą HTML puslapį laiko savo pradiniu adresu. Kiekvieną ataskaitos nuorodą laikykite prieigos raktu.

04Ilgos užklausos

HTTP laukia iki 10 sekundžių. HTTP 202 reiškia, kad darbas tęsiasi: kas 1 ar 2 sekundes tikrinkite status_url, kol būsena taps galutinė. Niekada nekartokite laukiančio pirkimo.

05Klaida ir atkūrimas

Šaltinio klaida nėra tas pats, kas duomenų nebuvimas. Už ataskaitą mokama tik tada, kai paruošti visi pasirinkti failai. Jei failų nepavyksta sukurti, POST /reports/{id}/retry vėl naudoja išsaugotus duomenis, be antro mokesčio.

06Webhooks

Tikriems VIN pridėkite viešą HTTPS webhook_url ir webhook_secret (nuo 16 iki 256 simbolių). API atsako 202 ir išsiunčia rezultatą, kai jis paruoštas, pasirašytą X-VHR-Signature su X-VHR-Timestamp.

Būsenos

Atsakymas yra galutinis, kai jo būsena galutinė; iki tol sekite status_url.

Patikra

running: Dar vykdoma. Tikrinkite status_url.
completedGalutinė: Baigta. Atsakė visi šaltiniai arba failai paruošti.
partialGalutinė: Baigta, bet kai kurie šaltiniai grąžino klaidą.
failedGalutinė: Sustabdyta dėl klaidos. Nieko neapmokestinama.

Ataskaita

running: Dar vykdoma. Tikrinkite status_url.
preparing: Šaltinio duomenys išsaugoti; failai kuriami.
rendering: Kuriamas PDF.
completedGalutinė: Baigta. Atsakė visi šaltiniai arba failai paruošti.
not_foundGalutinė: Šaltinis neturi įrašų apie šį VIN. Nieko neapmokestinama.
failedGalutinė: Sustabdyta dėl klaidos. Nieko neapmokestinama.

Kiekvienas patikros šaltinis

available: Rasta įrašų: šaltinį galima užsakyti (be status lauko).
pending: Šis šaltinis dar atsako.
not_found: Šaltinis neturi įrašų apie šį VIN. Nieko neapmokestinama.
error: Šis šaltinis dabar negalėjo atsakyti. Tai nereiškia, kad duomenų nėra.
not_checked: Ši užklausa jo netikrino. Tai nereiškia, kad duomenų nėra.

Klaidos

Klaidos grąžinamos kaip JSON su error_code ir message. Už klaidą nieko neapmokestinama.

401Trūksta x-api-key arba jis neteisingas.

402Nepakanka ataskaitų likučio šiai ataskaitai.

403Šis ataskaitos tipas jūsų raktui neįjungtas.

409Ta pati šio VIN ataskaita jau ruošiama.

422Neteisingas užklausos turinys, pavyzdžiui, VIN, formatas ar kalba, arba pasikeitusi kaina.

429Per daug užklausų. Palaukite akimirką ir bandykite dar kartą.

503Ataskaitos trumpam pristabdytos.

Webhooks

Pridėkite webhook_url ir webhook_secret prie tikro VIN patikros ar ataskaitos: API iškart atsako 202 ir išsiunčia rezultatą, kai jis paruoštas. Prieš pasitikėdami patikrinkite parašą.

X-VHR-Signature yra sha256= ir po jo HMAC-SHA256, apskaičiuotas iš X-VHR-Timestamp reikšmės, taško ir neapdoroto turinio.
Atmeskite senas laiko žymas (pavyzdžiui, senesnes nei 5 minutės) ir pasikartojančias X-VHR-Event-Id reikšmes.
Pavyzdiniai VIN atsako iškart ir niekada nekviečia 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))

}