Historique (VHR)

Statuts, erreurs et webhooks

Fonctionnement

01Authentification

Envoyez x-api-key avec chaque requête. Les identifiants de source et les formats viennent de votre propre catalogue et de la vérification du VIN ; l’accès et les prix sont appliqués par l’API.

02Vérifier, puis choisir une source

POST /checks renvoie price, available_formats et un aperçu pour chaque source. POST /reports prend un source_id, une langue et un ou plusieurs formats, pour un prix par rapport. Si availability_confirmed vaut false, lisez d’abord availability_notice.

03Des fichiers, pas un historique intégré

JSON, HTML et PDF arrivent sous forme de liens sur notre CDN ; certaines sources gardent les photos ou une page HTML prête à leur adresse d’origine. Traitez chaque lien de rapport comme une clé d’accès.

04Requêtes longues

HTTP attend jusqu’à 10 secondes. HTTP 202 signifie que le traitement continue : interrogez status_url toutes les 1 à 2 secondes jusqu’à un statut final. Ne répétez jamais un achat en attente.

05Échec et reprise

Une erreur de source n’est pas une absence de données. Un rapport n’est débité que lorsque chaque fichier choisi est prêt. Si les fichiers échouent, POST /reports/{id}/retry réutilise les données enregistrées, sans second débit.

06Webhooks

Pour de vrais VIN, ajoutez un webhook_url public en HTTPS et un webhook_secret (de 16 à 256 caractères). L’API répond 202 et envoie le résultat quand il est prêt, signé dans X-VHR-Signature avec X-VHR-Timestamp.

Statuts

Une réponse est définitive quand son statut est final ; d’ici là, suivez status_url.

Vérification

running: Toujours en cours. Interrogez status_url.
completedFinal: Terminé. Chaque source a répondu, ou les fichiers sont prêts.
partialFinal: Terminé, mais certaines sources ont renvoyé une erreur.
failedFinal: Arrêté sur une erreur. Rien n’est débité.

Rapport

running: Toujours en cours. Interrogez status_url.
preparing: Les données de source sont enregistrées ; les fichiers sont en cours de création.
rendering: Le PDF est en cours de rendu.
completedFinal: Terminé. Chaque source a répondu, ou les fichiers sont prêts.
not_foundFinal: La source n’a aucune entrée pour ce VIN. Rien n’est débité.
failedFinal: Arrêté sur une erreur. Rien n’est débité.

Chaque source d’une vérification

available: Entrées trouvées : la source peut être commandée (pas de champ status).
pending: Cette source répond encore.
not_found: La source n’a aucune entrée pour ce VIN. Rien n’est débité.
error: Cette source n’a pas pu répondre pour le moment. Ce n’est pas la même chose qu’une absence de données.
not_checked: Non vérifiée par cette requête. Cela ne veut pas dire qu’il n’y a pas de données.

Erreurs

Les erreurs reviennent en JSON avec error_code et message. Rien n’est débité pour une erreur.

401x-api-key manquant ou invalide.

402Solde de rapports insuffisant pour ce rapport.

403Ce type de rapport n’est pas activé pour votre clé.

409Le même rapport pour ce VIN est déjà en préparation.

422Corps invalide, par exemple un VIN, un format ou une langue, ou un prix modifié.

429Trop de requêtes. Patientez un instant et réessayez.

503Les rapports sont en pause pour un moment.

Webhooks

Ajoutez webhook_url et webhook_secret à une vérification ou à un rapport pour un VIN réel : l’API répond 202 immédiatement et envoie le résultat quand il est prêt. Vérifiez la signature avant de vous y fier.

X-VHR-Signature vaut sha256= suivi du HMAC-SHA256 de la valeur X-VHR-Timestamp, d’un point et du corps brut.
Refusez les horodatages anciens (par exemple de plus de 5 minutes) et les valeurs X-VHR-Event-Id répétées.
Les VIN d’exemple répondent immédiatement et n’appellent jamais de 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))

}