Historial (VHR)

Estados, errores y webhooks

Cómo funciona

01Autenticación

Envía x-api-key en cada solicitud. Los ids de fuente y los formatos salen de tu propio catálogo y de la consulta del VIN; el acceso y los precios los aplica la API.

02Consulta y elige una fuente

POST /checks devuelve price, available_formats y una vista previa de cada fuente. POST /reports recibe un source_id, un idioma y uno o más formatos, por un precio por informe. Si availability_confirmed es false, lee primero availability_notice.

03Archivos, no un historial incrustado

JSON, HTML y PDF llegan como enlaces en nuestra CDN; algunas fuentes mantienen las fotos o una página HTML lista en su dirección original. Trata cada enlace de informe como una clave de acceso.

04Solicitudes largas

HTTP espera hasta 10 segundos. HTTP 202 significa que el trabajo sigue: consulta status_url cada 1 a 2 segundos hasta que el estado sea final. Nunca repitas una compra pendiente.

05Error y recuperación

Un error de la fuente no equivale a que no haya datos. Un informe se cobra solo cuando cada archivo elegido está listo. Si fallan los archivos, POST /reports/{id}/retry reutiliza los datos guardados, sin un segundo cobro.

06Webhooks

Para VIN reales añade un webhook_url público con HTTPS y un webhook_secret (de 16 a 256 caracteres). La API responde 202 y envía el resultado cuando está listo, firmado en X-VHR-Signature con X-VHR-Timestamp.

Estados

Una respuesta es definitiva cuando su estado es final; hasta entonces, sigue status_url.

Consulta

running: Aún en curso. Consulta status_url.
completedFinal: Listo. Todas las fuentes respondieron o los archivos están listos.
partialFinal: Listo, pero algunas fuentes devolvieron un error.
failedFinal: Detenido por un error. No se cobra nada.

Informe

running: Aún en curso. Consulta status_url.
preparing: Los datos de la fuente están guardados; se están creando los archivos.
rendering: Se está generando el PDF.
completedFinal: Listo. Todas las fuentes respondieron o los archivos están listos.
not_foundFinal: La fuente no tiene registros de este VIN. No se cobra nada.
failedFinal: Detenido por un error. No se cobra nada.

Cada fuente de una consulta

available: Hay registros: la fuente se puede pedir (sin campo status).
pending: Esta fuente aún está respondiendo.
not_found: La fuente no tiene registros de este VIN. No se cobra nada.
error: Esta fuente no pudo responder ahora. No es lo mismo que no tener datos.
not_checked: No consultada en esta solicitud. No significa que no haya datos.

Errores

Los errores llegan como JSON con error_code y message. Un error no se cobra.

401Falta x-api-key o no es válida.

402Saldo de informes insuficiente para este informe.

403Este tipo de informe no está activado para tu clave.

409El mismo informe para este VIN ya se está preparando.

422Cuerpo no válido, por ejemplo un VIN, un formato o un idioma, o un precio que cambió.

429Demasiadas solicitudes. Espera un momento y vuelve a intentarlo.

503Los informes están en pausa por un momento.

Webhooks

Añade webhook_url y webhook_secret a una consulta o un informe de un VIN real: la API responde 202 al instante y envía el resultado cuando está listo. Comprueba la firma antes de fiarte de él.

X-VHR-Signature es sha256= seguido del HMAC-SHA256 del valor de X-VHR-Timestamp, un punto y el cuerpo sin procesar.
Rechaza marcas de tiempo antiguas (por ejemplo, de más de 5 minutos) y valores repetidos de X-VHR-Event-Id.
Los VIN de ejemplo responden al instante y nunca llaman a 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))

}