API e webhooks para software de oficina
Você cria software de agendamento, de oficina ou de concessionária? Com uma chave da oficina, seu sistema lê carros, códigos de falha, relatórios e viagens, e recebe um sinal quando algo acontece. Somente leitura, e sempre com a permissão do dono do carro.
A referência técnica (endpoints, campos, exemplos) está em inglês, assim como a própria API.
Primeiros passos
- A oficina tem o Car-Z Garage. O dono ou um admin abre a oficina e a aba Integrações.
- Ele cria uma chave com um nome e o que ela pode ler, e a copia uma única vez no seu software.
- Seu software envia a chave em cada requisição. Para sinais, a oficina também informa ali o endereço do seu webhook.
Autenticação
Envie a chave no header Authorization como Bearer token, somente via HTTPS. Nunca em uma URL. Uma chave pertence a uma oficina; uma chave revogada para de funcionar na hora. Guardamos apenas uma impressão digital da chave, então uma chave perdida não pode ser mostrada de novo: crie uma nova.
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 os endpoints são somente leitura (GET), versionados no caminho, e respondem em JSON com nomes de campo fixos em inglês, datas ISO 8601 em UTC e unidades métricas no nome do campo (distance_km, avg_speed_kmh).
| Método | Caminho | Escopo | O 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 e páginas
Listas vêm em páginas. Peça a próxima página com o next_cursor da resposta, até que seja null. Um cursor nunca pula nem repete uma linha, mesmo quando chegam linhas novas.
| Parâmetro | O 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. |
Resposta de uma 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"
}Carro de um cliente: sem 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"
}
}Erros
Um erro tem um status HTTP e um código fixo: {"error": {"code": "…", "message": "…"}}. Baseie-se no código, não na mensagem.
| Status | Código | O 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. |
Limites de requisições
No máximo 120 requisições por minuto por chave, somando todos os nossos servidores. Toda resposta tem X-RateLimit-Limit e X-RateLimit-Remaining; acima do limite, você recebe 429 com Retry-After em segundos. Busque alterações com um período (from, to) em vez de tudo a cada vez.
Webhooks
A oficina informa um endereço https e escolhe os eventos, e se eles chegam um a um ou agrupados por hora ou por dia. Enviamos um POST com JSON, assinado com o segredo da oficina.
Sem excesso de alertas: a oficina só fica sabendo de uma falha confirmada, com a luz da injeção acesa e que persiste, e de cada falha apenas uma vez.
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.Verificar a assinatura
O header Webhook-Signature tem t (horário Unix em segundos) e v1 (HMAC-SHA256 de "t.body" com o segredo, em hex). Compare em tempo constante e recuse um t com mais de 5 minutos, contra replay.
// 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 e novas tentativas
Responda com um 2xx em até 10 segundos. Caso contrário, tentamos de novo mais tarde (após 10 minutos, depois 30 minutos, 2, 6 e 24 horas), no máximo 6 vezes. Nunca seguimos um redirecionamento e só enviamos para endereços públicos. A oficina vê as últimas entregas em Integrações.
Privacidade: o dono decide
- O carro de um cliente só fica visível enquanto o dono der acesso à oficina, e somente se o dono permitiu o download. Revogado ou expirado significa: some da API na hora.
- Nunca o VIN do carro de um cliente, nunca localizações, nunca o link de um relatório.
- Cada requisição fica no registro da oficina e, no caso do carro de um cliente, também no do dono. O que seu sistema buscou fica com a oficina: trate como dado pessoal.
- Somente leitura: a API não pode alterar nada, apagar códigos nem enviar nada para um carro.
Integração pronta com um software específico?
Integrações com softwares específicos de oficina são sob consulta. Conte para a gente qual software você usa ou desenvolve.