Schadenmanagement und Versicherer: Kalkulation, Zustand und Restwert per Schnittstelle

Wo im Prozess Daten fehlen

Eine Schadenakte besteht zu großen Teilen aus Dokumenten und Fotos, deren Inhalt nicht als Datensatz vorliegt. Die Kalkulation kommt als PDF, die Fotos kommen aus der Schadenmeldung. Was davon in Feldern gebraucht wird, liest heute jemand ab und tippt es ein.

• Kalkulation und Gutachten liegen als PDF vor. Summen, Ersatzteile, Arbeitspositionen und Ausstattungscodes werden für Prüfung und Vergleich von Hand übertragen.
• Der Schaden ist fotografiert, aber nicht beschrieben. Der Sachbearbeiter schreibt einen Freitext, der bei jedem Kollegen anders ausfällt.
• Der Zustand außerhalb der Schadenzone ist nicht dokumentiert. Für Restwert und Verbleib zählt auch, was nicht beschädigt ist — ein Verwerter bewertet genau diese Teile, siehe Karosserieteile: Zustand beurteilen und ehrlich beschreiben.
• Reparatur oder Altfahrzeug wird nach Gefühl entschieden. Ob ein Fahrzeug nach dem Schaden Ware oder Abfall ist, bestimmt den weiteren Weg — siehe Gebrauchtwagen oder Altfahrzeug? Die Abgrenzung beim Export.
• Fahrzeugidentität und Rückrufe stehen in getrennten Quellen und landen selten in derselben Akte.

Was die Schnittstelle liefert

Ein Ablauf von Anfang bis Ende

1. Schadenmeldung mit Fotos. 1 bis 5 Aufnahmen desselben Schadens gehen an POST /vision/damage/describe; zurück kommt eine Beschreibung in sechs festen Abschnitten, die als Befund in der Akte liegt, nicht als Freitext.
2. Fahrzeug abgleichen. Die VIN geht an GET /vin/{vin}/vehicle mit provider=2 oder provider=3; Provider 1 ist aus Drittsystemen nur über den Browser-Redirect erreichbar und wird gebraucht, wenn später die Wirtschaftlichkeitsanalyse folgen soll. Der Abgleich bindet die VIN für diesen Client an den gewählten Provider. Zurück kommen Fahrzeugdaten und eine tapiId — oder 404 vehicle_not_found: kein Datensatz, das Feld bleibt leer, der Vorgang läuft weiter.
3. Kalkulation auslesen. Das PDF geht per fileUrl an POST /scanner/document/calculation. Summen, Reparaturbeurteilung, Positionen und equipment mit DAT-Codes als Strings stehen danach als Felder bereit — nur Werte aus dem Dokument, nichts wird ergänzt.
4. Rückrufe prüfen. GET /recalls/vehicles/{vin} liefert baureihenbezogene Maßnahmen samt Stop-Drive-Kennung, bevor das Fahrzeug zur Reparatur freigegeben wird.
5. Zustand und Einstufung. Bis zu 8 Rundgang-Aufnahmen gehen an POST /vision/condition-report; 1 bis 10 Aufnahmen mit Marktwert und Reparaturschätzung an POST /vision/vehicle/elv-classification. Die Stufe altfahrzeug entsteht nur aus einem hoch belegten Kriterium oder aus der Arithmetik mit den mitgegebenen Werten.
6. Restwertfrage vorbereiten. GET /vin/{vin}/economic-evaluation lässt nur provider=1 zu und setzt voraus, dass das Fahrzeug zuvor über Provider 1 abgeglichen wurde — aus Drittsystemen nur über POST /vin/redirect-sessions mit Rücksprung status=completed und tapiId; eine über provider=2 oder provider=3 abgeglichene VIN ist an diesen Provider gebunden. Dann liefert die Analyse das Erlöspotenzial der Teile als min/average/max und ein Demontage-Ranking; Status über GET /vin/economic-evaluation/jobs/{jobId}. Das ist eine Rechengrundlage, kein Restwert — der entsteht aus Geboten, siehe Unfallfahrzeuge: Totalschaden, Restwert und was für den Verwerter zählt und Fahrzeugankauf: Was ein Altfahrzeug wirklich wert ist.
7. Akte schließen. tapiId, Dokumentfelder und Befunde bleiben in der Akte; technische Fahrzeugdaten liefert GET /vehicles/{tapiId} später als Bestandteil des zuvor bezahlten VIN-Ablaufs, ohne VIN und Ausstattung.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"fileUrl": "<DOKUMENT_URL>"}' \
  'https://api.tapinomahub.com/scanner/document/calculation'

Der Einbau

1. Schlüssel serverseitig hinterlegen. Der API-Key gehört in die Konfiguration des Backends und in den Header X-Api-Key — nie in eine Browser-Anwendung.
2. Mit einem Endpunkt beginnen. Meist POST /scanner/document/calculation, weil dort heute abgetippt wird; technisch ein HTTPS-Aufruf mit JSON, unabhängig von Sprache und Plattform.
3. Feldzuordnung festlegen. Welche Antwortfelder landen in welchen Feldern der Schadenakte? Diese Abbildung ist die eigentliche Arbeit.
4. Fehlerfall und Leerbefund trennen. 404 vehicle_not_found, ein null-Feld oder ein befundfreier Abschnitt sind fachliche Ergebnisse und werden gespeichert; ein technischer Fehler löst eine Wiederholung oder eine Aufgabe aus, nie einen Standardwert.
5. Die `202`-Abholung bauen. Lang laufende Aufrufe antworten mit 202, Location und Retry-After; der Status wird über den zugehörigen .../jobs/{jobId}-Endpunkt abgeholt. Bis dahin bleibt der Vorgang „in Bearbeitung“.
6. Ausrollen und beobachten. Erst ein Mandant, dann alle; GET /client/usage und GET /client/credits zeigen Aufrufe und Guthaben.

Worauf zu achten ist

• `Idempotency-Key` setzen. Eine Wiederholung nach Timeout liefert dann dieselbe Antwort, erkennbar an X-Tapinoma-Idempotent-Replay. Aufrufe, die einen Schlüssel einmalig ausgeben, werden nicht gereplayt: nach Timeout Bestand abgleichen statt blind wiederholen.
• Leere Felder nicht füllen. Ein null in der Kalkulation heißt, das Dokument weist den Wert nicht aus; ein befundfreier Abschnitt heißt, nichts Sichtbares. Beides gehört so in die Akte — kein Standardwert, keine Schätzung.
• `tapiId` speichern. Sie ist die stabile Kennung des abgeglichenen Fahrzeugs und der Schlüssel für jede spätere Rückfrage ohne neuen Abgleich.
• Schlüssel nie im Browser. Auch für Provider 1: Das Backend erzeugt über POST /vin/redirect-sessions aus vin, returnUrl und state eine einmalig nutzbare Session; der Rücksprung trägt nur status, tapiId und state, nie Fahrzeug- oder Zugangsdaten. Die Session verfällt nach zehn Minuten.
• Rate-Limits je Mandant. PUT /client/users/{clientId}/rate-limits begrenzt je Nutzer, Schlüssel oder Endpunkt, damit ein Massenlauf die anderen Mandanten nicht ausbremst; X-Tapinoma-Usage-Warning meldet knappes Guthaben.
• Ergebnis prüfen lassen. Die Schadenbeschreibung ersetzt keine Besichtigung, die Einstufung kein Gutachten, das Erlöspotenzial keinen Restwert. In der Akte steht, welches Feld aus welchem Aufruf stammt.

Was die Schnittstelle nicht tut

Die Schnittstelle erstellt kein Gutachten und ersetzt keinen Sachverständigen: Der Zustandsbericht enthält keine Reparatur- oder Restwertkalkulation, die Schadenbeschreibung beschreibt nur Sichtbares, und die Stufe gutachten_empfohlen meint genau das. Sie führt keine Halterabfrage und keinen Abgleich mit dem Zulassungsregister durch; der Rückrufabgleich ist baureihenbezogen und eine Arbeitshilfe — ob ein einzelnes Fahrzeug betroffen und eine Maßnahme dort erledigt ist, beantwortet verbindlich nur der Hersteller. Preisbewertungen und Erlöspotenzial sind indikativ, keine Preisgarantie. Provider 1 wird von Drittsystemen nur über den Browser-Redirect erreicht. Und tapinomahub verkauft keinen Datenbestand: Geschuldet ist die Durchführung der Abfrage oder Analyse — eine durchgeführte Bildanalyse wird auch bei Leerbefund berechnet —, Prüfung und Verwendung der Ergebnisse liegen beim Kunden. Was Fahrzeugdaten in der Schadenakte datenschutzrechtlich bedeuten, behandelt Daten im Altfahrzeug: Was im Infotainment bleibt, wenn das Fahrzeug geht.