Restwertbörsen und Auktionsplattformen: Einstellen, bieten und kalkulieren über die Schnittstelle

Wo im Prozess Daten fehlen

Eine Restwertbörse lebt davon, dass beide Seiten dem Inserat vertrauen: Der Einsteller muss ein Fahrzeug in kurzer Zeit vollständig beschreiben, der Bieter in der Gebotsfrist entscheiden, was es ihm wert ist. An fünf Stellen entstehen regelmäßig Lücken:

• Beim Einstellen. Die Fahrgestellnummer wird aus dem Gutachten oder vom Foto abgetippt; ein vertauschtes Zeichen fällt erst auf, wenn ein Bieter das falsche Fahrzeug kalkuliert hat.
• Bei der Schadenbeschreibung. Jeder Einsteller fotografiert und formuliert anders. Zwei Inserate zum gleichen Schadenbild sind nicht vergleichbar.
• Bei den Bildern. Ob ein Foto noch ein lesbares Kennzeichen zeigt, prüft vor der Veröffentlichung niemand systematisch; bei Teileauktionen zeigen die Bilder Seriennummern und andere exemplarbezogene Kennungen, die der Verkäufer vor dem Zuschlag nicht preisgeben will.
• Beim Inseratstext. Titel, Beschreibung und Ausstattungsliste werden je Fahrzeug von Hand geschrieben — und für Bieter aus dem Ausland noch einmal in einer anderen Sprache.
• Beim Gebot. Der Verwerter rechnet in der Gebotsfrist aus Erfahrung: Welche Teile bringen Erlös, welche Ausstattung hat das Fahrzeug, darf es als Ware transportiert werden? Die Ausstattung steht nicht auf den Fotos, die Einordnung als Altfahrzeug bleibt Schätzung.

Was die Schnittstelle liefert

Ein Ablauf von Anfang bis Ende

1. Fahrzeug identifizieren. Der Einsteller lädt die Fotos hoch; das Backend liest mit POST /scanner/vin/extract die Fahrgestellnummer vom Fahrzeugfoto. Ist sie nicht lesbar, ist vin gleich null — das Feld bleibt leer und wird zur Nacharbeit. Liegt der Fahrzeugschein vor, erledigt POST /vehicles/intake mit fileUrl diesen und den nächsten Schritt in einem Aufruf.
2. Fahrzeug abgleichen und `tapiId` erhalten. Mit provider 2 oder 3 antwortet GET /vin/{vin}/vehicle direkt. Provider 1 darf ein Drittsystem nicht direkt abrufen: Das Backend erstellt mit POST /vin/redirect-sessions aus vin, returnUrl und state eine Session und leitet den Nutzer auf redirectUrl; nach dem Abgleich in der tapinoma-Oberfläche kehrt er auf returnUrl mit status=completed, tapiId und state zurück — oder mit status=cancelled. Fahrzeugdaten stehen nie im Redirect; die Session verfällt nach zehn Minuten. VIN-Ablauf und spätere Inseratsaufrufe laufen unter demselben Schlüssel, weil die tapiId an den Client gebunden ist, der sie erhalten hat.
3. Zustand und Schaden dokumentieren. Der Rundgang mit bis zu 8 Aufnahmen geht an POST /vision/condition-report und kommt als Befund je Zone mit Gesamteinstufung A/B/C zurück. Den eigentlichen Schaden beschreibt POST /vision/damage/describe aus 1 bis 5 Aufnahmen in sechs festen Abschnitten; befundfreie Abschnitte werden als befundfrei ausgewiesen, beschrieben wird nur Sichtbares — siehe Unfallfahrzeuge.
4. Bilder vor der Veröffentlichung prüfen. POST /vision/license-plate liest aus bis zu 3 Aufnahmen Zeichen, Land, Sicherheit und Position am Fahrzeug (vorne/hinten); mit den Zeichen gleicht Ihre Software das Fahrzeug gegen den Auftrag ab, und ein nicht leeres plates zeigt vor der Veröffentlichung, dass ein Bild noch ein lesbares Kennzeichen enthält. Das Unkenntlichmachen selbst leistet die Schnittstelle nicht. Bei Teileauktionen anonymisiert POST /vision/identifiers/redact instanzbezogene Kennungen im Teilebild, bevor es online geht; Typ- und OE-Kennungen bleiben sichtbar — siehe Teilebilder.
5. Inseratstext erzeugen. POST /vehicles/{tapiId}/listing mit language je Zielmarkt und Einstellerhinweisen in notes liefert Titel, Beschreibung und Ausstattungs-Highlights aus den dokumentierten Fahrzeugdaten. Der Text erfindet keine Eigenschaften und nennt weder Preise noch Zustand.
6. Bieterseite: vor dem Gebot kalkulieren. Vor der Analyse schließt der Bieter den Provider-1-Fahrzeugabgleich über POST /vin/redirect-sessions unter seinem eigenen Schlüssel ab. Erst dann läuft GET /vin/{vin}/economic-evaluation mit provider=1: Sie antwortet mit 200, wenn Teileliste und Marktpreisbewertungen bereits vorliegen, sonst mit 202, Location, Retry-After und Job-ID; das Ergebnis holt dann GET /vin/economic-evaluation/jobs/{jobId} ab. Es enthält das Erlöspotenzial der Teile als min/average/max, ein nach Erlös sortiertes Demontage-Ranking und eine Einkaufsempfehlung. Kleinteile sind aussortiert, Marktpreisbewertungen werden bis zu 30 Tage wiederverwendet — siehe Fahrzeugankauf und Demontagetiefe.
7. Bieterseite: Altfahrzeug einstufen. Ob das Fahrzeug nach dem Zuschlag als Ware oder als Abfall transportiert wird, entscheidet über Logistik und Papiere. POST /vision/vehicle/elv-classification liefert aus 1 bis 10 Aufnahmen die Stufe kein_altfahrzeug_verdacht, gutachten_empfohlen oder altfahrzeug; altfahrzeug wird nur bei hoch belegtem Kriterium oder aus der Arithmetik mit mitgegebenem Marktwert und Reparaturschätzung vergeben. Die rechtliche Abgrenzung steht in Gebrauchtwagen oder Altfahrzeug.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  'https://api.tapinomahub.com/vin/<VIN>/economic-evaluation?provider=1'

Der Einbau

1. Schlüssel serverseitig hinterlegen. Der Header X-Api-Key wird nur aus dem Backend gesetzt. Weder Einsteller-Oberfläche noch Bieter-App sprechen mit der Schnittstelle direkt; auch die Redirect-Session entsteht auf dem Server.
2. Mit einem Endpunkt beginnen. Einstellerseite: POST /vision/condition-report, weil er Inserate vergleichbar macht; Bieterseite: der Provider-1-Fahrzeugabgleich über POST /vin/redirect-sessions unter dem eigenen Schlüssel, erst dann GET /vin/{vin}/economic-evaluation mit provider=1. Kennzeichen, Inserat und Altfahrzeug-Einstufung folgen als eigene Schritte.
3. Feldzuordnung festlegen. Welche Zonen des Zustandsberichts und welche Werte der Analyse landen in welchen Feldern des Inserats und der Bieteransicht? Diese Abbildung ist die eigentliche Arbeit; die Referenz steht im Integrationsleitfaden.
4. Fehlerfall und Leerbefund trennen. 404 vehicle_not_found und vin gleich null sind Leerbefunde, keine Fehler: Inserat anlegen, Feld leer lassen, Abgleich als Nacharbeit führen. Eine durchgeführte Bildanalyse wird berechnet, auch ohne Befund; wiederholt wird nur, wenn sie gar nicht erbracht werden konnte.
5. Abholung bei `202` einbauen. Die Wirtschaftlichkeitsanalyse antwortet mit 200, wenn Teileliste und Marktpreisbewertungen bereits vorliegen, sonst mit 202, Location, Retry-After und Job-ID; das Ergebnis holt dann GET /vin/economic-evaluation/jobs/{jobId} aus einer Warteschlange Ihres Backends ab — nicht aus dem Browser des Bieters. Ihre Software muss beide Antworten verarbeiten.
6. Schrittweise ausrollen. Erst eine Einstellergruppe, dann die Bieter. GET /client/usage zeigt, welche Aufrufe wie oft laufen; X-Tapinoma-Usage-Warning meldet knappes Guthaben.

Worauf zu achten ist

• `Idempotency-Key` setzen. Ein doppelt abgeschickter Upload darf keine zweite Analyse auslösen; der Header macht die Wiederholung erkennbar (X-Tapinoma-Idempotent-Replay), berechnet wird einmal. Ausnahme: Aufrufe, die einen Schlüssel ausgeben, werden nicht wiederholt — nach einem Timeout Bestand abgleichen.
• Leere Felder leer lassen. Eine unlesbare VIN, eine Zone ohne Befund, eine Position ohne Marktreferenz: Das Ergebnis nennt die Lücke, das Inserat zeigt sie — kein Standardwert, keine Ergänzung aus einem ähnlichen Fahrzeug.
• `tapiId` am Inserat speichern — samt Client. Sie ist die stabile Kennung für Inseratstext und Fahrzeugdaten; GET /vehicles/{tapiId} liefert die technischen Daten später als Bestandteil des zuvor bezahlten VIN-Ablaufs, aber nur mit dem Schlüssel des Clients, der die tapiId dort erhalten hat. Mit einem anderen Schlüssel antwortet die Schnittstelle 404.
• Schlüssel nie im Browser. Weder in der Einsteller-Oberfläche noch in der Bieter-App. Jeder Aufruf und jede Redirect-Session läuft über Ihr Backend.
• Rate-Limits einplanen. Vor Auktionsende fragen viele Bieter dieselben Inserate ab; Analysen gehören in eine Warteschlange, nicht in den Klick. Limits je Nutzer, Schlüssel oder Endpunkt setzen Sie über PUT /client/users/{clientId}/rate-limits.
• Ergebnis prüfen lassen. Zustandsbericht, Schadentext und Einkaufsempfehlung sind Arbeitshilfen; das Gebot bleibt eine Entscheidung des Bieters, die Freigabe des Inserats eine des Einstellers.

Was die Schnittstelle nicht tut

Zustandsbericht und Schadentext sind keine Gutachten und enthalten keine Reparatur- oder Restwertkalkulation; sie beschreiben, was auf den Aufnahmen sichtbar ist. Das Kennzeichen wird gelesen, nicht gegen ein Register geprüft; eine Halterabfrage gibt es nicht. Die Wirtschaftlichkeitsanalyse ist eine Einkaufsempfehlung aus Marktreferenzen, kein Restwert und keine Preisgarantie — der Restwert entsteht auf Ihrer Plattform aus den Geboten. 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, Ihren Einstellern und Ihren Bietern.