Réserver une pièce unique commandée jusqu’à exécution ou abandon

Un phare est publié sur deux canaux et commandé sur l’un. Des heures passent avant l’emballage. S’il est commandé entre-temps sur le second canal, un acheteur doit essuyer un refus — et cela coûte plus que cette vente.

La réservation lie une pièce en stock concrète à une ligne de commande. Elle se termine consommée quand la marchandise part, ou libérée si la vente n’aboutit pas ; state connaît aussi la valeur expired. Les deux portent sur des quantités et figurent au journal.

Ce que ce cas suppose

• Une commande avec des lignes. La réservation exige salesOrderId et orderLineId ; une réservation sans commande n’est pas prévue.
• Une pièce en stock plutôt qu’une référence. On réserve un exemplaire concret avec stockItemId.
• La révision actuelle. Toute modification porte expectedRevision.
• Un canal qui prend en charge les réservations. Les capacités l’indiquent par canal.

Le déroulement

Le tableau indique pour chaque étape l’appel compétent et ce qui existe ensuite. La justification de l’étape figure en dessous.

Pourquoi chaque étape est nécessaire

1. Réserver. POST /commerce/v1/inventory/reservations prend stockItemId, quantity, salesOrderId, orderLineId, expectedRevision et en option expiresAt. Dès lors, la pièce est liée à cette ligne ; selon le contrat, availableQuantity dans le stock est dérivé en tenant compte des réservations actives.
2. Vérifier l’état. GET /commerce/v1/inventory/reservations/{reservationId} indique initialQuantity, reservedQuantity, releasedQuantity, consumedQuantity et state. Avec plusieurs pièces, on voit ce qui reste lié.
3. Consommer. POST /commerce/v1/inventory/reservations/{reservationId}/consume prend quantity, reasonCode — à l’expédition fulfilled — et expectedRevision. On consomme quand la marchandise part, non quand la commande arrive.
4. Libérer. POST /commerce/v1/inventory/reservations/{reservationId}/release rend des quantités, par exemple avec order_cancelled, order_changed, expired ou manual_review. Une réservation jamais libérée bloque une pièce vendable sans acheteur.
5. Lire le journal. GET /commerce/v1/inventory/ledger consigne réservation, consommation et libération comme écritures avec reservationId, quantityDelta et balance. Chaque mouvement d’une pièce unique s’explique ainsi plus tard.

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'

Ce que l’on obtient

Au final, reservedQuantity, releasedQuantity et consumedQuantity montrent quelle quantité reste liée, libérée ou consommée, et state indique l’état de la réservation. Qu’un second acheteur ait encore pu commander la pièce entre-temps dépend de la mise à jour à temps de l’offre sur le second canal.

Où cela figure dans la documentation

Les listes de champs contractuelles, les codes d’erreur et les réponses d’exemple se trouvent dans le contrat OpenAPI de cette surface, à l’adresse docs.tapinomahub.com (tapinoma-commerce). Tous les cas d’usage classés par surface et par rôle : aperçu des cas d’usage.