Pular para o conteúdo
BuscarConta grátis
Menu
Para desenvolvedores

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

  1. A oficina tem o Car-Z Garage. O dono ou um admin abre a oficina e a aba Integrações.
  2. Ele cria uma chave com um nome e o que ela pode ler, e a copia uma única vez no seu software.
  3. 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étodoCaminhoEscopoO quê
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 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âmetroO quê
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.

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.

StatusCódigoO quê
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.

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.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.

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.