Von der VIN zur Wirtschaftlichkeitsanalyse: der Fahrzeugweg

Am Hoftor steht ein Unfallfahrzeug, der Verkäufer will einen Preis hören, und die Entscheidung fällt in Minuten. Wer nur auf Erfahrung setzt, zahlt bei ungewöhnlichen Baureihen zu viel und lässt bei unauffälligen zu viel liegen. Der Fahrzeugweg der tapinomahub API setzt an derselben Stelle an wie der Einkäufer: bei der Fahrgestellnummer — und endet bei einer nachvollziehbaren Zahl samt Reihenfolge für die Demontage.

Stufe 1: Das Fahrzeug eindeutig machen

GET /vin/{vin}/vehicle gleicht die VIN gegen die freigeschaltete Quelle ab. Mit includeEquipments, includeColors und includeTechnical steuern Sie, wie tief die Antwort geht; country setzt den Marktbezug, provider die vertraglich vereinbarte Quelle. Ein erfolgreicher Abgleich enthält eine stabile tapiId — die Kennung, mit der alle weiteren Aufrufe dasselbe Fahrzeug meinen. Die Leistungsbeschreibung steht in Fahrzeugdaten anhand der VIN abgleichen.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  'https://api.tapinomahub.com/vin/WVWZZZ1KZAW000000/vehicle?includeEquipments=true&includeTechnical=true'

Stufe 2: Die Teileliste des Fahrzeugs

GET /vin/{vin}/parts gibt die ermittelten OE-Positionen zurück: je Teil number und numberUnformatted, name und nameAddition, category, manufacturer, amount, price, tapiGenArt und das Pflichtfeld vdi. vdi enthält bestätigte vollständige VDI-4081-Codes und bleibt ohne gültige Zuordnung als [] vorhanden. Wichtiger als die Liste selbst ist ihre Einordnung: matchLevel sagt, wie belastbar die Zuordnung ist, und missingCategories sagt, was fehlt. Eine nicht leere Liste in missingCategories bedeutet ausdrücklich, dass die Teileliste unvollständig ist. Details in Teilezuordnungen anhand der VIN abgleichen.

Der asynchrone Auftrag, richtig behandelt

Teileliste und Bewertung können länger dauern, als eine HTTP-Antwort warten soll. Deshalb antwortet die API entweder unmittelbar mit 200 oder nimmt den Auftrag mit 202 an — samt Location, Retry-After und einer jobId. Das ist der dokumentierte Normalfall und keine Störung.

1. Beide Antworten behandeln. Eine Anbindung, die nur 200 kennt, funktioniert im Test und fällt im Betrieb aus. 202 liefert jobId, statusUrl, status und retryAfterSeconds.
2. Im genannten Abstand nachfragen, nicht in einer engen Schleife. GET /vin/parts/jobs/{jobId} und GET /vin/economic-evaluation/jobs/{jobId} geben queued, running, succeeded oder failed zurück.
3. Bei `succeeded` steht das Ergebnis in `result` — dieselbe Struktur wie bei einer direkten 200-Antwort. Ihr Code braucht also nur einen Auswertepfad.
4. Bei `failed` unterscheidet `error.code` zwischen vehicle_not_found — ein fachlicher Leerbefund — und vin_service_unavailable, einem technischen Ausfall. Nur der zweite Fall rechtfertigt einen erneuten Versuch.
5. Die Job-Kennung gehört in den Vorgang. Wer sie verliert, kann ein Ergebnis nicht mehr abholen; ein unbekannter Auftrag endet in 404 vin_parts_job_not_found.

# 202 Accepted: {"jobId":"8f1c…","status":"queued","retryAfterSeconds":5,…}
curl \
  -H 'X-Api-Key: <API_KEY>' \
  'https://api.tapinomahub.com/vin/parts/jobs/8f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21'

Stufe 3: Die Wirtschaftlichkeitsanalyse

GET /vin/{vin}/economic-evaluation verbindet die Teileliste mit Marktpreisen und rechnet daraus drei Dinge: das Erlöspotenzial des Fahrzeugs, eine Reihenfolge für die Demontage und eine Einkaufsempfehlung. Die Antwort legt ihre Annahmen offen, damit jede Zahl nachgerechnet werden kann — siehe Wirtschaftlichkeitsanalyse anhand der VIN erstellen.

• `coverage` macht die Datenlage sichtbar: totalParts, excludedIrrelevant, relevantParts, selectedParts, pricedParts und unpricedParts. Eine hohe Zahl in unpricedParts ist ein Warnzeichen, keine Nebensache.
• `revenuePotential` nennt min, average und max. Die Spanne bleibt vollständig sichtbar — sie wird nicht zu einer Zahl verdichtet.
• `purchaseRecommendation.goodPurchasePriceEur` ist die Zahl für das Gespräch am Hoftor: recoveryRate mal dem Minimum, abzüglich der angenommenen Kosten je bewertetem Teil.
• `assumptions.priceBasis` weist min aus. Damit ist im Ergebnis dokumentiert, auf welcher Basis die Empfehlung steht.
• `parts[]` trägt rank, Nummer, Bezeichnung, Kategorie und pricing mit min, average, max, confidence und evaluatedAt. Die Geldbeträge in pricing gelten je Stück.
• `amount` stammt unverändert aus der Teileliste des Anbieters, ist nicht geprüft und geht in keine Berechnung ein. Gerechnet wird mit einer Einheit je Teil.

Abrechnung: das monatliche VIN-Bundle

• VIN Vehicle, VIN Parts und VIN Cart Check bilden das Bundle `VIN_MONTHLY_LOOKUP`. Abrechnung und Wiederholungen richten sich ausschließlich nach den vereinbarten Konditionen. Cache- oder Ergebniswiederverwendung verändert die Kundenabrechnung nicht.
• Der Header `X-Tapinoma-Billing-Bundle` ist gesetzt, wenn ein Aufruf unter diesen Deckel fällt. X-Tapinoma-Billing-Source nennt dazu die Abrechnungsentscheidung.
• Ein Plan gilt je Endpunkt-Schlüssel, nicht pauschal. Deckt kein Plan den Aufruf oder ist das Monatskontingent verbraucht, wird das Guthabenkonto belastet; reicht es nicht, antwortet die API mit 402 insufficient_credits.
• `404 vin_not_resolvable` kennzeichnet einen nicht durchgeführten Abgleich; seine kaufmännische Behandlung richtet sich nach den vor dem Auftrag angezeigten und vertraglich vereinbarten Konditionen.
• Die Sandbox folgt den vereinbarten Konditionen. Sie verwendet dieselbe Basisadresse, antwortet nur mit dokumentierten synthetischen Testdaten und verhält sich bei Validierung, Ratenlimits und asynchronen Zuständen wie beschrieben — der richtige Ort, um die 202-Behandlung zu bauen.

Der Ablauf im Ankauf

1. VIN erfassen — abgetippt, aus dem Fahrzeugschein über POST /scanner/document/registration oder vom Fahrzeug über POST /scanner/vin/extract. 17 Stellen, sonst 400 invalid_vin.
2. Fahrzeug abgleichen und tapiId, matchLevel der Folgeaufrufe und incomplete im Vorgang festhalten.
3. Teileliste anfordern und 202 sauber behandeln. Job-Kennung speichern, im genannten Abstand nachfragen.
4. Bewertung mit Ihren Annahmen anfordern, nicht mit den Vorgaben. Quote und Kosten je Teil kennt Ihr Betrieb besser als jede Vorgabe.
5. Empfehlung, Spanne und Abdeckung gemeinsam anzeigen. Eine Zahl ohne coverage daneben verleitet zu Vertrauen, das die Datenlage nicht hergibt.
6. Demontage nach rank planen. Die ersten Positionen tragen den Erlös; der Rest entscheidet über die Hallenzeit.
7. Nach dem Verkauf gegenrechnen: erzielter Erlös gegen Empfehlung, bewertete gegen verkaufte Teile. Daraus entsteht Ihre eigene, belastbare recoveryRate.

Grenzen, die man kennen muss

• Eine Bewertung ist keine Preisgarantie. Sie ist indikativ, sie beruht auf Marktangeboten und Annahmen, und sie ersetzt die Besichtigung nicht. Schäden, Laufleistung und Vollständigkeit sieht keine VIN-Abfrage.
• Die Abdeckung hängt an der Quelle. Je nach Hersteller, Baujahr und Markt liegen unterschiedlich viele Daten vor. incomplete, missingCategories und unpricedParts sind die Felder, die das sichtbar machen.
• Eine VIN ist ein Fahrzeugbezug und kann personenbezogen werden. Sie dürfen nur übermitteln, wozu Sie befugt sind, und nur das, was für den Zweck erforderlich ist. Die Aufbewahrung im eigenen System folgt Ihrem Vertrag und Ihrer Löschfrist.
• `vehicle_type_candidates` ist keine Passungsaussage. Auf dieser Stufe beschreibt die Liste den Fahrzeugtyp, nicht das Einzelfahrzeug.
• Die Teileliste ist kein Bestandsverzeichnis. Sie sagt, was in diesem Typ verbaut sein kann — nicht, was in diesem Fahrzeug noch verbaut und verkäuflich ist. Den Unterschied macht die Besichtigung.

Schemata, Fehlercodes und Beispielantworten stehen in der Entwicklerdokumentation. Sobald aus dem bewerteten Fahrzeug einzelne Teile werden, geht es weiter mit Von der OE-Nummer zum marktplatzfertigen Artikel und, sobald die Teile auf der Werkbank liegen, mit Vom Teilefoto zum Inserat: der Bildweg durch die tapinomahub API.