API e webhooks para software de oficina
Desenvolves software de planeamento, de oficina ou para concessionários? Com uma chave da oficina, o teu sistema lê carros, códigos de avaria, relatórios e viagens, e recebe um sinal quando algo acontece. Só leitura, e sempre com a autorização do dono do carro.
A referência técnica (endpoints, campos, exemplos) está em inglês, tal como a própria API.
Primeiros passos
- A oficina tem o Car-Z Garage. O proprietário ou um admin abre a oficina e o separador Integrações.
- Cria uma chave com um nome e aquilo que pode ler, e copia-a uma vez para o teu software.
- O teu software envia a chave em cada pedido. Para os sinais, a oficina indica também aí o endereço do teu webhook.
Autenticação
Envia a chave no cabeçalho Authorization como Bearer token, apenas por HTTPS. Nunca num URL. Uma chave pertence a uma oficina; uma chave revogada deixa de funcionar de imediato. Guardamos apenas uma impressão digital da chave, por isso uma chave perdida não pode ser mostrada de novo: cria uma nova.
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 os endpoints são só de leitura (GET), têm a versão no caminho e respondem em JSON com nomes de campos 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 | Âmbito | 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
As listas vêm em páginas. Pede a página seguinte com o next_cursor da resposta, até ser null. Um cursor nunca salta 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"
}O 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 estado HTTP e um código fixo: {"error": {"code": "…", "message": "…"}}. Baseia-te no código, não na mensagem.
| Estado | 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 pedidos
No máximo 120 pedidos por minuto por chave, para todos os nossos servidores em conjunto. Cada resposta tem X-RateLimit-Limit e X-RateLimit-Remaining; acima do limite recebes 429 com Retry-After em segundos. Obtém as alterações com um período (from, to) em vez de tudo de cada vez.
Webhooks
A oficina indica um endereço https e escolhe os eventos, e se chegam um a um ou agrupados por hora ou por dia. Enviamos um POST com JSON, assinado com o segredo da oficina.
Sem fadiga de alarmes: uma oficina só é avisada de uma avaria confirmada, com a luz do motor acesa e que se mantém, e de cada avaria 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 cabeçalho Webhook-Signature tem t (hora Unix em segundos) e v1 (HMAC-SHA256 de "t.body" com o segredo, em hex). Compara em tempo constante e recusa um t com mais de 5 minutos, contra repetição.
// 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
Responde com um 2xx em 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: quem decide é o dono
- O carro de um cliente só é visível enquanto o dono der acesso à oficina, e apenas se o dono permitir a transferência. Revogado ou expirado significa: desaparece da API de imediato.
- Nunca o VIN do carro de um cliente, nunca localizações, nunca o link de um relatório.
- Cada pedido fica no registo da oficina e, no caso do carro de um cliente, também no do dono. O que o teu sistema obteve fica com a oficina: trata-o como dados pessoais.
- Só leitura: a API não pode alterar nada, apagar códigos nem enviar nada para um carro.
Ligação pronta a usar com um pacote específico?
Ligações a pacotes de oficina específicos estão disponíveis mediante pedido. Diz-nos que pacote usas ou desenvolves.