API en webhooks voor garagesoftware
Maak je plannings-, werkplaats- of dealersoftware? Met een sleutel van de garage leest je systeem auto's, foutcodes, rapporten en ritten, en krijgt het een seintje als er iets gebeurt. Alleen lezen, en altijd met toestemming van de autobezitter.
De technische referentie (endpoints, velden, voorbeelden) is in het Engels, net als de API zelf.
Zo begin je
- De garage heeft Car-Z Garage. De eigenaar of een beheerder opent de garage en het tabblad Koppelingen.
- Die maakt een sleutel met een naam en wat hij mag lezen, en kopieert hem één keer naar jouw software.
- Jouw software stuurt de sleutel mee met elke aanvraag. Voor seintjes vult de garage daar ook jouw webhookadres in.
Authenticatie
Stuur de sleutel in de header Authorization als Bearer-token, alleen via HTTPS. Nooit in een URL. Eén sleutel hoort bij één garage; een ingetrokken sleutel werkt meteen niet meer. Wij bewaren alleen een vingerafdruk van de sleutel, dus een kwijtgeraakte sleutel is niet terug te halen: maak een nieuwe.
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
Alle endpoints lezen alleen (GET), hebben de versie in het pad en antwoorden met JSON: vaste Engelse veldnamen, ISO 8601-datums in UTC en metrische eenheden in de veldnaam (distance_km, avg_speed_kmh).
| Methode | Pad | Recht | Wat |
|---|---|---|---|
| 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. |
Filters en pagina's
Lijsten komen in pagina's. Vraag de volgende pagina op met de next_cursor uit het antwoord, tot die null is. Een cursor slaat nooit een regel over en herhaalt er geen, ook niet als er nieuwe bijkomen.
| Parameter | Wat |
|---|---|
| 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. |
Antwoord van een lijst
{
"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"
}Een auto van een klant: geen 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"
}
}Fouten
Een fout heeft een HTTP-status en een vaste code: {"error": {"code": "…", "message": "…"}}. Bouw op de code, niet op de tekst.
| Status | Code | Wat |
|---|---|---|
| 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. |
Limieten
Maximaal 120 aanvragen per minuut per sleutel, voor al onze servers samen. Elk antwoord heeft X-RateLimit-Limit en X-RateLimit-Remaining; boven de grens krijg je 429 met Retry-After in seconden. Haal wijzigingen op met een periode (from, to) in plaats van elke keer alles.
Webhooks
De garage vult één https-adres in en kiest de meldingen, en of ze los komen of gebundeld per uur of per dag. Wij sturen een POST met JSON, ondertekend met het geheim van de garage.
Geen alarmmoeheid: een garage hoort alleen van een storing die bevestigd is, het motorlampje aan heeft en blijft, en van elke storing maar één keer.
Meldingen
| 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.De handtekening controleren
De header Webhook-Signature bevat t (Unix-tijd in seconden) en v1 (HMAC-SHA256 van "t.body" met het geheim, in hex). Vergelijk in constante tijd en weiger een t ouder dan 5 minuten, tegen herhaalaanvallen.
// 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.Aflevering en opnieuw proberen
Antwoord binnen 10 seconden met een 2xx. Anders proberen we het later opnieuw (na 10 minuten, dan 30 minuten, 2, 6 en 24 uur), maximaal 6 keer. We volgen nooit een doorverwijzing en sturen alleen naar openbare adressen. De garage ziet de laatste afleveringen bij Koppelingen.
Privacy: de eigenaar beslist
- Een auto van een klant is alleen zichtbaar zolang de eigenaar de garage toegang heeft gegeven, en alleen als de eigenaar downloaden heeft toegestaan. Ingetrokken of verlopen betekent: meteen weg uit de API.
- Nooit het VIN van een auto van een klant, nooit locaties, nooit de link van een rapport.
- Elke aanvraag staat in het logboek van de garage, en bij een auto van een klant ook in dat van de eigenaar. Wat je systeem heeft opgehaald, blijft bij de garage: behandel het als persoonsgegevens.
- Alleen lezen: de API kan niets wijzigen, geen codes wissen en niets naar een auto sturen.
Kant-en-klare koppeling met een specifiek pakket?
Koppelingen met specifieke garagepakketten zijn op aanvraag. Laat weten welk pakket je gebruikt of bouwt.