Von der OE-Nummer zum marktplatzfertigen Artikel

Die OE-Nummer ist die Währung des Teilehandels. Sie steht auf dem Etikett, auf der Rechnung, in der Kundenanfrage und in der Teileliste des Spenderfahrzeugs. Nur: Eine Nummer allein verkauft nichts. Zwischen „5Q0941773B“ und einem Artikel, den eine Suchmaschine findet und ein Marktplatzfilter durchlässt, liegen Bezeichnung, Verwendung, Vergleichsnummern, Kategorie und Artikelmerkmale. Dieser Weg beschreibt, welche Aufrufe der tapinomahub API diese Strecke abnehmen.

Warum die Nummer zuerst normalisiert wird

Dieselbe Nummer wird im Betrieb in einem halben Dutzend Schreibweisen geführt: mit Bindestrichen, mit Leerzeichen, in Kleinbuchstaben, mit angehängtem Farbindex. GET /parts/oe/normalize prüft die Schreibweise gegen die bekannten Regeln und antwortet mit einem status, der über den weiteren Verlauf entscheidet. Der Aufruf ist billig, schnell und verhindert die teuerste Art von Fehler: eine saubere Abfrage auf eine Nummer, die es nicht gibt.

Der Kern: Teil, Fitment, Ersetzung, Referenzen

GET /parts/oe/{oeNumber} ist der zentrale Aufruf des ganzen Weges. Er gibt vier inhaltlich getrennte Listen zurück, die im Betrieb oft verwechselt werden — und genau diese Trennung ist der Wert der Antwort. Die Leistungsbeschreibung steht in OE-Teilname, Fitment, Referenzfamilie und Ersetzungskette abgleichen.

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

Wenn der freie Markt gefragt ist

Viele Kunden kennen nicht die OE-Nummer, sondern die Nummer des Zubehörherstellers. GET /parts/oe/{oeNumber}/aftermarket-references gibt die ermittelten IAM-Referenzen aus: je Eintrag partNumber in der originalen Schreibweise, normalizedPartNumber ohne Sonderzeichen und manufacturer. count nennt die Gesamtzahl; mit limit und offset wird die Liste seitenweise geholt, und page.hasMore sagt, ob noch etwas fehlt. Sind keine Referenzen vorhanden, ist die Antwort erfolgreich und die Liste leer — das ist kein Fehler, siehe Aftermarket-Referenzen zu einer OE-Nummer ermitteln.

Die Marktplatzseite: Titel, Kategorie, Artikelmerkmale

GET /parts/oe/{oeNumber}/seo ist der Aufruf, der aus Teiledaten Verkaufstext macht. marketplaceId wählt den Marktplatz — dokumentiert sind die eBay-Marktplätze EBAY_AT bis EBAY_US, Vorgabe ist EBAY_DE. language wählt die Sprache des erzeugten Textes, vehicleType unterscheidet car und motorcycle. Ausführlich beschrieben in Artikel für eBay und Marktplätze optimieren (SEO-Anreicherung).

curl \
  -H 'X-Api-Key: <API_KEY>' \
  'https://api.tapinomahub.com/parts/oe/5Q0919275C/seo?marketplaceId=EBAY_FR&language=fr&vehicleType=car'

• `404 seo_no_exact_match` bedeutet: Zur Nummer gibt es im gewählten Fahrzeugpfad keinen exakten Treffer. Die Antwort nennt oeNumber, marketplaceId, language und vehicleType — prüfen Sie zuerst vehicleType.
• `400 unsupported_marketplace_language` heißt, dass der gewählte Marktplatz diese Sprache nicht führt. Die Kombination gehört in Ihre Konfiguration, nicht in den Einzelaufruf.
• `liveAvailability` mit `status: "PAUSED"` zeigt, dass die Live-Anreicherung gerade pausiert; availableAt und retryAfterSeconds nennen den frühesten neuen Versuch. Dasselbe als Fehler: 429 seo_live_requests_paused.
• Das Ergebnis ist Veröffentlichungstext, keine Passungsaussage. Es ist vor der Veröffentlichung eigenständig auf Richtigkeit und Zulässigkeit zu prüfen — auch und gerade bei Artikelmerkmalen.

Der Preisrahmen, wenn Sie ihn brauchen

GET /parts/oe/{oeNumber}/price liefert eine indikative Bewertung: new und used mit min, max und average, dazu priceRecommendation mit confidence in HIGH, MEDIUM oder LOW. result sagt, woran man ist: priced heißt, es wurden verwertbare Angebote gefunden; no_listings_found heißt, es gab keine — dann stehen Nullwerte in der Antwort, und das ist kein Preis, sondern ein Leerbefund. Eine Bewertung mit LOW stützt sich auf wenige Angebote; ihre Mitte trägt keine Kaufentscheidung. Siehe Preisbewertung für ein OE-Teil ermitteln und Dynamische Preise bei Gebrauchtteilen, ohne die Kontrolle abzugeben.

Ersetzungsketten: der stille Umsatzhebel

Hersteller ersetzen Teilenummern im Lauf eines Modellzyklus mehrfach. Ein Artikel, der nur unter der ältesten Nummer geführt wird, ist für Kunden unsichtbar, die die neueste kennen — und umgekehrt. replacementChain macht diese Richtung sichtbar: from wird durch to ersetzt. Tragen Sie die gesamte Kette als Suchbegriffe und Vergleichsnummern am Artikel nach, und Ihr Lagerbestand wird unter jeder Nummer gefunden, die jemals gültig war. Mehr dazu in OE, OEM, OES und IAM: Der Unterschied in einer Übersicht und Neuteil, Gebrauchtteil, Austauschteil, Nachbau: vier Begriffe, zwei Achsen.

Abrechnung, Wiederholungen und Rate-Limits

• Leerbefund und technische Nichtausführung bleiben getrennt. Die kaufmännische Behandlung eines 404 oe_part_not_found richtet sich ausschließlich nach den vor dem Auftrag angezeigten und vertraglich vereinbarten Konditionen.
• `422 ambiguous_oe_number` heißt, dass die Nummer nicht eindeutig aufgelöst werden konnte. Geben Sie manufacturer mit, statt zu raten.
• Rate-Limits gelten je Endpunkt-Schlüssel, nicht pauschal für das Konto. Gleichzeitig ist ein aktiver Aufruf je Client zulässig; weitere Anfragen werden mit 429 client_request_in_progress abgewiesen.
• Antworten gehören in Ihre Datenbank. Teiledaten, Fitment und Referenzen ändern sich selten. Eine Wiederholung bei jedem Seitenaufruf kostet Geld und bringt nichts.
• Der Header `X-Tapinoma-Billing-Source` nennt die Abrechnungsentscheidung: plan, balance, bundle, sandbox oder idempotent_replay. Für die Buchhaltung ist er die verlässlichere Quelle als eine Vermutung.

Der Ablauf in der Warenwirtschaft

1. Nummer normalisieren und den status am Artikel festhalten. Nur matched führt ohne Rückfrage weiter.
2. Teiledaten holen und die vier Listen getrennt speichern. Wer Referenzen und Fitment in ein Feld wirft, kann später nicht mehr erklären, woher eine Angabe kommt.
3. IAM-Referenzen nachladen, wenn Sie Zubehörteile führen oder Ihre Kunden mit Zubehörnummern suchen. Bei langen Listen seitenweise arbeiten.
4. Marktplatzdaten je Zielkanal und Zielsprache abrufen. Ein Artikel für drei Länder braucht drei Aufrufe, nicht eine Übersetzung des deutschen Textes.
5. Artikelmerkmale auf die Pflichtfelder des Kanals abbilden und fehlende Pflichtfelder sichtbar machen, statt sie mit Vermutungen zu füllen.
6. Preisrahmen nur dort abrufen, wo er eine Entscheidung trägt — bei der Erstbepreisung und bei Liegezeiten, nicht bei jedem Artikel täglich.
7. Nach der Veröffentlichung messen: Ablehnungen des Kanals, Korrekturen, Rückläufer wegen Passung, Anteil der Artikel ohne Kategorie.

Grenzen, die man kennen muss

• Keine Passungszusicherung. Referenz, Fitment und Ersetzung sind Dokumentation. Die technische Prüfung am konkreten Fahrzeug bleibt beim Verwender.
• Leere Listen sind Auskünfte über Daten. Zu seltenen Baureihen, Sonderausführungen und sehr alten Teilen liegt weniger vor. Das ist eine Abdeckungsfrage, keine Qualitätsaussage über das Teil.
• Texte sind Vorschläge, nicht Freigaben. Marken- und Herstellernennungen dürfen Verweise sein, aber keine Herkunftsangabe vortäuschen; irreführende Angaben über wesentliche Merkmale sind nach § 5 UWG unzulässig.
• Ein Preisrahmen ist keine Preisgarantie. Die Ausgabe ist ausdrücklich indikativ und keine verbindliche Kauf- oder Verkaufsaussage.
• Kategorien und Merkmale ändern sich. Marktplätze überarbeiten ihre Strukturen. Eine Abfrage von vor zwei Jahren ist kein aktueller Stand, wenn der Kanal seine Felder umgebaut hat.

Alle Felder, Fehlercodes und Beispielantworten stehen in der Entwicklerdokumentation. Wer nicht von der Nummer, sondern von einem Foto oder von einem ganzen Fahrzeug ausgeht, findet die beiden anderen Wege in Vom Teilefoto zum Inserat: der Bildweg durch die tapinomahub API und Von der VIN zur Wirtschaftlichkeitsanalyse: der Fahrzeugweg.