Betriebssoftware für Demontagebetriebe: Fahrzeugakte, Nachweise und Bestand per API

Wo im Prozess Daten fehlen

Die Fahrzeugakte entsteht an der Annahme, und dort ist die Zeit knapp: Der Anlieferer wartet auf den Nachweis, der Fahrzeugschein liegt auf dem Tresen, das Fahrzeug steht auf dem Hof. An fünf Stellen wird heute abgetippt, geschätzt oder offen gelassen:

• Anlage der Akte. Fahrgestellnummer, Marke, Typ und Fahrzeugklasse werden vom Fahrzeugschein abgetippt. Eine falsch übertragene VIN macht den späteren Verwertungsnachweis angreifbar — siehe Zulassungsbescheinigung: Die Felder, die im Betrieb zählen.
• Einstufung des Fahrzeugs. Ob ein Fahrzeug als Altfahrzeug zu behandeln ist, wird auf dem Hof entschieden und selten mit Bildern belegt — siehe Altfahrzeugverordnung: Pflichten für Halter und Demontagebetriebe.
• Demontagetiefe. Welche Teile ausgebaut werden, entscheidet Erfahrung, nicht eine belegte Erlöserwartung je Teil — siehe Demontagetiefe: Welche Teile sich auszubauen lohnen.
• Teilenummer und Zustand beim Ausbau. Die Nummer vom Etikett landet mit öligen Händen auf einem Zettel; im Zustandsfeld steht „gut“, weil das Feld gefüllt sein musste — siehe Teileidentifikation: Vom Ausbauteil zum verkaufsfähigen Datensatz.
• Einordnung des Bestands. Hauptgruppe und Position nach VDI 4081 werden je Betrieb anders vergeben, weil kein Katalog im System hinterlegt ist.

Was die Schnittstelle liefert

Ein Ablauf von Anfang bis Ende

1. Annahme: Fahrzeugschein fotografieren. Die Software schickt die fileUrl des Bildes an POST /vehicles/intake, optional mit Rundgang-Fotos als photoUrls für einen Zustandsbericht. Zurück kommen Dokumentfelder, Fahrzeugdaten samt tapiId und der Bericht; was das Dokument nicht hergibt, bleibt leer.
2. Nachweis ausstellen. Fahrgestellnummer, Marke, Typ und Kennzeichen aus den Dokumentfeldern füllen den Verwertungsnachweis. Die Einstufung als Altfahrzeug belegt POST /vision/vehicle/elv-classification mit Befund und Bildern je Kriterium; die rechtliche Entscheidung bleibt beim Betrieb.
3. Teileliste abholen. Direkt nach dem Intake ruft die Software GET /vin/{vin}/parts ohne provider auf. Der Intake hat die VIN an Datenweg 2 gebunden; der Aufruf übernimmt diese Bindung und liefert die Teileliste auf Fahrzeugtypebene mit matchLevel=vehicle_type_candidates, in der Regel sofort mit 200. Mehrere Varianten eines Bauteils können nebeneinander stehen. Ein expliziter provider, der der bestehenden Bindung widerspricht, wird mit 409 vin_provider_mismatch abgewiesen.
4. Oder: der Provider-1-Weg, vor dem ersten Abgleich gewählt. Das Erlösranking beruht auf der fahrzeuggenauen Teileliste von Provider 1, und den Provider-1-Abgleich darf ein Drittsystem nicht direkt aufrufen. Die Software entscheidet deshalb je Fahrzeug vor dem ersten Abgleich, welchen Weg sie geht: den Intake über Datenweg 2 mit der Teileliste auf Typebene — oder den Provider-1-Weg, bei dem Ihr Server mit POST /vin/redirect-sessions aus vin, returnUrl und optional state eine Session anlegt und den Nutzer auf die redirectUrl leitet; der Rücksprung auf returnUrl bringt status=completed und die tapiId. Die Session verfällt nach zehn Minuten; Fahrzeugdaten stehen nie im Redirect. Einen Wechsel einer bestehenden VIN-Bindung dokumentiert die Spezifikation nicht; ein provider, der der Bindung widerspricht, wird mit 409 vin_provider_mismatch abgewiesen.
5. Demontage planen. Auf dem Provider-1-Weg liefert GET /vin/{vin}/economic-evaluation mit provider=1 nach dem Abgleich aus der Browser-Session das nach Erlös sortierte Ranking mit min/average/max je Teil; Kleinteile sind aussortiert. Liegen nicht alle Bewertungen vor, antwortet der Aufruf mit 202, Location, Retry-After und Job-ID für GET /vin/economic-evaluation/jobs/{jobId}. Die Software zeigt das Ranking als Arbeitsliste; wo die Linie verläuft, entscheidet der Betrieb.
6. Ausbau: Etikett fotografieren. POST /scanner/label/extract-partnumbers liest Teile- und Referenznummern; GET /parts/oe/{oeNumber} liefert bei bestätigtem Treffer Bezeichnung, genau eine tapiGenArt und die VDI-4081-Zuordnung, 404 heißt kein Treffer.
7. Zustand einstufen. Ein bis drei Aufnahmen gehen an POST /vision/part/quality; zurück kommt A, B oder C mit limitations — oder gradable=false mit reason; dann bleibt das Feld leer.
8. Bestand führen. GET /vdi liefert den Katalog mit Stand und Prüfwert, gegen den die Software ihre Hauptgruppen abgleicht; Trockenlegung, Teileentnahme und Abgabe der Restkarosse stehen an derselben tapiId — siehe Trockenlegung: Welche Stoffe vor der Demontage heraus müssen.

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

Der Einbau

1. Schlüssel serverseitig hinterlegen. Der X-Api-Key gehört in die Konfiguration Ihres Backends; das Foto vom Tablet am Hof geht an Ihren Server, und nur Ihr Server ruft die API auf.
2. Mit einem Endpunkt beginnen. Für Betriebssoftware ist das POST /vehicles/intake hinter der Annahme, weil jede spätere Angabe an der Akte hängt. Die Reihenfolge Vertrag, Schlüssel, Prozess, Go-live beschreibt der Integrationsleitfaden.
3. Feldzuordnung festlegen. Dokumentfelder, Fahrzeugdaten und Zustandsbericht haben feste Ziele in der Akte; die tapiId bekommt ein eigenes Feld, ebenso die Herkunft je Wert: gelesen, abgeglichen oder von Hand eingetragen.
4. Leerbefund und Fehler trennen. Bleibt in der Akte tapiId null und meldet components den Fahrzeugbestandteil als nicht geliefert, ist das ein fachliches Ergebnis, kein Fehler: Akte anlegen, Fahrzeugfeld leer lassen, Klärungsaufgabe erzeugen; die Dokumentfelder bleiben Teil der Antwort, der Fahrzeuganteil wird anteilig erstattet. Nur ein technischer Fehler wird wiederholt.
5. Asynchrone Antworten abholen. Teileliste und Wirtschaftlichkeitsanalyse können mit 202 antworten; auf dem Provider-1-Weg setzen beide den Abgleich aus der Browser-Session voraus, der vor dem ersten Abgleich der VIN gewählt wurde. Die Software merkt sich die Job-ID und fragt GET /vin/parts/jobs/{jobId} beziehungsweise GET /vin/economic-evaluation/jobs/{jobId} nach Retry-After ab, statt den Aufruf zu wiederholen.
6. Ausrollen. Zuerst bei einem Betrieb, dann in der Breite. GET /client/usage und je Workspace GET /client/users/{clientId}/usage zeigen, welche Aufrufe wie oft laufen.

Worauf zu achten ist

• `Idempotency-Key` setzen. Bei wiederholbaren Aufrufen verhindert der Header Doppelanlagen nach einem Timeout; X-Tapinoma-Idempotent-Replay zeigt die Wiederholung an. Ausnahme: POST /client/partner-workspaces gibt einen geheimen Schlüssel einmalig aus und wird nicht gereplayt — nach einem Timeout den Bestand abgleichen, nicht blind wiederholen.
• Leere Felder nicht füllen. Bleibt ein Dokumentfeld leer oder kommt gradable=false, bleibt das Feld in der Akte leer und bekommt eine Klärungsaufgabe. Eine geratene Fahrgestellnummer im Verwertungsnachweis ist schlimmer als eine sichtbare Lücke.
• `tapiId` speichern. Sie ist der Anker der Akte: GET /vehicles/{tapiId} liefert die technischen Daten als Bestandteil des zuvor bezahlten VIN-Ablaufs, ohne VIN und ohne Ausstattung, und jedes ausgebaute Teil hängt daran.
• Schlüssel nie im Browser. Auch eine Web- oder Tablet-Anwendung ruft die API aus dem Backend auf; das Endgerät spricht nur mit Ihrem Server.
• Rate-Limits je Workspace setzen. PUT /client/users/{clientId}/rate-limits begrenzt je Nutzer, Schlüssel oder Endpunkt, damit ein Bildimport bei einem Betrieb nicht das Kontingent aller anderen aufbraucht; X-Tapinoma-Usage-Warning meldet knappes Guthaben.
• Ergebnis prüfen lassen. Ranking und Zustandsstufe sind Grundlagen für eine Entscheidung, nicht die Entscheidung; Marktpreisbewertungen werden bis zu 30 Tage wiederverwendet. Der Demonteur bestätigt, die Software dokumentiert, woher ein Wert stammt.

Was die Schnittstelle nicht tut

Die Schnittstelle verkauft keinen Datenbestand: Geschuldet ist die Abfrage beziehungsweise Analyse und die Ausgabe des Ergebnisses; die Prüfung vor der Verwendung liegt beim Betrieb. Sie stellt keinen Verwertungsnachweis aus; sie liefert die Angaben dafür und belegt, woher sie stammen. Die Altfahrzeug-Einstufung ist eine Sichtprüfung aus Bildern, kein Gutachten; der Zustandsbericht enthält keine Reparatur- oder Restwertkalkulation; die Wirtschaftlichkeitsanalyse ist eine Erlöserwartung, keine Preisgarantie. Eine Halterabfrage gibt es nicht. Fahrzeugdaten des Providers 1 dürfen von Drittsystemen nicht direkt abgerufen werden: GET /vin/{vin}/vehicle antwortet dort mit redirect_required, der Abgleich läuft über eine Browser-Session aus POST /vin/redirect-sessions, die nach zehn Minuten verfällt; Provider 2 und 3 sind direkt abfragbar. Wo ein Feld nicht belegt ist, bleibt es null — die Schnittstelle rät nicht, und Ihre Software sollte es auch nicht tun.