Einen Verkaufskanal anbinden, ohne zwei schreibende Systeme zu haben

Ein Händler verkauft über einen Marktplatz und pflegt daneben eine Warenwirtschaft. Beide Systeme halten sich für führend. Das Ergebnis kennt jeder, der es erlebt hat: Bestände, die hin- und herspringen, Preise, die eine Nacht später wieder alt sind, und ein Einzelstück, das zweimal verkauft wird.

Der Commerce-Vertrag setzt deshalb bewusst eine Stufe vor die Übertragung: Bevor überhaupt geschrieben wird, legt ein Synchronisationsplan fest, wer schreibt; je Verkaufskonto, Marktgebiet, optionalem Angebot und Fachfluss ist höchstens eine aktive Schreibzuweisung zulässig. Erst danach läuft eine Vorschau, und erst eine ausdrückliche Freigabe macht daraus eine Änderung.

Was dieser Fall voraussetzt

• Ein autorisiertes Verkaufskonto. Die Verbindung wird mit einem Berechtigungsnachweis angelegt; Zugangsdaten des Kanals werden nicht offengelegt und nicht durchgereicht.
• Eine Entscheidung, welches System führt. Diese Frage ist kaufmännisch, nicht technisch. Der Vertrag erzwingt nur, dass sie beantwortet wird.
• Bereitschaft, den Trockenlauf zu lesen. Eine Vorschau, die niemand ansieht, ist ein Verzicht auf die einzige Gelegenheit, folgenlos zu scheitern.
• Eine Idempotenzkennung je schreibendem Aufruf. Ein wiederholter Aufruf darf keine zweite Wirkung haben.

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. Den Funktionsumfang lesen. GET /commerce/v1/capabilities nennt je Kanal supportLevel, flows und ob Reservierungen getragen werden. Diese Stufe klärt vor jeder Arbeit, was der Kanal überhaupt kann — eine Anbindung gegen eine nicht unterstützte Funktion scheitert sonst spät und teuer.
2. Die Verbindung anlegen. POST /commerce/v1/connections nimmt channelId, channelAccountReference, marketAreaReference, authorizationProof und ownershipMode. Die kanalgebundenen Details bleiben hinter einer privaten Übersetzungsgrenze; öffentliche Kennungen sind undurchsichtig.
3. Die Zuständigkeit festlegen. POST /commerce/v1/sync-plans ist die entscheidende Stufe: writerAssignments lässt je Verkaufskonto, Marktgebiet, optionalem Angebot und flow höchstens eine aktive Schreibzuweisung zu, conflictPolicy regelt den Streitfall, und dryRunRequired kann den Trockenlauf verbindlich machen.
4. Trocken laufen lassen. POST /commerce/v1/sync-runs mit dem Vorschaumodus liefert counts mit read, changed, rejected und conflicted. Vier Zahlen, die vor dem ersten echten Schreiben sagen, was passieren würde.
5. Freigeben. POST /commerce/v1/sync-runs/{syncRunId}/approval nimmt decision, previewRevision und expectedRevision; alle drei sind Pflichtfelder. Freigegeben wird also genau die geprüfte Vorschau — nicht ein inzwischen veränderter Stand.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: lauf-2026-09-12-01' \
  -d '{"syncPlanId":"<syncPlanId>","mode":"preview"}' \
  'https://commerce-preview.invalid/commerce/v1/sync-runs'

Was am Ende vorliegt

Am Ende steht eine Verbindung, bei der der Plan festhält, wer schreibt, und eine erste Übertragung, die vor der Freigabe als Vorschau gelesen wurde. Dass der Bestand dadurch nicht mehr hin und her springt, sichert der Vertrag nicht zu: Handarbeit daneben im Kanal kann er nicht verhindern.

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.