API et webhooks pour logiciels de garage
Tu développes un logiciel de planning, d'atelier ou de concession ? Avec une clé du garage, ton système lit les voitures, codes défaut, rapports et trajets, et reçoit un signal quand il se passe quelque chose. Lecture seule, et toujours avec l'accord du propriétaire.
La référence technique (endpoints, champs, exemples) est en anglais, comme l'API elle-même.
Pour commencer
- Le garage a Car-Z Garage. Le propriétaire ou un administrateur ouvre le garage et l'onglet Connexions.
- Il crée une clé avec un nom et ce qu'elle peut lire, et la copie une fois dans ton logiciel.
- Ton logiciel envoie la clé avec chaque requête. Pour les signaux, le garage y saisit aussi ton adresse de webhook.
Authentification
Envoie la clé dans l'en-tête Authorization comme jeton Bearer, uniquement en HTTPS. Jamais dans une URL. Une clé appartient à un seul garage ; une clé révoquée cesse de fonctionner immédiatement. Nous ne gardons qu'une empreinte de la clé : une clé perdue ne peut pas être réaffichée, crée-en une nouvelle.
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
Tous les endpoints sont en lecture seule (GET), versionnés dans le chemin et répondent en JSON : noms de champs fixes en anglais, dates ISO 8601 en UTC et unités métriques dans le nom du champ (distance_km, avg_speed_kmh).
| Méthode | Chemin | Droit | Quoi |
|---|---|---|---|
| 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. |
Filtres et pages
Les listes arrivent par pages. Demande la page suivante avec le next_cursor de la réponse, jusqu'à ce qu'il soit null. Un curseur ne saute ni ne répète jamais une ligne, même si de nouvelles arrivent.
| Paramètre | Quoi |
|---|---|
| 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. |
Réponse d'une liste
{
"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"
}La voiture d'un client : pas de 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"
}
}Erreurs
Une erreur a un statut HTTP et un code fixe : {"error": {"code": "…", "message": "…"}}. Appuie-toi sur le code, pas sur le message.
| Statut | Code | Quoi |
|---|---|---|
| 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
Au plus 120 requêtes par minute et par clé, pour l'ensemble de nos serveurs. Chaque réponse a X-RateLimit-Limit et X-RateLimit-Remaining ; au-delà, tu reçois 429 avec Retry-After en secondes. Récupère les changements avec une période (from, to) plutôt que tout à chaque fois.
Webhooks
Le garage saisit une adresse https et choisit les événements, à l'unité ou regroupés par heure ou par jour. Nous envoyons un POST en JSON, signé avec le secret du garage.
Pas de fatigue d'alarme : un garage n'est prévenu que d'un défaut confirmé, avec voyant moteur allumé et qui persiste, et une seule fois par défaut.
Événements
| 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.Vérifier la signature
L'en-tête Webhook-Signature contient t (temps Unix en secondes) et v1 (HMAC-SHA256 de « t.body » avec le secret, en hexadécimal). Compare en temps constant et refuse un t de plus de 5 minutes, contre le rejeu.
// 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.Livraison et nouvelles tentatives
Réponds par un 2xx en moins de 10 secondes. Sinon nous réessayons plus tard (après 10 minutes, puis 30 minutes, 2, 6 et 24 heures), au plus 6 fois. Nous ne suivons jamais de redirection et n'envoyons qu'à des adresses publiques. Le garage voit les dernières livraisons dans Connexions.
Vie privée : le propriétaire décide
- La voiture d'un client n'est visible que tant que le propriétaire a donné l'accès au garage, et seulement s'il a autorisé le téléchargement. Révoqué ou expiré : aussitôt absent de l'API.
- Jamais le VIN de la voiture d'un client, jamais de localisation, jamais le lien d'un rapport.
- Chaque requête figure au journal du garage et, pour la voiture d'un client, aussi dans celui du propriétaire. Ce que ton système a récupéré reste au garage : traite-le comme des données personnelles.
- Lecture seule : l'API ne peut rien modifier, ni effacer de codes, ni rien envoyer à une voiture.
Connexion prête à l'emploi avec un logiciel précis ?
Les connexions avec des logiciels de garage précis sont sur demande. Dis-nous quel logiciel tu utilises ou développes.