Marktplätze und Shopsysteme für Teile: Angebote aus der OE-Nummer anreichern

Wo im Prozess Daten fehlen

Ein Marktplatz ist so gut wie die Datensätze seiner Verkäufer, und die kommen selten vollständig an. Was der Verkäufer nicht liefert, muss die Plattform ergänzen oder leer lassen — und leere Felder kosten Sichtbarkeit, siehe Bestandsdaten für Marktplätze. Die typischen Stellen:

• Beim Einstellen. Der Verkäufer trägt eine OE-Nummer ein, aber keine Artikelart und keine Vorgängernummern. Die Kategorie kommt aus einem Aufklappmenü, und Käufer suchen mit der Nummer auf ihrem ausgebauten Teil — die ist oft älter als die im Angebot.
• Bei mehrsprachigen Angeboten. Die Teilebezeichnung wird je Sprache von Hand übersetzt oder bleibt in der Ausgangssprache stehen.
• Bei den Bildern. Aufnahmen aus der Halle haben unruhige Hintergründe, und der Zustand steht als Freitext daneben, den niemand einheitlich vergibt.
• Nach dem Einstellen. Ob ein angebotenes Teil von einem Rückruf betroffen ist, prüft niemand, weil die Register nicht an den Bestand angeschlossen sind.
• Auf der Käuferseite. Ob das Teil zum Fahrzeug des Käufers passt, wird per Rückfrage geklärt oder gar nicht — und die Retoure entsteht nach dem Versand.

Was die Schnittstelle liefert

Ein Ablauf von Anfang bis Ende

1. Der Verkäufer stellt ein Teil ein. Ihre Software ruft GET /parts/oe/{oeNumber} auf. Kommt 200, übernehmen Sie die normalisierte Nummer, die tapiGenArt als Grundlage der Kategorie und die Ersetzungskette in das Nummernfeld — siehe GenArt-Nummer. Kommt 404, gab es keinen bestätigten Basistreffer: Das Angebot wird trotzdem angelegt, die Felder bleiben leer.
2. Suchfelder und Sprachfassungen. GET /parts/oe/{oeNumber}/seo liefert Produkt-, Inhalts- und Merkmalsfelder für Sprache und Marktplatz. Die Teilebezeichnung geht einzeln durch GET /translation/translations.
3. Bilder aufbereiten. Jede Aufnahme des Verkäufers läuft durch POST /vision/part/remove/bg; das Modell bestimmt nur den Umriss, das Zusammensetzen geschieht im Code. Ein bis drei Aufnahmen desselben Teils gehen an POST /vision/part/quality und liefern eine Stufe, die Sie als Sichtprüfung kennzeichnen — siehe Teilebilder.
4. Neuteile ohne Aufnahme. Für Neuteile ohne eigenes Foto startet POST /vision/part/generate einen Produktbild-Job. Standard ist references_required; wer knowledge_only wählt, bekommt basis=knowledge und partIdentityVerified=false zurück und zeigt das Bild als Darstellung, nicht als Foto.
5. Nächtlicher Rückrufdurchlauf. Ein Job schickt den aktiven Bestand in Paketen von bis zu 100 Positionen an POST /recalls/parts, mit vehicle.make und vehicle.model, wo bekannt. Betroffene Angebote bekommen einen Hinweis und eine Aufgabe für den Verkäufer.
6. Der Käufer legt in den Warenkorb. Gibt er seine VIN an, prüft POST /vin/cart-check bis zu 30 Positionen dagegen — mode=type für den Fahrzeugtyp, mode=vehicle für das konkrete Fahrzeug. fits=false mit complete=true ist ein abschließendes Nein; complete=false bleibt eine offene Frage — siehe Gebrauchtteile online verkaufen.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  'https://api.tapinomahub.com/parts/oe/5Q0919275C'

Der Einbau

1. Schlüssel serverseitig hinterlegen. Der Schlüssel im Header X-Api-Key gehört in die Konfiguration Ihres Backends — nie in den Browser, nie in einen Feed, nie in ein Verkäuferkonto. Der Weg von Vertrag bis Go-live steht in der Dokumentation.
2. Mit einem Endpunkt beginnen. Für Marktplätze ist das GET /parts/oe/{oeNumber} beim Einstellen: ein Aufruf, drei gefüllte Felder, sofort messbar an der Nummernsuche.
3. Feldzuordnung festlegen. tapiGenArt auf Ihre Kategorie, die Ersetzungskette in das Nummernfeld, part.manufacturer und part.name in die Angebotsfelder — und jedes Feld, das null liefert, bleibt bei Ihnen leer.
4. Fehlerfall und Leerbefund trennen. 404 beim OE-Abgleich, found=false beim Freistellen und gradable=false bei der Zustandsstufe sind Leerbefunde: Angebot anlegen, Feld leer lassen, Aufgabe erzeugen. Nur ein technischer Fehler wird wiederholt.
5. Antworten mit 202 abholen. POST /vin/cart-check und POST /vision/part/generate antworten bei längeren Vorgängen mit 202, Location, Retry-After und einer Job-ID. Der Status kommt aus GET /vin/cart-check/jobs/{jobId} beziehungsweise GET /vision/part/generation-jobs/{jobId} — im Abstand von Retry-After.
6. Ausrollen und beobachten. Erst eine Verkäufergruppe, dann alle. GET /client/usage zeigt, welche Aufrufe wie oft laufen; der Header X-Tapinoma-Usage-Warning meldet sich, bevor das Guthaben ausgeht.

Worauf zu achten ist

• Idempotency-Key setzen. Läuft ein Aufruf nach einem Neustart doppelt, wird die Wiederholung über den Header Idempotency-Key erkannt und im Antwortheader X-Tapinoma-Idempotent-Replay ausgewiesen. Ausnahme: Aufrufe, die einen Schlüssel einmalig ausgeben — nach einem Timeout Bestand abgleichen statt erneut anlegen.
• Leere Felder nicht füllen. Ein null in part.listPrice ist eine Aussage. Wer daraus einen Platzhalter macht, erzeugt die Retouren, die die Sichtbarkeit wieder aufzehren.
• SEO-Inhalte nicht als Passung anzeigen. Die SEO-Anreicherung erstellt Veröffentlichungstexte und Artikelmerkmale. Eine Passungsaussage muss aus dem dafür vorgesehenen Teile- oder VIN-Abgleich stammen.
• tapiId speichern. Hat ein Käuferkonto ein Fahrzeug über einen VIN-Ablauf abgeglichen, behalten Sie die tapiId; GET /vehicles/{tapiId} liefert die technischen Daten als Bestandteil des zuvor bezahlten VIN-Ablaufs, ohne VIN und ohne Ausstattung.
• Ergebnisse speichern, nicht bei jedem Seitenaufruf abfragen. Was GET /parts/oe/{oeNumber} liefert, gehört an die Nummer in Ihrer Datenbank; jede Anfrage wird aus dem Guthaben berechnet.
• Schlüssel nie im Browser. Auch der Warenkorb-Check läuft über Ihr Backend; die VIN des Käufers steht nie in einer Seiten-URL. Rate-Limits je Workspace begrenzen einen Feed, der nachts alles neu einstellt.
• Ergebnis vor Veröffentlichung prüfen. Die SEO-Anreicherung ist zur Prüfung gedacht, nicht zur ungesehenen Ausspielung. Die Verwendung der Ergebnisse liegt beim Kunden.

Was die Schnittstelle nicht tut

Die Schnittstelle liefert Abgleiche und Analysen, keinen Datenbestand: Geschuldet ist die Abfrage, die Verwendung und Prüfung der Ergebnisse liegt bei Ihnen und Ihren Verkäufern. Die Preisbewertung aus GET /parts/oe/{oeNumber}/price ist indikativ und keine Preisgarantie. Die Zustandsstufe ist eine Sichtprüfung, kein Gutachten; ein Kennzeichen auf einem Bild führt zu keiner Halterabfrage. Fahrzeugdaten von Provider 1 werden von Drittsystemen nicht direkt abgerufen — dafür gibt es den Browser-Redirect über POST /vin/redirect-sessions, dessen Session nach zehn Minuten verfällt und weder Fahrzeug- noch Zugangsdaten enthält. Und wo die Quellen nichts hergeben, bleibt das Feld leer — eine Referenz ist keine Passung, und eine Aufnahme ohne belastbare Aussage bekommt keine Stufe.