API y webhooks para software de taller
¿Desarrollas software de planificación, taller o concesionario? Con una clave del taller tu sistema lee coches, códigos de avería, informes y trayectos, y recibe una señal cuando pasa algo. Solo lectura, y siempre con el permiso del propietario.
La referencia técnica (endpoints, campos, ejemplos) está en inglés, como la propia API.
Cómo empezar
- El taller tiene Car-Z Garage. El propietario o un administrador abre el taller y la pestaña Integraciones.
- Crea una clave con un nombre y lo que puede leer, y la copia una vez en tu software.
- Tu software envía la clave con cada petición. Para las señales, el taller también introduce ahí tu dirección de webhook.
Autenticación
Envía la clave en la cabecera Authorization como token Bearer, solo por HTTPS. Nunca en una URL. Una clave pertenece a un solo taller; una clave revocada deja de funcionar al instante. Solo guardamos una huella de la clave, así que una clave perdida no se puede volver a mostrar: crea una nueva.
Authorization: Bearer cz_…Test the key
curl -s https://car-z.app/api/v1 \
-H "Authorization: Bearer $CARZ_API_KEY"List cars (first page of 100)
curl -s "https://car-z.app/api/v1/cars?limit=100" \
-H "Authorization: Bearer $CARZ_API_KEY"Fault codes of one car in a period, descriptions in Dutch
curl -s "https://car-z.app/api/v1/cars/$CAR_ID/codes?from=2026-10-01&to=2026-10-31&lang=nl" \
-H "Authorization: Bearer $CARZ_API_KEY"Next page
curl -s "https://car-z.app/api/v1/cars/$CAR_ID/trips?cursor=$NEXT_CURSOR" \
-H "Authorization: Bearer $CARZ_API_KEY"Endpoints
Todos los endpoints son de solo lectura (GET), llevan la versión en la ruta y responden en JSON: nombres de campo fijos en inglés, fechas ISO 8601 en UTC y unidades métricas en el nombre del campo (distance_km, avg_speed_kmh).
| Método | Ruta | Permiso | Qué |
|---|---|---|---|
| GET | /api/v1 | — | The key itself: workspace, scopes, rate limit. Use it to test a key. |
| GET | /api/v1/cars | cars | Cars of the garage, plus customers' cars with running access and download permission. Sorted by id. |
| GET | /api/v1/cars/{car_id} | cars | One car. |
| GET | /api/v1/cars/{car_id}/codes | codes | Fault code episodes (first seen until cleared), newest first. |
| GET | /api/v1/cars/{car_id}/reports | reports | Inspection reports made in the garage's own workspace (a customer's car: empty list). |
| GET | /api/v1/cars/{car_id}/trips | trips | Trip summaries, newest first. |
Filtros y páginas
Las listas llegan por páginas. Pide la página siguiente con el next_cursor de la respuesta, hasta que sea null. Un cursor nunca salta ni repite una fila, aunque lleguen filas nuevas.
| Parámetro | Qué |
|---|---|
| limit | Rows per page, 1–200. Default 50. |
| cursor | The next_cursor of the previous page. Opaque; pass it back unchanged. |
| from | YYYY-MM-DD, inclusive (UTC). Codes: seen on or after this day. Trips and reports: started/created on or after. |
| to | YYYY-MM-DD, inclusive (the whole day, UTC). Codes: first seen before the end of this day. |
| lang | codes only: language of the description (en, nl, de, fr, es). Default en. |
Respuesta de una lista
{
"data": [
{
"id": "0b9c7d0e-5a3f-4d8e-9c1a-2f6b8e4d7a10",
"code": "P0420",
"description": "Catalyst system efficiency below threshold (bank 1)",
"state": "stored",
"first_seen_at": "2026-10-02T07:41:12.000Z",
"last_seen_at": "2026-10-09T16:05:40.000Z",
"cleared_at": null,
"days_seen": 4
}
],
"next_cursor": "eyJ0IjoiMjAyNi0xMC0wMlQwNzo0MToxMi4wMDBaIiwiaSI6IjBiOWM3ZDBlLi4uIn0"
}El coche de un cliente: sin VIN
{
"data": {
"id": "6f1e2d3c-4b5a-4978-8a6b-5c4d3e2f1a0b",
"access": "shared",
"name": "Golf",
"make": "Volkswagen",
"model": "Golf",
"year": 2019,
"plate": "AB-123-C",
"vin": null,
"access_expires_at": "2026-12-01T09:00:00.000Z",
"created_at": "2026-05-04T10:11:12.000Z",
"updated_at": "2026-11-10T08:00:00.000Z"
}
}Errores
Un error tiene un estado HTTP y un código fijo: {"error": {"code": "…", "message": "…"}}. Básate en el código, no en el mensaje.
| Estado | Código | Qué |
|---|---|---|
| 400 | invalid_parameter | A query parameter is not valid (limit, cursor, from, to). |
| 401 | invalid_key | No key, an unknown key or a revoked key. |
| 403 | plan_required | The garage has no active paid plan. |
| 403 | insufficient_scope | The key does not have the scope of this endpoint. |
| 404 | not_found | Unknown car, or no access to it. The two are deliberately the same. |
| 429 | rate_limited | More than 120 requests in this minute. See Retry-After. |
| 503 | unavailable | Temporarily unavailable. Try again later. |
Límites
Como máximo 120 peticiones por minuto por clave, para todos nuestros servidores juntos. Cada respuesta lleva X-RateLimit-Limit y X-RateLimit-Remaining; por encima del límite recibes 429 con Retry-After en segundos. Obtén los cambios con un periodo (from, to) en lugar de todo cada vez.
Webhooks
El taller introduce una dirección https y elige los eventos, uno a uno o agrupados por hora o por día. Enviamos un POST con JSON, firmado con el secreto del taller.
Sin fatiga de alarmas: un taller solo recibe avisos de una avería confirmada, con el testigo del motor encendido y que persiste, y una sola vez por avería.
Eventos
| code.confirmed | A confirmed code (stored or permanent) with the check-engine light on, not cleared, seen on at least 2 days. Once per episode; again only after clearing and coming back. Pending codes never. |
| access.granted | A customer's access for your garage started (after accepting and, if asked, the owner's confirmation). |
| access.ended | That access ended: revoked by the owner or the garage, or expired. |
| report.created | An inspection report was made for one of the garage's own cars. |
POST https://your-system.example/webhook
Content-Type: application/json
Webhook-Signature: t=1763107200,v1=5f2b…(64 hex)
Webhook-Event: code.confirmed
Webhook-Id: 3a1d…
{
"id": "3a1d…",
"type": "code.confirmed",
"created_at": "2026-11-14T08:00:00.000Z",
"workspace_id": "…",
"data": {
"car_id": "6f1e2d3c-…",
"code": "P0301",
"state": "stored",
"first_seen_at": "2026-11-10T07:02:00.000Z",
"last_seen_at": "2026-11-13T17:45:00.000Z",
"days_seen": 3,
"mil_on": true
}
}
Digest (hourly or daily): one POST with "type": "digest" and "events": [ … ], each with id, type, created_at, data.Comprobar la firma
La cabecera Webhook-Signature contiene t (tiempo Unix en segundos) y v1 (HMAC-SHA256 de "t.body" con el secreto, en hexadecimal). Compara en tiempo constante y rechaza un t de más de 5 minutos, contra la repetición.
// Node.js: check the signature before you trust the body (use the raw body, not re-serialised JSON).
import { createHmac, timingSafeEqual } from "node:crypto";
export function verify(rawBody, header, secret, toleranceSeconds = 300) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const t = Number(parts.t);
if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false; // replay
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
const given = Buffer.from(parts.v1 ?? "", "hex");
return given.length === expected.length && timingSafeEqual(expected, given);
}
// Answer 2xx quickly. Anything else (or no answer within 10 s) is retried, at most 6 attempts.
// Use the "id" to ignore a delivery you already processed.Entrega y reintentos
Responde con un 2xx en menos de 10 segundos. Si no, lo intentamos más tarde (tras 10 minutos, luego 30 minutos, 2, 6 y 24 horas), como máximo 6 veces. Nunca seguimos redirecciones y solo enviamos a direcciones públicas. El taller ve las últimas entregas en Integraciones.
Privacidad: decide el propietario
- El coche de un cliente solo es visible mientras el propietario ha dado acceso al taller, y solo si ha permitido descargar. Revocado o caducado: desaparece de la API al instante.
- Nunca el VIN del coche de un cliente, nunca ubicaciones, nunca el enlace de un informe.
- Cada petición figura en el registro del taller y, para el coche de un cliente, también en el del propietario. Lo que tu sistema ha obtenido se queda en el taller: trátalo como datos personales.
- Solo lectura: la API no puede cambiar nada, ni borrar códigos, ni enviar nada a un coche.
¿Integración lista para un paquete concreto?
Las integraciones con paquetes de taller concretos son bajo petición. Dinos qué paquete usas o desarrollas.