API V2 Beta
Umstieg von V1 auf V2.
V2 ist die neue Schnittstelle von api4cars: eigene Adresse, ein einheitliches Antwortformat, Fahrzeug-IDs im Pfad und Gutachten mit Auflagen im Klartext. Hier steht, was sich für dich ändert und was zu tun ist.
Stand November 2026 · wird laufend ergänzt
BetaAPI V2 ist in der Beta. Endpunkte und Felder können wir noch erweitern oder anpassen. Änderungen, die bestehende Integrationen betreffen, kündigen wir vorher an. V1 bleibt bis auf Weiteres verfügbar. Was Beta bedeutet
Was sich ändert
V1 und V2 im Vergleich.
Die Passungsurteile nutzen dieselbe Grundlage. Antwortformen und Funktionsgrenzen unterscheiden sich; prüfe die verwendeten Funktionen beim Umstieg.
| Thema | V1 (bisher) | V2 (neu) |
|---|---|---|
| Adresse | https://api4cars.com/wp-json/carapi/v1/ | https://api.api4cars.com/v2/ |
| Zugang | X-API-Key + X-API-Secret (carapi_live_…) | ck_v2_… + X-API-Secret oder Authorization: Bearer key:secret, wie bei V1 von deinem Server aus |
| Fahrzeug | /vehicle?hsn=…&tsn=… | /v2/vehicles/{hsn}-{tsn}, z. B. 0603-COB |
| Fahrzeugauswahl | /brands, /models, /series, /generations, /engines | /v2/brands → /models → /generations → /v2/generations/{id}/engines |
| Typgenehmigung | /vehicle-configurations | /v2/vehicles/{id}/configurations |
| Felgen am Fahrzeug | /compatibility, /fitments | /v2/vehicles/{id}/wheels und /v2/vehicles/{id}/wheels/{code} |
| Felgenkatalog | /wheels | /v2/wheels und /v2/wheels/{code} (mit Farben und Bildern) |
| Gutachten | /gutachten | /v2/documents?wheel_code=… (Liste je Felgencode) und /v2/documents/{id} mit Auflagentexten |
| Typklassen | /insurance | /v2/vehicles/{id}?include=insurance, Liste je Marke oder Modell über /v2/insurance |
| Rückrufe je Fahrzeug | /intelligence/vehicle | /v2/vehicles/{id}?include=safety |
| Marktdaten zum Fahrzeug | /intelligence/vehicle | /v2/vehicles/{id}?include=market,market_history |
| Technische Daten | /workshop-profile | /v2/vehicles/{id}/technical je Variante; technische Angaben je EU-Konfiguration separat aus /configurations. Kein vollständiger Ersatz des Konfigurationsprofils |
| Mehrfahrzeugvergleich | /vehicle-compare | /v2/vehicles/{id}/technical mehrfach abrufen und im Shop zusammenführen |
| Konfigurator-Bilder | /configurator/availability, /images, /layers | /v2/vehicles/{id}/images und /images/{code}, Ebenen mit delivery=layers (Zusatzmodul) |
| Suche | /vehicle-search | /v2/vehicles?q=… und /v2/engine-codes/{code}/vehicles |
| Antwortformat | je Endpunkt unterschiedlich | immer { data, meta }; Listen blättern über meta.next_cursor |
| Fehler | { code, message, data }, z. B. rest_invalid_api_key | { error: { code, message, status } }, z. B. unauthorized |
| Kontingent | im Konto | zusätzlich Header X-RateLimit-*, Retry-After bei 429 und /v2/me |
| Datenstand & Quelle | – | meta.data_version in jeder Antwort, attribution mit Quellenangabe (KBA, dl-de/by-2-0) |
Gleiche Abfrage
Vorher und nachher.
Fahrzeug mit Felgendaten für einen VW Touareg (HSN 0603, TSN COB).
curl -H "X-API-Key: carapi_live_…" \
-H "X-API-Secret: …" \
"https://api4cars.com/wp-json/carapi/v1/compatibility?hsn=0603&tsn=COB"curl -H "X-API-Key: ck_v2_…" \
-H "X-API-Secret: …" \
"https://api.api4cars.com/v2/vehicles/0603-COB/wheels"Funktionsgrenzen
Das musst du im Shop anpassen.
Die vorhandenen V2-Ressourcen ersetzen diese V1-Abrufe in anderer Form.
Werkstattprofil je Konfiguration
Beobachtungen aus /configurations und Variantenprofil aus /technical getrennt anzeigen. Nur bei belegter variant_selection_id zuordnen. engines_unavailable beachten; keine Füllmengen oder Achslasten ergänzen.
V1: /workshop-profile
Mehrfahrzeugvergleich
Technikprofile je Fahrzeug einzeln abrufen und im Shop zusammenführen.
V1: /vehicle-compare
Intelligence
Markt, Bestand, Rückrufe und Umwelt je Fahrzeug über include; keine Scores und keine Filter from, to oder region. Für diese Funktionen und Auswertungslisten über viele Fahrzeuge weiterhin V1 nutzen.
V1: /intelligence/vehicle
Werkstattansicht je Konfiguration
GET /v2/vehicles/{id}/configurations (alle Cursor-Seiten) plus GET /v2/vehicles/{id}/technical. Technische Angaben je EU-Konfiguration mit Einheit, Messbasis, Kontext und Wertebereichen erhalten. selection=cfg_… wird am Technikprofil mit 400 abgewiesen.
// JavaScript-Client auf deinem Server; vehicleId = gewählte HSN-TSN
const technical = (await api.technical(vehicleId)).data;
const profiles = new Map(technical.variants.map(v => [v.selection_id, v]));
for await (const cfg of api.paginate(cursor => api.configurations(vehicleId, { cursor }))) {
console.log({
configuration: cfg.selection_id,
observations: cfg.technical_observations,
variantProfile: cfg.variant_selection_id ? (profiles.get(cfg.variant_selection_id) ?? null) : null,
enginesUnavailable: technical.engines_unavailable
});
}
Beta
Was Beta bei V2 heißt.
V2 ist nutzbar und wächst weiter. Bis zur stabilen Version können sich Details noch ändern. So bleibst du auf der sicheren Seite.
Was kann sich ändern?
Wir ergänzen Endpunkte, Felder und Filter. Vereinzelt passen wir Namen, Formate oder Grenzen an, wenn sich im Einsatz zeigt, dass es besser geht.
Wie erfahre ich davon?
Datierte Änderungen stehen im API-Changelog der Dokumentation (/api-docs/#v2-changelog, Deutsch und Englisch). Änderungen, die eine bestehende Integration betreffen, kündigen wir vorher per E-Mail an alle Konten mit V2-Schlüssel an.
Wie baue ich robust?
Unbekannte Felder ignorieren statt als Fehler werten, Fehler über error.code auswerten und den Stand aus meta.data_version mitloggen. Dann übersteht deine Integration Erweiterungen ohne Anpassung.
Und wenn ich keine Änderungen will?
Dann bleibst du vorerst bei V1. V1 läuft weiter, eine Abschaltung kündigen wir rechtzeitig per E-Mail an.
In fünf Schritten
So stellst du um.
Für die meisten Integrationen ist das eine überschaubare Änderung an einer Stelle im Code.
- 01
V2-Schlüssel selbst anlegen
V2 ist für alle Kunden offen. Lege im Konto einen V2-Server-Schlüssel an. Das Secret wird einmal angezeigt; speichere es sicher auf deinem Server.
- 02
Adresse und Header umstellen
Neue Basis-Adresse, neuer Schlüssel mit Secret. Aufrufe gehen wie bisher über deinen eigenen Server.
- 03
Fahrzeug-ID verwenden
Statt
hsnundtsnals Parameter steht die ID im Pfad:/v2/vehicles/0603-COB. - 04
Antworten anpassen
Nutzdaten liegen in
data, Angaben zum Datenstand inmeta. Listen blätterst du mitcursor. - 05
Fehler und Grenzen behandeln
Neues Fehlerformat prüfen, bei 429 den Wert aus
Retry-Afterabwarten, Quellenangabe ausattributionanzeigen.
Muss ich sofort umsteigen?
Nein. V1 läuft weiter. Einen Termin für die Abschaltung gibt es noch nicht; wir kündigen ihn rechtzeitig per E-Mail an.
Brauche ich neue Zugangsdaten?
Ja. V2 arbeitet mit eigenen Schlüsseln: einem Schlüssel mit Secret, den du in deinem Konto anlegst. Dein V1-Schlüssel funktioniert weiter, und beide zählen gegen dasselbe Kontingent.
Wo sehe ich Grenzen und Änderungen?
Das Mapping beschreibt die Unterschiede bei Konfigurationsprofilen, Vergleichen und Intelligence. Datierte Hinweise stehen im API-Changelog der Dokumentation (Deutsch und Englisch).
Gibt es Hilfe beim Umstieg?
Ja. Es gibt einen kleinen JavaScript-Client für V2, die Beschreibung als OpenAPI-Datei und uns – schreib uns, wenn du eine Integration umstellst.
Bereit für V2
Lege deinen V2-Schlüssel an.
V2 ist für alle Kunden offen. Im Konto legst du deinen Server-Schlüssel mit Secret selbst an.