Ein bestelltes Einzelstück halten, bis die Bestellung erfüllt oder erledigt ist

Ein Scheinwerfer ist auf zwei Kanälen eingestellt und wird auf einem bestellt. Bis er verpackt ist, vergehen Stunden. Wird er in dieser Zeit auf dem zweiten Kanal ein weiteres Mal bestellt, muss einer der Käufer eine Absage bekommen — und das kostet mehr als nur diesen Verkauf.

Die Reservierung bindet ein konkretes Lagerstück an eine Auftragsposition. Sie endet verbraucht, wenn die Ware das Haus verlässt, oder freigegeben, wenn der Kauf nicht zustande kommt; state kennt daneben den Wert expired. Beides nimmt Mengen und steht als Buchung im Journal.

Was dieser Fall voraussetzt

• Ein Auftrag mit Positionen. Die Reservierung verlangt salesOrderId und orderLineId; eine Reservierung ohne Auftrag ist nicht vorgesehen.
• Ein Lagerstück statt einer Artikelnummer. Reserviert wird ein konkretes Exemplar mit stockItemId.
• Die aktuelle Revision. Jede Änderung an der Reservierung trägt expectedRevision.
• Einen Kanal, der Reservierungen trägt. Der Funktionsumfang nennt es je Kanal.

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. Reservieren. POST /commerce/v1/inventory/reservations nimmt stockItemId, quantity, salesOrderId, orderLineId, expectedRevision und optional expiresAt. Ab jetzt ist das Stück an diese Position gebunden; availableQuantity im Bestand wird laut Vertrag unter Berücksichtigung aktiver Reservierungen abgeleitet.
2. Den Stand prüfen. GET /commerce/v1/inventory/reservations/{reservationId} nennt initialQuantity, reservedQuantity, releasedQuantity, consumedQuantity und state. Bei mehreren Stück zeigt sich hier, wie viel noch gebunden ist.
3. Verbrauchen. POST /commerce/v1/inventory/reservations/{reservationId}/consume nimmt quantity, reasonCode — beim Versand fulfilled — und expectedRevision. Verbraucht wird, wenn die Ware das Haus verlässt, nicht wenn der Auftrag eingeht.
4. Freigeben. POST /commerce/v1/inventory/reservations/{reservationId}/release gibt Mengen zurück, etwa mit order_cancelled, order_changed, expired oder manual_review. Eine Reservierung, die nie freigegeben wird, blockiert ein verkäufliches Teil ohne Käufer.
5. Das Journal lesen. GET /commerce/v1/inventory/ledger führt Reservierung, Verbrauch und Freigabe als Buchungen mit reservationId, quantityDelta und balance. So lässt sich später jede Bewegung eines Einzelstücks erklären.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: reservierung-4711-versand' \
  -d '{"quantity":1,"reasonCode":"fulfilled","expectedRevision":"<revision>"}' \
  'https://commerce-preview.invalid/commerce/v1/inventory/reservations/<reservationId>/consume'

Was am Ende vorliegt

Am Ende zeigen reservedQuantity, releasedQuantity und consumedQuantity, welche Menge noch gebunden, freigegeben oder verbraucht ist, und state nennt den Stand der Reservierung. Ob ein zweiter Käufer das Teil in der Zwischenzeit noch bestellen konnte, hängt davon ab, wie rechtzeitig das Angebot auf dem zweiten Kanal aktualisiert wurde.

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.