Vom Teilefoto zum Inserat: der Bildweg durch die tapinomahub API

Wer online mit Teilen wächst, scheitert selten am Lager und fast immer an der Erfassung. Das Teil liegt ausgebaut da, die Nummer steht auf dem Typenschild, und trotzdem vergehen Minuten mit Abtippen, Kategoriesuche und Freistellen. Der Bildweg der tapinomahub API dreht die Reihenfolge: Das Foto ist nicht das Letzte, was an ein Inserat kommt, sondern das Erste, aus dem es entsteht.

Was der Bildweg voraussetzt

• Eine abrufbare Bildadresse. Die Bilddienste nehmen imageUrl entgegen, keine hochgeladene Datei. Das Bild muss also in Ihrem Speicher, Ihrem Shop oder einem signierten Objektspeicher öffentlich abrufbar liegen — zeitlich begrenzte Adressen genügen.
• Eine Aufnahme, die etwas hergibt. Ein Vorschaubild mit 200 Pixeln Kantenlänge enthält kein lesbares Typenschild. Laden Sie die größte vorhandene Fassung, nicht die, die im Katalog angezeigt wird.
• Das Recht an der Aufnahme. Mit dem Absenden bestätigen Sie, dass Sie zur Übermittlung und automatisierten Verarbeitung befugt sind. Personenbezogene Inhalte — etwa ein Kennzeichen im Hintergrund — brauchen eine Rechtsgrundlage und gehören, wo möglich, aus dem Bild.
• Eine Entscheidung über die Verarbeitungsstufe. quality kennt standard, enhanced und maximum. Die Stufen unterscheiden sich in Bearbeitungsumfang und Antwortzeit; welche Stufe was kostet, richtet sich nach Ihrem Vertrag.

Schritt 1: Das Etikett lesen

POST /scanner/label/extract-all analysiert eine Etikettaufnahme und gibt alle mit ausreichender Sicherheit erkannten Angaben strukturiert zurück — nicht nur die Teilenummer. Der Aufruf ist der aufwendigste Schritt des ganzen Weges und ersetzt die meiste Handarbeit. Details zu Nutzung und Abrechnung stehen im Artikel Alle erkennbaren Etikettinformationen extrahieren.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: teil-4711-etikett' \
  -d '{"imageUrl":"https://example.com/steuergeraet.jpg","quality":"maximum"}' \
  'https://api.tapinomahub.com/scanner/label/extract-all'

Schritt 2: Aus einer Ablesung eine belastbare Nummer machen

Eine abgelesene Zeichenfolge ist noch keine OE-Nummer. Sie kann Bindestriche tragen, die der Katalog nicht kennt, eine Zuliefernummer sein oder zu mehreren Herstellern passen. Zwei Aufrufe klären das, bevor irgendetwas gespeichert wird.

1. `GET /parts/oe/normalize` prüft die Schreibweise und antwortet mit status: matched, unresolved, ambiguous oder invalid. Bei einem Treffer stehen normalizedOeNumber, lookupKey, matchRule und confidence in der Antwort, dazu equivalentOeNumbers mit gleichwertigen Schreibweisen. Siehe OE-Nummer normalisieren und validieren.
2. `POST /parts/identify` entscheidet, wenn mehrere Quellen im Spiel sind. Der Aufruf nimmt die Kundennummer, die Ablesung aus Schritt 1 als labelReadings und — falls vorhanden — die VIN des Spenderfahrzeugs. Zurück kommt status mit matched, candidates oder unresolved, dazu source mit customer, label oder vin_parts_list und eine Kandidatenliste mit score und reasons.
3. Bei `candidates` entscheidet ein Mensch. Die Liste ist nach Bewertung sortiert und nennt die Gründe; sie ist eine Vorauswahl, keine Festlegung. Genau hier gehört im ERP ein Prüfkorb hin, kein automatischer Übernahmeschritt.
4. Bei `unresolved` bleibt das Feld leer und der Vorgang bekommt eine Aufgabe. Ein unbestimmtes Teil kann fotografiert, eingelagert und später bestimmt werden — inseriert wird es nicht.

Schritt 3: Die Teiledaten hinter der Nummer

Mit der bestätigten Nummer liefert GET /parts/oe/{oeNumber} die Bezeichnung, den Hersteller, die Fahrzeugzuordnungen in fitment, die dokumentierten Ersetzungskanten in replacementChain und die nach Hersteller gruppierten Vergleichsnummern in references. Dieser Teil des Weges ist derselbe, den der Artikel Von der OE-Nummer zum marktplatzfertigen Artikel ausführlich beschreibt — dort stehen auch die Feldbedeutungen im Einzelnen und der Grund, warum aus einer Referenznummer keine Passungsaussage wird.

Schritt 4: Das Galeriebild

Das erste Bild entscheidet über den Klick. POST /vision/part/remove/bg stellt das Bauteil frei und liefert ein PNG: mit background: "transparent" einen Alphakanal, mit background: "white" eine Fläche aus reinem Weiß. Die Vorgabe ist transparent, weil Weiß sich nachträglich hinterlegen, aber nicht wieder entfernen lässt. Der Vorgang wird im Artikel Bauteilfoto freistellen beschrieben.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"imageUrl":"https://example.com/stossfaenger.jpg","background":"transparent","partType":"Stoßfänger vorn"}' \
  'https://api.tapinomahub.com/vision/part/remove/bg'

• `found` sagt, ob überhaupt ein Gegenstand erkannt wurde. Ist der Wert false, ist imageUrl null — und das Inserat behält sein Originalfoto, statt ein leeres Bild zu zeigen.
• `coverage.cropped` und `coverage.touchesImageEdge` melden, dass der Gegenstand über den Bildrand hinausläuft. Solche Aufnahmen gehören wiederholt, nicht veröffentlicht.
• `sourcePixelsPreserved` bestätigt, dass die Bildpunkte des Gegenstands aus der eingereichten Aufnahme stammen. Das Verfahren bestimmt den Umriss; es malt das Teil nicht neu.
• `limitations` nennt, was am Ergebnis unsicher blieb — etwa eine Kante im Schatten. Der Hinweis gehört in die Prüfliste der Freigabe.
• `422 part_segmentation_failed` ist die ehrliche Antwort, wenn sich das Bauteil nicht sicher von Hintergrund oder angrenzenden Flächen trennen ließ. Es kommt kein halb freigestelltes Bild zurück.

Schritt 5: Kennungen, die nicht ins Netz gehören

Auf Steuergeräten, Kombiinstrumenten und Schlüsseln stehen Nummern, die nicht den Teiletyp bezeichnen, sondern das einzelne Stück: Seriennummern, IMEI, Kalibriercodes, Datamatrix-Felder. POST /vision/identifiers/redact macht sie im Bild unlesbar und gibt nur dann ein Bild aus, wenn die Anonymisierung bestätigt werden konnte — andernfalls 422 identifier_redaction_unverified und gar kein Bild. Warum das wirtschaftlich und rechtlich zählt, steht in Kennungen auf Teilebildern anonymisieren, ohne die OE-Nummer zu verlieren.

Schritt 6: Der Zustand, den der Käufer sehen will

POST /vision/part/quality nimmt eine bis drei Aufnahmen desselben Bauteils und liefert eine Einstufung: grade mit A, B oder C, die Einzelkriterien in criteria — Gebrauchsspuren, Korrosion, Verformung, Kratzer, Lackzustand, Vollständigkeit, Verschmutzung —, dazu reworkEffort und refinishEffort als Aufwandsklassen. visualOnly stellt klar, woran das Urteil hängt: am Sichtbaren. Ein Getriebe, das innen Späne hat, sieht von außen unauffällig aus. Ist das Bild für eine Einstufung nicht geeignet, steht gradable: false mit einer Begründung in reason, und es wird keine Stufe geraten. Mehr dazu in Gebrauchtteile nach Bildern bewerten: Zustand, Schaden und Grenzen.

Was der Weg kostet und wie er sich verhält

• Die Analyse ist die Leistung. Ein Bilddienst, der durchläuft und antwortet, hat geliefert — auch wenn auf dem Foto keine Nummer zu sehen war. Erstattet wird ein Fehlschlag, nicht ein Leerbefund. Das ist der Grund, unscharfe Aufnahmen vorher auszusortieren statt hinterher zu diskutieren.
• `Idempotency-Key` schützt vor Doppelbelastung. Dieselbe Wiederholung mit demselben Schlüssel liefert dasselbe Ergebnis ohne erneute Ausführung. Läuft der erste Aufruf noch, antwortet die API mit 409 idempotency_request_in_progress.
• Ein Aufruf je Client gleichzeitig. Weitere parallele Anfragen werden mit 429 client_request_in_progress abgewiesen. Eine Warteschlange im ERP ist deshalb Pflicht, kein Feinschliff.
• `402 insufficient_credits` bedeutet, dass kein Plan den Endpunkt deckt und Guthaben samt Rahmen nicht reichen. Der Header X-Tapinoma-Usage-Warning warnt vorher, ab 90 Prozent Planverbrauch.
• Ergebnisse gehören in Ihre Datenbank. Kein Aufruf bei jedem Seitenaufruf, keine zweite Abfrage für denselben Artikel. Die Felder aus Schritt 1 bis 3 ändern sich nicht, solange das Teil dasselbe bleibt.

Der Einbau in ERP, Shop und Marktplatz

1. Aufnahmeroutine festlegen: ein Bild vom Bauteil, ein Bild vom Typenschild, beide in der höchsten Auflösung, beide unter einer abrufbaren Adresse.
2. Schritt 1 aufrufen und die Antwort vollständig speichern, nicht nur die Teilenummer. Die übrigen Felder gehören zur Antwort dieses Auftrags und beantworten später Fragen, die heute niemand stellt.
3. Schritt 2 durchlaufen und das Ergebnis als matched, candidates oder unresolved im Vorgang festhalten — mit confidence und source, damit später erklärbar ist, woher die Nummer kam.
4. Teiledaten und Marktplatzdaten holen, Felder auf Ihre Artikelfelder abbilden. Diese Abbildung ist die eigentliche Arbeit der Anbindung, nicht der Aufruf.
5. Bilder erzeugen: freigestelltes Galeriebild, bei Elektronik zusätzlich die anonymisierte Fassung. Beide Dateien in Ihren Speicher legen, nicht auf die Antwortadresse verlinken.
6. Freigabegrenze ziehen: Was automatisch veröffentlicht wird, braucht bestätigte Nummer, ein Bild mit found: true und eine Zustandsstufe. Alles andere landet im Prüfkorb.
7. Nach zwei Wochen messen: Bearbeitungszeit je Artikel, Anteil des Prüfkorbs, Korrekturquote nach Veröffentlichung, Rückläufer wegen falscher Passung.

Grenzen, die man kennen muss

• Kein Bild liefert Passgenauigkeit. Die Zuordnung entsteht aus der bestätigten Nummer und den Referenzdaten, nicht aus dem Foto. Eine Verwendungsliste ist eine Dokumentation, keine Zusicherung.
• Verdeckte Schäden bleiben verdeckt. Die Einstufung ist ausdrücklich visuell. Für Aggregate gehört eine Funktionsprüfung dazu, und zwar in die Artikelbeschreibung.
• Hersteller- und Markennamen sind Verweise, keine Herkunftsangabe. Ein Gebrauchtteil wird als solches beschrieben. Irreführende Angaben über wesentliche Merkmale sind nach § 5 UWG unzulässig, unabhängig davon, aus welcher Datenquelle sie stammen.
• Marktplatzdaten sind Veröffentlichungstext, keine Passungsaussage. Vor der Veröffentlichung prüft der Betrieb, was er veröffentlicht — das gilt für Titel, Kategorie und Artikelmerkmale gleichermaßen.
• Die Abdeckung ist nicht überall gleich. Zu seltenen Baureihen und sehr alten Teilen liegen weniger Referenzdaten vor. Eine leere Liste ist eine Auskunft über den Datenbestand, keine Aussage über das Teil.

Die vollständigen Schemata, Fehlercodes und Beispielantworten stehen in der Entwicklerdokumentation. Wer denselben Artikel nicht vom Bild, sondern von der Nummer oder vom Fahrzeug aus aufbaut, findet den Weg in Von der OE-Nummer zum marktplatzfertigen Artikel und Von der VIN zur Wirtschaftlichkeitsanalyse: der Fahrzeugweg.