Zum Inhalt springen
SuchenGratis-Konto
Menü
Für Entwickler

API und Webhooks für Werkstattsoftware

Entwickelst du Planungs-, Werkstatt- oder Händlersoftware? Mit einem Schlüssel der Werkstatt liest dein System Autos, Fehlercodes, Berichte und Fahrten und bekommt ein Signal, wenn etwas passiert. Nur lesen, und immer mit Erlaubnis des Halters.

Die technische Referenz (Endpunkte, Felder, Beispiele) ist auf Englisch, wie die API selbst.

So fängst du an

  1. Die Werkstatt hat Car-Z Garage. Inhaber oder Admin öffnen die Werkstatt und den Reiter Anbindungen.
  2. Dort wird ein Schlüssel mit Namen und Leserechten erstellt und einmal in deine Software kopiert.
  3. Deine Software sendet den Schlüssel bei jeder Anfrage mit. Für Signale trägt die Werkstatt dort auch deine Webhook-Adresse ein.

Authentifizierung

Sende den Schlüssel im Header Authorization als Bearer-Token, nur über HTTPS. Nie in einer URL. Ein Schlüssel gehört zu einer Werkstatt; ein widerrufener Schlüssel funktioniert sofort nicht mehr. Wir speichern nur einen Fingerabdruck des Schlüssels; ein verlorener Schlüssel lässt sich nicht wieder anzeigen: Erstelle einen neuen.

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"

Endpunkte

Alle Endpunkte lesen nur (GET), haben die Version im Pfad und antworten mit JSON: feste englische Feldnamen, ISO-8601-Daten in UTC und metrische Einheiten im Feldnamen (distance_km, avg_speed_kmh).

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

Filter und Seiten

Listen kommen in Seiten. Frage die nächste Seite mit dem next_cursor der Antwort ab, bis er null ist. Ein Cursor überspringt oder wiederholt nie eine Zeile, auch wenn neue dazukommen.

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

Antwort einer 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"
}

Ein Kundenauto: keine FIN

{
  "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"
  }
}

Fehler

Ein Fehler hat einen HTTP-Status und einen festen Code: {"error": {"code": "…", "message": "…"}}. Baue auf den Code, nicht auf den Text.

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

Limits

Höchstens 120 Anfragen pro Minute pro Schlüssel, für alle unsere Server zusammen. Jede Antwort hat X-RateLimit-Limit und X-RateLimit-Remaining; über dem Limit gibt es 429 mit Retry-After in Sekunden. Hole Änderungen mit einem Zeitraum (from, to) statt jedes Mal alles.

Webhooks

Die Werkstatt trägt eine https-Adresse ein und wählt die Ereignisse, einzeln oder gebündelt pro Stunde oder pro Tag. Wir senden einen POST mit JSON, signiert mit dem Geheimnis der Werkstatt.

Keine Alarmmüdigkeit: Eine Werkstatt hört nur von einem Fehler, der bestätigt ist, die Motorkontrollleuchte an hat und bleibt, und von jedem Fehler nur einmal.

Ereignisse

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.

Die Signatur prüfen

Der Header Webhook-Signature enthält t (Unix-Zeit in Sekunden) und v1 (HMAC-SHA256 von "t.body" mit dem Geheimnis, hex). Vergleiche in konstanter Zeit und lehne ein t ab, das älter als 5 Minuten ist (gegen Wiederholung).

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

Zustellung und Wiederholung

Antworte innerhalb von 10 Sekunden mit 2xx. Sonst versuchen wir es später erneut (nach 10 Minuten, dann 30 Minuten, 2, 6 und 24 Stunden), höchstens 6-mal. Weiterleitungen folgen wir nie, und wir senden nur an öffentliche Adressen. Die Werkstatt sieht die letzten Zustellungen unter Anbindungen.

Datenschutz: Der Halter entscheidet

  • Ein Kundenauto ist nur sichtbar, solange der Halter der Werkstatt Zugang gegeben hat, und nur wenn er das Herunterladen erlaubt hat. Widerrufen oder abgelaufen heißt: sofort weg aus der API.
  • Nie die FIN eines Kundenautos, nie Standorte, nie den Link eines Berichts.
  • Jede Anfrage steht im Protokoll der Werkstatt, bei einem Kundenauto auch in dem des Halters. Was dein System abgerufen hat, bleibt bei der Werkstatt: Behandle es als personenbezogene Daten.
  • Nur lesen: Die API kann nichts ändern, keine Codes löschen und nichts an ein Auto senden.

Fertige Anbindung an ein bestimmtes Paket?

Anbindungen an bestimmte Werkstattpakete gibt es auf Anfrage. Sag uns, welches Paket du nutzt oder entwickelst.