Fahrzeugbörsen und Inseratsportale: Inserate aus dem Fahrzeugabgleich statt aus dem Abtippen

Wo im Prozess Daten fehlen

Ein Inserat ist so gut wie das, was der Anbieter beim Einstellen eingibt — selten vollständig, nicht immer richtig. Was fehlt, kostet Sichtbarkeit im Filter und Vertrauen beim Käufer; was falsch ist, kostet Rückfragen und Rücktritte. Die typischen Stellen:

• Einstellen. Der Anbieter tippt Fahrgestellnummer, Erstzulassung und Schlüsselnummern aus der Zulassungsbescheinigung ab. Ein Zahlendreher in der VIN fällt erst auf, wenn ein Käufer die Nummer mit dem Fahrzeug vergleicht; bei ausländischen Dokumenten fehlt oft schon die Zuordnung der Felder.
• Filterfelder. Getriebe, Antrieb, Aufbau und Motorisierung stehen nicht vollständig im Schein. Was der Anbieter nicht einträgt, bleibt leer, und das Inserat erscheint in der Suche nicht.
• Inseratstext. Titel und Beschreibung entstehen aus Textbausteinen oder werden aus dem letzten Inserat kopiert — samt Ausstattung, die dieses Fahrzeug nicht hat.
• Fotos. Aufnahmen vom Hof mit Nachbarfahrzeugen im Hintergrund, uneinheitlich und oft mit lesbarem Kennzeichen. Ob eines lesbar ist, wird vor der Veröffentlichung selten geprüft; das Abdecken selbst bleibt Sache des Portals.
• Zustand und Rückrufe. Zustandsangaben stammen vom Anbieter und sind nicht belegt; ob zur Baureihe eine Rückrufmaßnahme vorliegt, weiß weder das Portal noch der Käufer.

Was die Schnittstelle liefert

Ein Ablauf von Anfang bis Ende

1. Dokument fotografieren. Der Anbieter fotografiert die Zulassungsbescheinigung; das Portal-Backend legt die Datei ab und übergibt ihre Adresse als fileUrl an POST /scanner/document/registration/international — für deutsche Scheine genügt POST /scanner/document/registration. Die Fahrzeugfelder füllen die Maske vor; Namen, Adressen, Kennzeichen und VIN werden nie übersetzt, und die Halterfelder übernimmt das Portal nicht, siehe Daten im Altfahrzeug: Was im Infotainment bleibt, wenn das Fahrzeug geht.
2. Fahrzeugabgleich starten. Für Provider 1 antwortet GET /vin/{vin}/vehicle einem Drittsystem mit redirect_required. Das Backend erstellt deshalb mit POST /vin/redirect-sessions eine Session aus vin, der absoluten HTTPS-returnUrl und einem state mit der eigenen Inseratsnummer und leitet den Anbieter auf die redirectUrl. Provider 2 und 3 sind direkt abfragbar.
3. Rücksprung verarbeiten. Nach dem Abgleich in der tapinoma-Oberfläche kommt der Anbieter 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. Das Portal speichert die tapiId am Inserat.
4. Filterfelder und Text füllen. GET /vehicles/{tapiId} liefert die technischen Fahrzeugdaten als Bestandteil des zuvor bezahlten VIN-Ablaufs, ohne VIN und ohne Ausstattung. POST /vehicles/{tapiId}/listing mit language und optionalen Händlernotizen in notes liefert Titel, Beschreibung und Ausstattungs-Highlights — ohne erfundene Eigenschaften, ohne Preis, ohne Zustandsaussage.
5. Rundgang aufnehmen. Bis zu 8 Aufnahmen gehen an POST /vision/condition-report; zurück kommen Befunde je Zone in fester Reihenfolge und eine Gesamteinstufung A, B oder C. POST /vehicles/intake fasst Dokument, Fahrzeugabgleich und Zustandsbericht in einem Aufruf zusammen — der Abgleich läuft dort fest über Provider 2 ohne Redirect, und photoUrls nimmt bis zu fünf Aufnahmen.
6. Fotos aufbereiten. POST /vision/vehicle/remove/bg stellt das Fahrzeug frei; das Modell bestimmt nur den Umriss, die Bildpunkte bleiben die der Aufnahme, siehe Freistellen ohne Neuzeichnen. POST /vision/license-plate sagt, ob und welches Kennzeichen auf einer Aufnahme lesbar ist — Zeichen, Land, vorne oder hinten; er liefert keine Bildkoordinaten und macht nichts unkenntlich. Meldet er ein lesbares Kennzeichen, hält das Portal die Freigabe an; das Abdecken bleibt eine eigene Leistung des Portals.
7. Rückrufhinweis anzeigen. GET /recalls/vehicles/{vin} gleicht die Baureihe gegen die amtlichen Register ab — Kraftfahrt-Bundesamt, EU Safety Gate, NHTSA. Die VIN wird nur aus dem eigenen Bestand aufgelöst, ein Lieferantenabruf findet nicht statt. Das Portal zeigt den Hinweis als Arbeitshilfe am Inserat.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <UUID_JE_VORGANG>' \
  -d '{"language": "de", "notes": "Anhängerkupplung nachgerüstet"}' \
  'https://api.tapinomahub.com/vehicles/<TAPI_ID>/listing'

Der Einbau

1. Schlüssel serverseitig hinterlegen. Der API-Key geht als Header X-Api-Key vom Portal-Backend aus und gehört in dessen Konfiguration — nie in die Einstellmaske im Browser, nie in den Quelltext.
2. Einen Endpunkt wählen. Das Auslesen des Zulassungsdokuments beim Einstellen ist der naheliegende Einstieg, weil es sofort Tippfehler ersetzt. Der Inseratstext über POST /vehicles/{tapiId}/listing setzt einen abgeschlossenen VIN-Ablauf voraus und kommt danach.
3. Feldzuordnung festlegen. Welches Antwortfeld landet in welchem Inseratsfeld? Diese Abbildung ist die eigentliche Arbeit. Das Inserat 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 Portal legt das Inserat trotzdem an, lässt die Felder leer und bittet den Anbieter um Ergänzung — nie als rote Fehlermeldung; status=cancelled beim Rücksprung ist ebenfalls keiner. 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 zugehörigen Job-Endpunkt abgeholt, nicht durch einen zweiten Aufruf des Ausgangsendpunkts.
6. Ausrollen und beobachten. Zuerst ein Anbieter mit überschaubarem Bestand, 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. Empfohlen ist eine UUID je fachlichem Vorgang, mindestens 8 Zeichen, etwa inserat-<nr>-listing-<uuid> — nicht die Inseratsnummer allein, weil ein Schlüssel nach dem ersten Erfolg als vervollständigt gilt und Dokumentauslesen, Redirect-Session und Inseratstext sonst dieselbe gespeicherte Antwort erhielten. Nach einem Verbindungsabbruch wiederholt das Backend den Aufruf mit demselben Schlüssel und erhält dieselbe Antwort, erkennbar am Header X-Tapinoma-Idempotent-Replay; gespeichert wird 24 Stunden lang und nur bei Erfolg. 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, kein Textbaustein, keine Ableitung aus ähnlichen Inseraten. Eine plausible Ausstattung im Inserat ist gefährlicher als eine sichtbare Lücke, weil der Käufer sie als Zusage liest.
• `tapiId` speichern. Sie ist stabil und der Schlüssel zu GET /vehicles/{tapiId} und POST /vehicles/{tapiId}/listing. Ergebnisse gehören in die Datenbank des Portals, nicht in jeden Seitenaufruf; jede Anfrage kostet.
• Schlüssel nie im Browser. Die Einstellmaske spricht mit dem Portal-Backend, das Backend mit der Schnittstelle. Auch die Redirect-Session für Provider 1 entsteht serverseitig; der Browser sieht nur die redirectUrl, und beim Rücksprung prüft das Backend, dass state zu einem eigenen Vorgang gehört.
• Rate-Limits je Anbieter setzen. PUT /client/users/{clientId}/rate-limits begrenzt je Nutzer, Schlüssel oder Endpunkt, damit ein fehlerhafter Bestandsimport eines Händlers nicht das Guthaben des Portals aufbraucht.
• Ergebnis prüfen lassen. Inseratstext, Zustandsbericht, freigestelltes Bild und Rückrufhinweis sind Arbeitshilfen. Der Anbieter liest den Text und sichtet die Bilder vor der Veröffentlichung; der Rückrufhinweis gilt für die Baureihe, nicht als Nachweis für dieses Fahrzeug.

Was die Schnittstelle nicht tut

Die Schnittstelle bewertet kein Fahrzeug und nennt keinen Preis — der Inseratstext enthält bewusst keinen, und eine Preisgarantie gibt es nicht. Der Zustandsbericht aus POST /vision/condition-report beschreibt Sichtbares und ist kein Gutachten; er kalkuliert weder Reparatur noch Restwert, siehe Unfallfahrzeuge: Totalschaden, Restwert und was für den Verwerter zählt. Zum Kennzeichen gibt es keine Halterabfrage, keinen Registerabgleich und keine Unkenntlichmachung — POST /vision/license-plate macht Kennzeichen lesbar, nicht unkenntlich. 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 Verantwortung für das Inserat bleibt beim Anbieter. Was das Material nicht hergibt, bleibt eine Lücke — warum, steht in VIN-Abfrage in der Praxis: Ablauf, Ergebnis, Abrechnung.