Leasinggesellschaften und Remarketing: Rücknahme, Zustand und Inserat über die Schnittstelle

Wo im Prozess Daten fehlen

Eine Rücknahme ist ein kurzer Termin mit vielen Übertragungen: Der Fahrzeugschein wird fotografiert und später abgetippt, der Zustand in ein Freitextfeld geschrieben, das Inserat aus dem Vertragsdatensatz zusammengesetzt — der nicht immer das Fahrzeug beschreibt, das tatsächlich zurückkam. An fünf Stellen entstehen regelmäßig Lücken:

• Bei der Annahme. Fahrgestellnummer aus Vertrag und Schein werden nicht abgeglichen; Tippfehler fallen erst auf, wenn das Inserat online ist oder die Abmeldung scheitert.
• Beim Zustandsprotokoll. Jeder Standort fotografiert und beschreibt anders. Zwei Berichte zum selben Schaden sind nicht vergleichbar, und ein Käufer auf der Auktionsplattform kann sich auf keinen verlassen.
• Beim Inserat. Titel, Beschreibung und Ausstattungsliste werden je Fahrzeug von Hand formuliert — und für jeden Zielmarkt noch einmal in einer anderen Sprache.
• Vor der Freigabe. Ob für die Baureihe eine offene Rückrufaktion besteht, prüft niemand systematisch, obwohl das Fahrzeug an einen neuen Halter geht.
• Am Ende der Kette. Nicht mehr vermarktbare Fahrzeuge gehen ohne Datengrundlage in die Verwertung: Ob es rechtlich ein Altfahrzeug ist und was die Teile noch einbringen, bleibt Schätzung.

Was die Schnittstelle liefert

Ein Ablauf von Anfang bis Ende

1. Vor dem Rundgang: Fahrzeug zurücksetzen. Infotainment auf Werkseinstellung, Kopplungen trennen, Speichermedien entnehmen — solange das Fahrzeug Strom hat. Das ist kein Aufruf an die Schnittstelle, sondern ein Feld im Rücknahmeprotokoll; warum, steht in Daten im Altfahrzeug.
2. Rücknahme in einem Aufruf anlegen. Die App am Standort lädt das Foto des Scheins und bis zu 5 Rundgang-Aufnahmen hoch; das Backend ruft POST /vehicles/intake mit fileUrl und photoUrls auf. Zurück kommen die Scheinfelder, die Fahrzeugdaten mit tapiId und der Zustandsbericht in acht Zonen. components nennt je Bestandteil, ob er geliefert wurde; die kaufmännische Behandlung richtet sich nach den vor dem Auftrag angezeigten und vertraglich vereinbarten Konditionen.
3. Kennzeichen gegen den Vertrag prüfen. Aus einer Frontaufnahme liest POST /vision/license-plate Zeichen, Land und Sicherheit — zum Abgleich mit dem Vertragsdatensatz, nicht als Halterabfrage.
4. Rückrufe vor der Freigabe abgleichen. GET /recalls/vehicles/{vin} prüft die Baureihe gegen die amtlichen Register. Eine Maßnahme mit Stop-Drive-Kennung sperrt die Freigabe im eigenen System; die übrigen werden vor der Übergabe erledigt oder dem Inserat als Hinweis mitgegeben.
5. Inserat erzeugen. POST /vehicles/{tapiId}/listing mit language je Zielmarkt und Händlernotizen in notes liefert Titel, Beschreibung und Ausstattungs-Highlights aus den dokumentierten Fahrzeugdaten. Preis und Zustandsaussage ergänzt die eigene Software; der Text erfindet keine Eigenschaften.
6. Nicht vermarktbare Fahrzeuge einordnen. Sprechen Unfall, Defekt oder Alter gegen die Wiedervermarktung, liefert POST /vision/vehicle/elv-classification aus 1 bis 10 Aufnahmen die Einstufung mit belegten Kriterien; die rechtliche Abgrenzung steht in Gebrauchtwagen oder Altfahrzeug und Unfallfahrzeuge. Was das Fahrzeug in der Verwertung noch einbringt, beantwortet GET /vin/{vin}/economic-evaluation mit provider=1 — ein lang laufender Vorgang mit Antwort 202. Die Analyse setzt den Fahrzeugabgleich bei Provider 1 voraus, den der Intake nicht liefert: Für Drittsysteme läuft er über POST /vin/redirect-sessions durch den Browser des Nutzers; erst nach dem Rücksprung mit status=completed folgt der Aufruf.
7. Kennung speichern. Die tapiId wandert in die Fahrzeugakte. Technische Fahrzeugdaten liefert GET /vehicles/{tapiId} später als Bestandteil des zuvor bezahlten VIN-Ablaufs — ohne VIN und Ausstattung und ohne erneuten Abgleich.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <IDEMPOTENCY_KEY>' \
  -d '{
    "fileUrl": "https://example.com/ruecknahme/fahrzeugschein.jpg",
    "photoUrls": [
      "https://example.com/ruecknahme/front.jpg",
      "https://example.com/ruecknahme/heck.jpg"
    ]
  }' \
  'https://api.tapinomahub.com/vehicles/intake'

Der Einbau

1. Schlüssel serverseitig hinterlegen. Der Header X-Api-Key wird nur aus dem Backend gesetzt. Die Rücknahme-App spricht mit Ihrem Server, nie mit der Schnittstelle direkt.
2. Mit einem Endpunkt beginnen. POST /vehicles/intake ersetzt drei Erfassungen auf einmal und ist der lohnendste Einstieg. Rückrufe, Inserat und Altfahrzeug-Einstufung folgen als eigene Schritte.
3. Feldzuordnung festlegen. Welche Scheinfelder, Fahrzeugdaten und Zonen des Zustandsberichts landen in welchen Feldern des Rücknahmeprotokolls? Diese Abbildung ist die eigentliche Arbeit; die Referenz steht im Integrationsleitfaden.
4. Fehlerfall und Leerbefund trennen. Beim Intake ist ein Leerbefund eine 200-Antwort: Bleibt die VIN unlesbar oder antwortet der Datenweg nicht, steht components.vehicle auf vin_not_readable oder unavailable und complete ist false. Die Rücknahme wird angelegt, die Scheinfelder übernommen, der Abgleich bleibt Nacharbeit. 404 vehicle_not_found ist bei GET /vin/{vin}/vehicle und der Wirtschaftlichkeitsanalyse der Leerbefund zur VIN; bei POST /vehicles/{tapiId}/listing und GET /vehicles/{tapiId} bedeutet derselbe Code eine unbekannte oder fremde tapiId. Beim Rückrufabgleich bedeutet 404, dass die VIN im Bestand nicht auflösbar ist. Die kaufmännische Behandlung richtet sich jeweils nach den vor dem Auftrag angezeigten und vertraglich vereinbarten Konditionen. Wiederholt wird nur, wenn die Analyse gar nicht erbracht werden konnte.
5. Abholung bei `202` einbauen. Die Wirtschaftlichkeitsanalyse antwortet mit 202, Location, Retry-After und Job-ID; das Ergebnis holt GET /vin/economic-evaluation/jobs/{jobId} ab — aus einer Warteschlange Ihres Backends, nicht aus der App.
6. Standortweise ausrollen. Erst ein Rückgabestandort, dann die anderen. GET /client/usage zeigt, welche Aufrufe wie oft laufen; X-Tapinoma-Usage-Warning meldet knappes Guthaben.

Worauf zu achten ist

• `Idempotency-Key` setzen. Eine App im Mobilfunknetz sendet gelegentlich doppelt; mit dem Header wird der zweite Aufruf als Wiederholung erkannt (X-Tapinoma-Idempotent-Replay) und nicht zweimal berechnet. Ausnahme: Aufrufe, die einen Schlüssel ausgeben, werden nicht wiederholt — nach einem Timeout Bestand abgleichen statt neu anlegen.
• Leere Felder leer lassen. Ein nicht gelesenes Scheinfeld, eine Zone ohne Befund, ein Fahrzeug ohne Treffer: Das Ergebnis nennt die Lücke, und die Software übernimmt sie als Lücke — kein Standardwert, keine Ergänzung aus dem Vertrag.
• `tapiId` an der Akte speichern. Sie ist die stabile Kennung für Inserat und Fahrzeugdaten. Wer sie verwirft, gleicht dasselbe Fahrzeug ein zweites Mal ab.
• Schlüssel nie im Browser. Weder in der Rücknahme-App noch im Händlerportal. Jeder Aufruf läuft über Ihr Backend.
• Rate-Limits einplanen. Ein Massenimport aus dem Archiv gehört in eine Warteschlange. Limits je Nutzer, Schlüssel oder Endpunkt setzen Sie über PUT /client/users/{clientId}/rate-limits.
• Ergebnis prüfen lassen. Zustandsbericht, Rückrufabgleich und Inseratstext sind Arbeitshilfen; die Freigabe bleibt eine Entscheidung im eigenen Prozess. Eine durchgeführte Bildanalyse wird berechnet, auch ohne Befund.

Was die Schnittstelle nicht tut

Der Zustandsbericht ist kein Gutachten und enthält keine Reparatur- oder Restwertkalkulation; er beschreibt, was auf den Aufnahmen sichtbar ist, und weist befundfreie Zonen als befundfrei aus. Das Kennzeichen wird gelesen, nicht gegen ein Register geprüft; eine Halterabfrage gibt es nicht. Der Inseratstext nennt keine Preise, und die Wirtschaftlichkeitsanalyse ist eine Einkaufsempfehlung aus Marktreferenzen, keine Preisgarantie — wie ein Ankauf zu rechnen ist, steht in Fahrzeugankauf. Fahrzeugdaten von Provider 1 kann ein Drittsystem nicht direkt über GET /vin/{vin}/vehicle abrufen; dieser Abgleich läuft über POST /vin/redirect-sessions durch den Browser des Nutzers. Verkauft wird kein Datenbestand: Geschuldet ist die Durchführung der Abfrage oder Analyse; geprüft und verwendet wird das Ergebnis von Ihnen und Ihren Kunden.