Vom eingegangenen Auftrag zur gemeldeten Sendung

Ein Auftrag über drei Positionen kommt herein. Zwei Teile liegen im Regal, das dritte ist beim Nachzählen nicht auffindbar. Ein System, das nur den ganzen Auftrag annehmen oder ablehnen kann, zwingt jetzt zu einer schlechten Entscheidung: alles stornieren oder etwas versprechen, was nicht da ist.

Deshalb sind Entscheidung und Sendung in diesem Vertrag positionsbezogen. Die Teilmenge ist nicht der Sonderfall, für den es einen Umweg gibt, sondern der vorgesehene Weg — und abgeholt wird mit einer Cursor-Paginierung, die der Vertrag als stabil beschreibt.

Was dieser Fall voraussetzt

• Ein gespeicherter Cursor. Mit dem zuletzt erhaltenen nextCursor setzen Sie den seitenweisen Abruf fort; der Abgleich arbeitet dagegen mit eigenen Prüfpunkten.
• Eine Zuordnung der Positionen zu Ihrem Lager. Die Entscheidung je Position setzt voraus, dass Sie je Position wissen, was verfügbar ist.
• Begründungen, die Sie vertreten können. Eine Ablehnung trägt einen reasonCode.
• Die Bereitschaft, Teilmengen zu versenden. Wer nur vollständig liefert, verschenkt die zwei Positionen, die da sind.

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 Aufträge abholen. GET /commerce/v1/orders liefert seitenweise mit nextCursor. Der Vertrag beschreibt diese Cursor-Paginierung als stabil.
2. Den Auftrag lesen. GET /commerce/v1/orders/{salesOrderId} gibt lines, totals, taxes und fees sowie shipTo und billTo getrennt zurück. Die Trennung ist wichtig für die Buchhaltung: Eine Gebühr ist kein Rabatt, und eine Versandkostenposition ist kein Artikelpreis.
3. Entscheiden. POST /commerce/v1/orders/{salesOrderId}/decision nimmt je Position Annahme oder Ablehnung mit reasonCode und Menge. Statt eines Auftrags, der stillschweigend verfällt, steht hier eine benannte Entscheidung; ob sie bestätigt ist, zeigt acknowledgementStatus.
4. Die Sendung melden. POST /commerce/v1/shipments nimmt salesOrderId, die Positionen mit Mengen, carrierCode, trackingReference und shippedAt. Positionsgenau, weil zwei Teile heute und eines nächste Woche rausgehen darf, ohne dass der Auftrag den Zustand verliert.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: sendung-4711-position-1' \
  -d '{"salesOrderId":"<salesOrderId>","lines":[{"lineId":"<lineId>","quantity":1}],"carrierCode":"DHL","trackingReference":"00340434","shippedAt":"2026-09-12T09:30:00Z"}' \
  'https://commerce-preview.invalid/commerce/v1/shipments'

Was am Ende vorliegt

Am Ende steht ein Auftrag mit einer Entscheidung je Position und gemeldeten Sendungen; Abweichungen im Auftrags- und Sendungszustand zwischen Kanal und Ihrem System stellt ein Abgleich fest, der im Vertrag noch nicht aktiviert ist. Dazu kommt ein Kunde, der eine Teillieferung mit Sendungsverfolgung bekommt statt einer Stornierung. Die abgelehnte Position trägt einen Grund, den man nachlesen kann.

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.