De la commande reçue à l’expédition déclarée

Une commande de trois lignes arrive. Deux pièces sont en rayon, la troisième est introuvable au recomptage. Un système qui ne peut qu’accepter ou refuser toute la commande impose alors un mauvais choix : tout annuler ou promettre ce qui n’existe pas.

C’est pourquoi décision et expédition sont par ligne dans ce contrat. La quantité partielle n’est pas un cas particulier à contourner mais la voie prévue — et la récupération utilise une pagination par curseur que le contrat décrit comme stable.

Ce que ce cas suppose

• Un curseur stocké. Avec le dernier nextCursor reçu, vous poursuivez l’extraction par pages ; le rapprochement, lui, travaille avec ses propres points de contrôle.
• Une correspondance des lignes avec votre entrepôt. Décider par ligne suppose de savoir par ligne ce qui est disponible.
• Des motifs que vous pouvez assumer. Un refus porte un reasonCode.
• La volonté d’expédier des quantités partielles. Ne livrer qu’en totalité, c’est renoncer aux deux lignes présentes.

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écupérer les commandes. GET /commerce/v1/orders renvoie des pages avec nextCursor. Le contrat décrit cette pagination par curseur comme stable.
2. Lire la commande. GET /commerce/v1/orders/{salesOrderId} renvoie lines, totals, taxes et fees ainsi que shipTo et billTo séparément. La séparation compte pour la comptabilité : un frais n’est pas une remise, et un port n’est pas un prix article.
3. Décider. POST /commerce/v1/orders/{salesOrderId}/decision prend acceptation ou refus par ligne avec reasonCode et quantité. Au lieu d’une commande qui expire en silence, il y a ici une décision nommée ; acknowledgementStatus indique si elle est confirmée.
4. Déclarer l’expédition. POST /commerce/v1/shipments prend salesOrderId, les lignes avec quantités, carrierCode, trackingReference et shippedAt. Par ligne, car deux pièces peuvent partir aujourd’hui et une la semaine prochaine sans que la commande perde son état.

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'

Ce que l’on obtient

Il reste une commande avec une décision par ligne et des expéditions déclarées ; les écarts d’état de commande et d’expédition entre canal et système sont constatés par un rapprochement, pas encore activé dans le contrat. S’y ajoute un client qui reçoit une livraison partielle avec suivi au lieu d’une annulation. La ligne refusée porte un motif consultable.

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.