Werkstattmanagement-Systeme: Teile gegen das Fahrzeug prüfen, bevor bestellt wird

Wo im Prozess Daten fehlen

Ein Werkstattauftrag beginnt mit einem Fahrzeug und endet mit einer Rechnung. Dazwischen liegen Stellen, an denen die Software nicht weiß, was sie wissen müsste, und ein Mitarbeiter es aus dem Katalog oder vom Telefon nachträgt:

• Die Teilebestellung geht raus, bevor die Passung geprüft ist. Der Serviceberater übernimmt OE-Nummern aus dem Katalog in den Auftrag. Ob sie zu genau diesem Fahrzeug mit genau dieser Ausstattung passen, zeigt sich beim Einbau — oder bei der Retoure.
• Die OE-Nummer aus den Kundenunterlagen ist eine Vorgängernummer. Die Nummer auf der mitgebrachten Rechnung oder dem alten Teil ist ersetzt worden. Welche heute gilt, sucht jemand von Hand — siehe OE-Nummer: Die Originalteilenummer richtig lesen.
• Das ausgebaute Teil hat ein Etikett, das niemand abschreibt. Teile- und Referenznummern des getauschten Steuergeräts landen als Foto im Auftrag, nicht als Datensatz — siehe Gebrauchte Steuergeräte: Codierung, Wegfahrsperre, Angebot.
• Rückrufe werden beim Werkstattbesuch nicht abgeglichen. Das Fahrzeug steht auf der Bühne; eine offene Rückrufaktion wäre ein zweiter Auftrag, aber die Software weiß nichts davon.
• Die Teilebezeichnung liegt nur in einer Sprache vor. Ein Betrieb mit Kunden oder Lieferanten im Ausland übersetzt Bezeichnungen auf der Rechnung selbst.

Was die Schnittstelle liefert

Ein Ablauf von Anfang bis Ende

1. Auftrag anlegen, Fahrzeug abgleichen. Die Werkstatt erfasst die Fahrgestellnummer. Provider 2 und 3 fragt Ihr System direkt über GET /vin/{vin}/vehicle ab. Für Provider 1 legt Ihr Server über POST /vin/redirect-sessions eine Session aus vin, returnUrl und state an und leitet den Serviceberater auf die redirectUrl; der Rücksprung bringt status=completed mit tapiId und state — oder status=cancelled. Die Session verfällt nach zehn Minuten; Fahrzeug- oder Zugangsdaten stehen nie im Redirect.
2. Enthaltene Fahrzeugdaten nachladen. GET /vehicles/{tapiId} liefert die technischen Fahrzeugdaten für die Auftragsmaske als Bestandteil des zuvor bezahlten VIN-Ablaufs — ohne VIN und Ausstattung und ohne einen neuen Fahrzeugabgleich zu bestellen.
3. Rückrufe prüfen, solange das Fahrzeug da ist. GET /recalls/vehicles/{vin} gleicht die Baureihe gegen Kraftfahrt-Bundesamt, EU Safety Gate und NHTSA ab. Eine offene Maßnahme erscheint mit Aktenzeichen, Abhilfe und Stop-Drive-Kennung als Hinweis im Auftrag.
4. Teile aus dem Auftrag einordnen. Jede OE-Nummer geht durch GET /parts/oe/{oeNumber}. Zurück kommen die Ersetzungskette, die tapiGenArt als GenArt für die Warengruppe und unter part die Felder manufacturer, name und listPrice, die null sein können und dann leer bleiben. Ohne bestätigten Basistreffer antwortet der Aufruf mit 404.
5. Passung prüfen, bevor bestellt wird. Alle Positionen gehen gesammelt an POST /vin/cart-check mit mode=vehicle, bis zu 30 je Aufruf. Je Position kommt fits zurück; complete steht einmal auf Antwortebene und sagt, ob die Teileliste des Fahrzeugs vollständig vorlag. Bei complete=true werden Positionen mit fits=false vor der Bestellung markiert; bei complete=false bleibt jedes Nein dieser Prüfung eine offene Frage. Antwortet der Dienst mit 202, holt Ihr System das Ergebnis über GET /vin/cart-check/jobs/{jobId} ab.
6. Alternativen und Gebrauchtteile anbieten. Für eine Position ohne Passung oder Lieferbarkeit liefert GET /parts/oe/{oeNumber}/aftermarket-references Suchkandidaten aus dem freien Teilemarkt, keine Passungsgarantie. Ein Gebrauchtteil vom Verwerter ist eine weitere Option; welche Angaben die Werkstatt dafür braucht, steht in Werkstätten als Kunden: Was der gewerbliche Käufer anders braucht.
7. Ausgebautes Teil erfassen. Der Mechaniker fotografiert das Etikett; POST /scanner/label/extract-partnumbers liest Teile- und Referenznummern aus und legt sie am Auftrag ab. Was auf dem Bild nicht lesbar ist, bleibt eine Lücke.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"vin":"<VIN>","mode":"vehicle","oeNumbers":["5Q0919275C"]}' \
  'https://api.tapinomahub.com/vin/cart-check'

Der Einbau

1. Schlüssel serverseitig hinterlegen. Der X-Api-Key gehört in die Konfiguration Ihres Servers, nie in die Werkstatt-Oberfläche oder eine mobile App. Bei einer Installation vor Ort ruft ein Dienst auf dem Werkstattserver auf.
2. Mit einem Endpunkt anfangen. Für diese Fachgruppe ist das POST /vin/cart-check: Er setzt dort an, wo Fehler am teuersten sind, und braucht nur Daten, die der Auftrag schon hat.
3. Feldzuordnung festlegen. fits in die Auftragsposition, complete der Antwort an alle Positionen dieser Prüfung, tapiGenArt in die Warengruppe, die aktuelle Nummer der Ersetzungskette in ein eigenes Feld neben der erfassten. Diese Abbildung ist die eigentliche Arbeit.
4. Leerbefund und Fehlerfall trennen. 404 vehicle_not_found oder eine leere Referenzliste sind fachliche Ergebnisse: Der Auftrag bleibt, das Feld bleibt leer, ein Hinweis erscheint. Ein technischer Fehler löst eine Wiederholung oder Nacharbeit aus — nie einen Standardwert.
5. Die Abholung nach `202` einbauen. Lang laufende Prüfungen antworten mit 202, Location, Retry-After und Job-ID. Ihr System fragt GET /vin/cart-check/jobs/{jobId} ab, ohne die Auftragsmaske zu blockieren.
6. Ausrollen und beobachten. Erst ein Pilotbetrieb, dann breit. GET /client/usage zeigt, welche Aufrufe wie oft laufen; der Header X-Tapinoma-Usage-Warning meldet knappes Guthaben.

Worauf zu achten ist

• `Idempotency-Key` bei jedem POST setzen. Ein zweiter Klick auf „Prüfen“ darf keine zweite Prüfung auslösen; X-Tapinoma-Idempotent-Replay zeigt eine wiederholte Antwort an. Ausnahme: POST /client/partner-workspaces gibt den Schlüssel einmalig aus — nach einem Timeout den Bestand über externalReference abgleichen statt neu anlegen.
• Leere Felder nicht füllen. Ist name oder listPrice null, bleibt das Feld im Auftrag leer. Ein plausibler Listenpreis aus anderer Quelle ist gefährlicher als eine sichtbare Lücke.
• Die `tapiId` am Fahrzeug speichern. Sie ist stabil und hält GET /vehicles/{tapiId} beim nächsten Besuch dem bereits bezahlten VIN-Ablauf zugeordnet.
• Den Schlüssel nie in den Browser geben. Auch nicht für den Redirect: POST /vin/redirect-sessions ruft Ihr Server auf, der Browser bekommt nur die redirectUrl.
• Rate-Limits je Werkstatt setzen. PUT /client/users/{clientId}/rate-limits begrenzt je Nutzer, Schlüssel oder Endpunkt, damit ein Betrieb nicht das Kontingent der anderen aufbraucht.
• Das Ergebnis prüfen lassen, nicht durchreichen. fits=true ist ein Abgleich, kein Einbauversprechen; eine Aftermarket-Referenz ein Suchkandidat. Die Software zeigt Herkunft und Konfidenz, die Werkstatt entscheidet.

Was die Schnittstelle nicht tut

Sie ersetzt keinen Teilekatalog des Herstellers und liefert keine Einbauanleitung. POST /vin/cart-check gleicht ab, ob eine OE-Nummer zum Fahrzeug passt; Lieferbarkeit und Preis sagt der Aufruf nicht — GET /parts/oe/{oeNumber}/price liefert eine indikative Bewertung, keine Preisgarantie. Der Rückrufabgleich ist eine Arbeitshilfe auf Baureihenebene, keine amtliche Auskunft. Ein Halter wird nirgends ermittelt, ein Gutachten nirgends erstellt. Bei Provider 1 läuft der Fahrzeugabgleich ausschließlich über den Redirect in die tapinoma-Oberfläche; ein Drittsystem kann ihn nicht direkt abrufen. Was keine Quelle belegt, bleibt leer: Ein Leerbefund ist kein Fehler, sondern das Ergebnis. Verkauft wird der Abgleich, nicht ein Datenbestand; Prüfung und Verwendung der Ergebnisse liegen bei der Werkstatt.