Zum Inhalt springen

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.

ThemaV1 (bisher)V2 (neu)
Adressehttps://api4cars.com/wp-json/carapi/v1/https://api.api4cars.com/v2/
ZugangX-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
Antwortformatje Endpunkt unterschiedlichimmer { 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
Kontingentim Kontozusä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).

V1
curl -H "X-API-Key: carapi_live_…" \
     -H "X-API-Secret: …" \
     "https://api4cars.com/wp-json/carapi/v1/compatibility?hsn=0603&tsn=COB"
V2
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.

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

  2. 02

    Adresse und Header umstellen

    Neue Basis-Adresse, neuer Schlüssel mit Secret. Aufrufe gehen wie bisher über deinen eigenen Server.

  3. 03

    Fahrzeug-ID verwenden

    Statt hsn und tsn als Parameter steht die ID im Pfad: /v2/vehicles/0603-COB.

  4. 04

    Antworten anpassen

    Nutzdaten liegen in data, Angaben zum Datenstand in meta. Listen blätterst du mit cursor.

  5. 05

    Fehler und Grenzen behandeln

    Neues Fehlerformat prüfen, bei 429 den Wert aus Retry-After abwarten, Quellenangabe aus attribution anzeigen.

FAQ

Fragen zum Umstieg

Deine Frage fehlt? Schreib uns.

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.