Ir al contenido
BuscarCuenta gratis
Menú
Para desarrolladores

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

  1. El taller tiene Car-Z Garage. El propietario o un administrador abre el taller y la pestaña Integraciones.
  2. Crea una clave con un nombre y lo que puede leer, y la copia una vez en tu software.
  3. 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.com/api/v1 \
  -H "Authorization: Bearer $CARZ_API_KEY"

List cars (first page of 100)

curl -s "https://car-z.com/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.com/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.com/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étodoRutaPermisoQué
GET/api/v1—The key itself: workspace, scopes, rate limit. Use it to test a key.
GET/api/v1/carscarsCars of the garage, plus customers' cars with running access and download permission. Sorted by id.
GET/api/v1/cars/{car_id}carsOne car.
GET/api/v1/cars/{car_id}/codescodesFault code episodes (first seen until cleared), newest first.
GET/api/v1/cars/{car_id}/reportsreportsInspection reports made in the garage's own workspace (a customer's car: empty list).
GET/api/v1/cars/{car_id}/tripstripsTrip 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ámetroQué
limitRows per page, 1–200. Default 50.
cursorThe next_cursor of the previous page. Opaque; pass it back unchanged.
fromYYYY-MM-DD, inclusive (UTC). Codes: seen on or after this day. Trips and reports: started/created on or after.
toYYYY-MM-DD, inclusive (the whole day, UTC). Codes: first seen before the end of this day.
langcodes 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.

EstadoCódigoQué
400invalid_parameterA query parameter is not valid (limit, cursor, from, to).
401invalid_keyNo key, an unknown key or a revoked key.
403plan_requiredThe garage has no active paid plan.
403insufficient_scopeThe key does not have the scope of this endpoint.
404not_foundUnknown car, or no access to it. The two are deliberately the same.
429rate_limitedMore than 120 requests in this minute. See Retry-After.
503unavailableTemporarily 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.confirmedA 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.grantedA customer's access for your garage started (after accepting and, if asked, the owner's confirmation).
access.endedThat access ended: revoked by the owner or the garage, or expired.
report.createdAn 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.