Dealer-Management-Systeme: Fahrzeugaufnahme und Abgleich über die Schnittstelle

Wo im Prozess Daten fehlen

Ein DMS legt Fahrzeuge an vielen Stellen an: bei der Inzahlungnahme, beim Gebrauchtwagenankauf, bei der Serviceannahme eines Fremdfahrzeugs, beim Import einer Flotte. Jedes Mal liegt eine Zulassungsbescheinigung auf dem Tresen, und jedes Mal überträgt jemand ihre Felder von Hand.

• Inzahlungnahme. Der Kunde sitzt daneben, der Verkäufer tippt Fahrgestellnummer, Erstzulassung und Schlüsselnummern in die Bewertungsmaske. Ein Zahlendreher in der VIN fällt erst auf, wenn die Börse den Datensatz zurückweist.
• Technische Akte. Was der Schein nicht ausweist — Getriebe, Antrieb, Aufbau — wird aus dem Gedächtnis, von einer Herstellerseite oder gar nicht ergänzt. Bei Fremdmarken fehlt der Herstellerzugang ganz.
• Inseratstext. Titel und Beschreibung entstehen aus Textbausteinen, die zum Fahrzeug passen können oder nicht.
• Serviceannahme. Welche Rückrufmaßnahmen für die Baureihe veröffentlicht sind, sucht der Serviceberater in einem Herstellerportal außerhalb des DMS — bei Fremdfahrzeugen oft gar nicht. Ob eine Maßnahme am einzelnen Fahrzeug erledigt ist, beantwortet auch mit Schnittstelle nur das Herstellerportal.
• Teilebestellung. Ob eine OE-Nummer zu genau diesem Fahrzeug passt, entscheidet der Teiledienst nach Katalog und Erfahrung. Bei Bauteilen mit vielen Varianten ist das eine häufige Quelle für Fehlbestellungen.

Was die Schnittstelle liefert

Ein Ablauf von Anfang bis Ende

1. Schein fotografieren. Der Verkäufer fotografiert den Fahrzeugschein in der DMS-App. Das DMS legt die Datei auf dem eigenen Server ab und übergibt ihre Adresse als fileUrl an POST /vehicles/intake; Rundgang-Fotos, bis zu 5 Aufnahmen, gehen als photoUrls mit.
2. Antwort in die Akte schreiben. Dokumentfelder füllen Fahrgestellnummer, Erstzulassung und Typangaben; Fahrzeugdaten samt tapiId füllen die technische Akte; der Zustandsbericht wird angehängt. components sagt je Bestandteil, ob er geliefert wurde; ein nicht gelieferter lässt seine Felder leer und wird anteilig erstattet. Der Abgleich im Intake läuft fest über Provider 2; provider in der Antwort ist immer 2.
3. Provider-1-Abgleich als Alternative. Soll das Fahrzeug stattdessen über Provider 1 abgeglichen werden, antwortet GET /vin/{vin}/vehicle einem Drittsystem mit redirect_required. Das DMS erstellt dann serverseitig mit POST /vin/redirect-sessions eine Session aus vin, der absoluten HTTPS-returnUrl und einem state für den eigenen Vorgang und leitet den Verkäufer auf die redirectUrl.
4. Rücksprung verarbeiten. Nach dem Abgleich in der tapinoma-Oberfläche kommt der Verkäufer auf die returnUrl zurück — mit status=completed, tapiId und state, oder mit status=cancelled. Fahrzeug-, Ausstattungs- oder Zugangsdaten stehen nie im Redirect; die Session verfällt nach zehn Minuten.
5. Fahrzeugdaten nachladen. Mit der gespeicherten tapiId ruft das DMS GET /vehicles/{tapiId} als Bestandteil des zuvor bezahlten VIN-Ablaufs ab — ohne VIN und ohne Ausstattung.
6. Inserat erzeugen. POST /vehicles/{tapiId}/listing mit language und optionalen Händlernotizen in notes liefert Titel, Beschreibung und Ausstattungs-Highlights. Der Text erfindet keine Eigenschaften und nennt weder Preis noch Zustand.
7. Service vorbereiten. GET /recalls/vehicles/{vin} listet Maßnahmen zur Baureihe aus den amtlichen Registern. Voraussetzung: Die VIN wurde zuvor über POST /vehicles/intake oder einen VIN-Ablauf dieses Clients abgeglichen, denn sie wird nur aus dem eigenen Bestand aufgelöst, nicht beim Lieferanten; sonst antwortet der Endpunkt mit 404 vin_not_resolvable. Die kaufmännische Behandlung richtet sich nach den vor dem Auftrag angezeigten und vertraglich vereinbarten Konditionen. Ob eine Maßnahme am einzelnen Fahrzeug erledigt ist, sagt weiterhin nur der Hersteller. Vor einer Teilebestellung prüft POST /vin/cart-check bis zu 30 OE-Positionen gegen das Fahrzeug (mode=vehicle) oder den Typ (mode=type); bei Steuergeräten bleibt die Codierung Sache der Werkstatt, siehe Gebrauchte Steuergeräte: Codierung, Wegfahrsperre, Angebot.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <VORGANGSNUMMER>' \
  -d '{"fileUrl": "https://dms.example/scheine/4711.pdf", "photoUrls": ["https://dms.example/fotos/4711-front.jpg"]}' \
  'https://api.tapinomahub.com/vehicles/intake'

Der Einbau

1. Schlüssel serverseitig hinterlegen. Der API-Key geht als Header X-Api-Key vom DMS-Backend aus und gehört in dessen Konfiguration — nie in die Browser-Oberfläche, nie in eine mobile App, nie in den Quelltext.
2. Einen Endpunkt wählen. POST /vehicles/intake ist der naheliegende Einstieg, weil er die Fahrzeugaufnahme in einem Aufruf abdeckt. Wer nur den Schein lesen will, beginnt mit POST /scanner/document/registration.
3. Feldzuordnung festlegen. Welches Antwortfeld landet in welchem Feld der Akte? Diese Abbildung ist die eigentliche Arbeit. Die Akte braucht zusätzlich ein Feld für die tapiId und einen Vermerk, welche Werte aus der Abfrage stammen.
4. Leerbefund und Fehler unterscheiden. 404 vehicle_not_found ist kein Fehler, sondern ein Ergebnis: nicht gefunden. Das DMS legt die Akte trotzdem an, lässt die Felder leer und erzeugt eine Nacharbeit — „kein Treffer“ erscheint dem Anwender nie als rote Fehlermeldung. Ein Verbindungsabbruch dagegen darf wiederholt werden, mit demselben Idempotency-Key.
5. Lang laufende Vorgänge abholen. Antwortet ein Endpunkt mit 202, nennen Location und Retry-After Job und Wartezeit. Der Status wird am Job-Endpunkt abgeholt, bei der Teileprüfung über GET /vin/cart-check/jobs/{jobId} — nicht durch einen zweiten Aufruf des Ausgangsendpunkts.
6. Ausrollen und beobachten. Zuerst ein Pilothaus, dann die Fläche. GET /client/usage und der Antwortheader X-Tapinoma-Usage-Warning zeigen den Guthabenverbrauch. Den Weg von Vertrag bis Go-live beschreibt der Integrationsleitfaden.

Worauf zu achten ist

• `Idempotency-Key` setzen. Bricht eine Verbindung ab, wiederholt das DMS den Aufruf mit demselben Schlüssel und erhält dieselbe Antwort, erkennbar am Header X-Tapinoma-Idempotent-Replay. Ausnahme sind Aufrufe, die einen geheimen Schlüssel ausgeben (Unter-Nutzer, Partner-Workspaces): nach einem Timeout den Bestand abgleichen statt blind wiederholen.
• Leere Felder leer lassen. Liefert die Antwort null, bleibt das Feld leer — kein Standardwert, keine Ableitung aus der Weltherstellerkennung. Eine plausible Angabe im Inserat ist gefährlicher als eine sichtbare Lücke.
• `tapiId` speichern. Sie ist stabil und der Schlüssel zu GET /vehicles/{tapiId} und POST /vehicles/{tapiId}/listing. Wer sie verliert, bezahlt den Abgleich erneut.
• Schlüssel nie im Browser. Die Oberfläche spricht mit dem eigenen Backend, das Backend mit der Schnittstelle. Auch die Redirect-Session für Provider 1 entsteht serverseitig; der Browser sieht nur die redirectUrl.
• Rate-Limits je Nutzer setzen. PUT /client/users/{clientId}/rate-limits begrenzt je Nutzer, Schlüssel oder Endpunkt, damit ein fehlerhafter Import nicht das Guthaben des ganzen Hauses aufbraucht.
• Ergebnis prüfen lassen. Inseratstext, Rückrufliste und Passungsaussage sind Arbeitshilfen. Der Verkäufer liest den Text vor der Ausspielung, der Serviceberater prüft die baureihenbezogenen Rückrufe gegen das Herstellerportal, und complete=false heißt, dass ein Nein nicht abschließend ist.

Was die Schnittstelle nicht tut

Die Schnittstelle liefert keine Bewertung und kein Gutachten: Der Zustandsbericht aus POST /vehicles/intake beschreibt Sichtbares, er kalkuliert weder Reparatur noch Restwert. Sie führt keine Halterabfrage durch und gibt keine Preisgarantie — der Inseratstext nennt bewusst keinen Preis. Provider 1 ist für Drittsysteme nur über den Browser-Redirect erreichbar. Und sie verkauft keinen Datenbestand: Geschuldet ist die Abfrage beziehungsweise Analyse mit ihrem Ergebnis; die Verwendung liegt beim Autohaus. Was das Material nicht hergibt, bleibt eine Lücke — warum, steht in VIN-Abfrage in der Praxis: Ablauf, Ergebnis, Abrechnung.