Katalog und Bestand führen, Einzelstücke reservieren

Ein Gebrauchtteilehändler stellt denselben Scheinwerfer auf drei Kanälen ein. Er hat aber nur einen. Verkauft sich das Teil auf Kanal eins, müssen zwei Angebote sofort verschwinden — und zwar nicht in der nächtlichen Synchronisation, sondern jetzt. Wer das über eine Artikelnummer und eine Stückzahl abbildet, verkauft irgendwann zweimal.

Der Vertrag trennt deshalb vier Dinge, die im Alltag gern zusammenfallen: den Katalogartikel als Beschreibung, das Lagerstück als konkretes Exemplar, die Reservierung als zeitweilige Bindung und das Angebot als kanalbezogene Veröffentlichung mit Preis.

Was dieser Fall voraussetzt

• Eine eigene Artikelnummer. Der Katalogartikel trägt Ihre merchantSku; sie ist der Anker, an dem Ihr System und der Vertrag sich treffen.
• Eine Unterscheidung von Beschreibung und Exemplar. Ein Katalogartikel beschreibt, ein Lagerstück existiert. Wer nur Artikel führt, kann Einzelstücke nicht reservieren.
• Eine Verbindung je Kanal. Das Angebot verweist auf Verbindungen; ohne sie ist eine Veröffentlichung gegenstandslos.
• Eine Revision bei jedem Schreiben. Die Felder für erwartete Revisionen verhindern, dass zwei gleichzeitige Änderungen sich überschreiben.

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 Artikel schreiben. PUT /commerce/v1/catalog/items/{catalogItemId} legt die kanonische Fassung ab: merchantSku, condition, identifiers, compatibility, media und attributes. Kanonisch heißt: Diese Fassung ist von jedem Kanal unabhängig, und ein Kanalwechsel erzwingt keine Umbenennung.
2. Die Bestände buchen. POST /commerce/v1/inventory/batches nimmt physicalQuantity und safetyStockQuantity gebündelt. Die Antwort nennt die Anzahl accepted und rejected und kann Fehler in errors aufführen.
3. Das Einzelstück reservieren. POST /commerce/v1/inventory/reservations bindet eine Menge eines konkreten Lagerstücks (stockItemId, quantity) an eine Auftragsposition; salesOrderId und orderLineId sind Pflichtfelder. Aktive Reservierungen fließen in die verfügbare Menge (availableQuantity) ein; die atomare Reservierung ist im Vertrag noch nicht aktiviert. Freigeben und Verbrauchen sind eigene Aufrufe.
4. Das Angebot setzen. PUT /commerce/v1/offers/{offerId} verbindet stockItemId, connectionId, price und publicationState. Das Angebot ist kanalbezogen, der Artikel nicht: Derselbe Artikel kann auf zwei Kanälen zu verschiedenen Preisen stehen, ohne zweimal beschrieben zu werden.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: bestand-2026-09-12-a' \
  -d '{"entries":[{"stockItemId":"<stockItemId>","physicalQuantity":1,"safetyStockQuantity":0,"expectedRevision":"<revision>"}]}' \
  'https://commerce-preview.invalid/commerce/v1/inventory/batches'

Was am Ende vorliegt

Am Ende steht ein Bestand, dessen verfügbare Menge sich aus physischer Menge, Sicherheitsmenge und aktiven Reservierungen ergibt, und ein Einzelstück, dessen Reservierung an eine Auftragsposition gebunden ist und in die verfügbare Menge einfließt. Beschreibung, Exemplar und Preis sind getrennt pflegbar — eine Preisänderung berührt die Artikelbeschreibung nicht.

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.