Einen Katalog als Datei übertragen — mit Prüfhinweisen vor der Übernahme

Ein Händler exportiert seinen Artikelbestand einmal im Monat aus der Warenwirtschaft als CSV. Eine API-Anbindung ist nicht geplant, und sie wäre für diesen Rhythmus auch übertrieben. Das Risiko liegt woanders: Eine verrutschte Spalte in einer Datei mit zehntausend Zeilen macht aus Preisen Artikelnummern.

Die Katalogübertragung behandelt die Datei deshalb wie einen Synchronisationslauf: Erst entsteht eine Vorschau mit Zählern und Prüfhinweisen, dann wird gegen genau diese Vorschau entschieden. Angelegt wird die Übertragung laut Vertrag im kanonischen Commerce-Modell; ob sich die Prüfung je Format unterscheidet, legt der Vertrag nicht fest.

Was dieser Fall voraussetzt

• Eine hochgeladene Datei mit Token. Die Übertragung verweist über artifactToken auf die Datei; der Token wird nur geschrieben, nie zurückgegeben.
• Das richtige Format. serialization kennt csv, xml und json.
• Optional eine Verbindung. connectionId ist optional und verweist auf eine Verbindung; welche Wirkung die Angabe auf die Übertragung hat, beschreibt der Vertrag nicht.
• Jemanden, der die Hinweise liest. Die Freigabe ist nur so gut wie die Prüfung davor.

Der Ablauf

Die Tabelle nennt je Stufe den zuständigen Aufruf und das, was danach vorliegt. Die Begründung, warum die Stufe nicht übersprungen werden kann, steht darunter.

Warum jede Stufe nötig ist

1. Die Übertragung anlegen. POST /commerce/v1/catalog-transfers nimmt direction mit import oder export, serialization und artifactToken. Die Antwort trägt transferId, state und die ersten counts — noch ist nichts übernommen.
2. Den Stand lesen. GET /commerce/v1/catalog-transfers/{transferId} liefert state und counts mit read, changed, rejected und conflicted. Die vier Zahlen sind die erste Plausibilitätsprüfung: Zehntausend gelesen und zehntausend geändert ist bei einer Monatsdatei selten richtig.
3. Die Prüfhinweise lesen. GET /commerce/v1/catalog-transfers/{transferId}/issues listet je Hinweis severity, code, message, pointer und, sofern vorhanden, recordNumber. Mit recordNumber findet man die Zeile in der eigenen Datei, statt eine Fehlermeldung zu deuten.
4. Entscheiden. POST /commerce/v1/catalog-transfers/{transferId}/approval nimmt decision mit approve oder reject, dazu previewRevision und expectedRevision. Freigegeben wird die geprüfte Vorschau — hat sich der Stand inzwischen verändert, passt die Revision nicht mehr.
5. Die Ergebnisdatei holen. GET /commerce/v1/catalog-transfers/{transferId}/artifact liefert artifactToken, checksum und expiresAt. checksum ist eine Zeichenfolge aus 64 Hexadezimalzeichen; mit welchem Verfahren und worüber sie gebildet wird, legt der Vertrag nicht fest. expiresAt nennt den Ablaufzeitpunkt.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: katalog-import-2026-09' \
  -d '{"direction":"import","serialization":"csv","artifactToken":"<artifactToken>","connectionId":"<connectionId>"}' \
  'https://commerce-preview.invalid/commerce/v1/catalog-transfers'

Was am Ende vorliegt

Am Ende steht ein Katalog, der erst nach einer Freigabe gegen die geprüfte Vorschau übernommen wurde, und eine Ergebnisdatei mit checksum. Dass vor der Freigabe jemand Zähler und Prüfhinweise gelesen hat, erzwingt der Vertrag nicht; verlangt werden previewRevision und expectedRevision — deshalb gehört jemand, der die Hinweise liest, zu den Voraussetzungen. Eine verrutschte Spalte kann vor der Freigabe auffallen, wenn Zähler oder Prüfhinweise der Vorschau sie zeigen.

Wo das in der Dokumentation steht

Die verbindlichen Feldlisten, Fehlercodes und Beispielantworten stehen im OpenAPI-Vertrag dieser Fläche unter docs.tapinomahub.com (tapinoma-commerce). Alle Anwendungsfälle nach Fläche und Rolle geordnet: Übersicht der Anwendungsfälle.