ERP und Warenwirtschaft: Artikel anlegen, Passung prüfen, je Endkunde abrechnen

Wo im Prozess Daten fehlen

Ein Artikelstamm im Teilehandel entsteht selten am Stück. Er wächst aus Lieferscheinen, Etiketten, Katalogsuchen und Zurufen aus dem Lager — und an jeder dieser Stellen wird heute etwas abgetippt, geschätzt oder offen gelassen:

• Artikelanlage aus einer Nummer. Die OE-Nummer kommt vom Etikett, vom Lieferschein oder aus einem Foto in mehreren Schreibweisen. Ob 5Q0 919 275 C und 5Q0919275C derselbe Artikel sind, entscheidet heute der Sachbearbeiter — mehr dazu unter OE-Nummer: Die Originalteilenummer richtig lesen.
• Bezeichnung, Hersteller und Artikelart. Der Artikel heißt „Sensor“, weil das Feld gefüllt sein musste. Eine belegte Bezeichnung, eine Artikelart und die Ersetzungskette fehlen.
• Preisfindung. Der Verkaufspreis eines Gebrauchtteils wird aus dem Gedächtnis gesetzt, weil eine Vergleichsgrundlage im System nicht vorliegt.
• Passung im Auftrag. Ein Kunde bestellt fünf Positionen für ein Fahrzeug, und ob sie passen, klärt sich beim Einbau — oder in der Retoure.
• Etiketten im Wareneingang. Zuliefernummer, OE-Nummer und Referenzen stehen auf dem Etikett und werden per Hand in die Maske übertragen, siehe Teileidentifikation: Vom Ausbauteil zum verkaufsfähigen Datensatz.

Was die Schnittstelle liefert

Ein Ablauf von Anfang bis Ende

1. Wareneingang: Etikett fotografieren. Das ERP schickt das Bild an POST /scanner/label/extract-partnumbers und erhält Teile- und Referenznummern. Was auf dem Bild nicht lesbar ist, kommt nicht zurück — die Analyse wird trotzdem berechnet, weil sie erbracht wurde.
2. Nummer bereinigen. GET /parts/oe/normalize bringt die gelesene Nummer in die Vergleichsform; ambiguous und invalid landen in einer Klärliste statt im Artikelstamm.
3. Artikel anlegen. GET /parts/oe/{oeNumber} liefert bei bestätigtem Treffer 200 mit Bezeichnung, Hersteller, Artikelart und Ersetzungskette; 404 heißt: kein Treffer im OE-Bestand, kein Fehler.
4. Preis vorschlagen. GET /parts/oe/{oeNumber}/price gibt eine indikative Bewertung, die der Sachbearbeiter sieht und bestätigt. Sie ersetzt nicht die Preisentscheidung.
5. Auftrag prüfen. Vor der Auftragsbestätigung sendet das ERP die VIN und die OE-Positionen an POST /vin/cart-check, mit mode=type für den Fahrzeugtyp oder mode=vehicle für das konkrete Fahrzeug.
6. Ausgeben. Für mehrsprachige Marktplätze und Belege übersetzt GET /translation/translations die Bezeichnung; der Artikel geht mit belegten Feldern in Lager und Verkauf, siehe Lager im Verwerterbetrieb: Der Platz, der das Teil wiederfindet.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "<KUNDENNAME>",
    "externalReference": "erp-kunde-4711",
    "endpointKeys": ["parts.oe", "vin.cart_check"],
    "sponsorship": true
  }' \
  'https://api.tapinomahub.com/client/partner-workspaces'

Der Einbau

1. Schlüssel serverseitig hinterlegen. Der X-Api-Key gehört in die Konfiguration Ihres Backends. Er darf nie in einen Browser oder ein Client-Bundle gelangen — auch nicht „nur für den Test“.
2. Mit einem Endpunkt beginnen. Für ein ERP ist das fast immer GET /parts/oe/{oeNumber} hinter der Artikelanlage. Die Reihenfolge Vertrag, Schlüssel, Prozess, Go-live beschreibt der Integrationsleitfaden.
3. Feldzuordnung festlegen. Bezeichnung, Hersteller, Artikelart und Ersetzungskette haben feste Ziele im Stamm; die tapiGenArt bekommt ein eigenes Feld, damit Filter und Marktplätze darauf zugreifen, siehe GenArt-Nummer: Was für ein Teil ist das eigentlich?.
4. Leerbefund und Fehler trennen. 404 bei der OE-Abfrage ist ein fachliches Ergebnis: kein bestätigter Treffer. Das ERP legt den Artikel an, lässt die Felder leer und erzeugt eine Klärungsaufgabe. Nur ein technischer Fehler wird wiederholt.
5. Asynchrone Antworten abholen. Warenkorbprüfungen können mit 202, Location und Retry-After antworten. Das ERP merkt sich die Job-ID und fragt GET /vin/cart-check/jobs/{jobId} ab, statt den Aufruf zu wiederholen.
6. Ausrollen. Zuerst bei einem Endkunden, dann in der Breite. GET /client/usage und je Workspace GET /client/users/{clientId}/usage zeigen, welche Aufrufe wie oft laufen.

Worauf zu achten ist

• `Idempotency-Key` setzen. Bei wiederholbaren Aufrufen wie der Warenkorbprüfung schützt der Header vor Doppelbuchungen nach einem Timeout; X-Tapinoma-Idempotent-Replay zeigt die Wiederholung an. Ausnahme: POST /client/partner-workspaces gibt einen geheimen Schlüssel einmalig aus und wird nicht gereplayt — nach einem Timeout den Bestand abgleichen, nicht blind wiederholen.
• Leere Felder nicht füllen. Kommt manufacturer, name oder listPrice als null, bleibt das Stammdatenfeld leer, und der Artikel bekommt eine Klärungsaufgabe. Ein Standardwert im Artikelstamm ist gefährlicher als eine sichtbare Lücke.
• `tapiId` speichern. Wo ein Fahrzeug über einen VIN-Ablauf abgeglichen wurde, gehört die tapiId in die Fahrzeugakte; GET /vehicles/{tapiId} liefert die technischen Daten als Bestandteil dieses bezahlten Ablaufs, ohne VIN und ohne Ausstattung.
• Schlüssel nie im Browser. Auch ein Web-ERP ruft die API aus dem Backend auf; der Browser spricht nur mit Ihrem Server.
• Rate-Limits je Workspace setzen. PUT /client/users/{clientId}/rate-limits begrenzt je Nutzer, Schlüssel oder Endpunkt, damit ein fehlerhafter Import bei einem Endkunden nicht das Kontingent aller anderen aufbraucht.
• Ergebnis prüfen lassen. Preisbewertung und Passungsangaben sind Grundlagen für eine Entscheidung im ERP, nicht die Entscheidung. Der Sachbearbeiter bestätigt, das System dokumentiert, woher ein Wert stammt.

Was die Schnittstelle nicht tut

Die Schnittstelle verkauft keinen Datenbestand: Geschuldet ist die Abfrage und die Ausgabe des Ergebnisses; die Prüfung vor der Verwendung liegt beim Kunden. Die Preisbewertung ist indikativ und keine Preisgarantie. Fahrzeugdaten des Providers 1 dürfen von Drittsystemen nicht direkt abgerufen werden: GET /vin/{vin}/vehicle antwortet dort mit redirect_required, der Abgleich läuft über eine Browser-Session aus POST /vin/redirect-sessions, die nach zehn Minuten verfällt; Provider 2 und 3 sind direkt abfragbar. Eine Halterabfrage, ein Gutachten oder eine Restwertkalkulation liefert die API nicht. Und wo ein Feld nicht belegt ist, bleibt es null — die Schnittstelle rät nicht, und Ihr ERP sollte es auch nicht tun.