Tenir catalogue et stock, réserver les pièces uniques

Un négociant de pièces d’occasion publie le même phare sur trois canaux. Mais il n’en a qu’un. Si la pièce se vend sur le canal un, deux offres doivent disparaître aussitôt — pas à la synchronisation nocturne, mais maintenant. Modéliser cela avec une référence et une quantité conduit tôt ou tard à une double vente.

Le contrat sépare donc quatre choses que la pratique confond volontiers : l’article de catalogue comme description, la pièce en stock comme exemplaire concret, la réservation comme lien temporaire et l’offre comme publication liée au canal avec un prix.

Ce que ce cas suppose

• Votre propre référence article. L’article de catalogue porte votre merchantSku ; c’est l’ancrage où votre système et le contrat se rencontrent.
• Une distinction entre description et exemplaire. Un article de catalogue décrit, une pièce en stock existe. Si vous ne tenez que des articles, vous ne pouvez réserver de pièces uniques.
• Une connexion par canal. L’offre renvoie à des connexions ; sans elles, une publication est sans objet.
• Une révision à chaque écriture. Les champs de révision attendue empêchent deux modifications simultanées de s’écraser.

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. Écrire l’article. PUT /commerce/v1/catalog/items/{catalogItemId} enregistre la version canonique : merchantSku, condition, identifiers, compatibility, media et attributes. Canonique signifie indépendante de tout canal ; un changement de canal n’impose aucun renommage.
2. Comptabiliser le stock. POST /commerce/v1/inventory/batches prend physicalQuantity et safetyStockQuantity en un lot. La réponse indique les nombres accepted et rejected et peut lister les erreurs dans errors.
3. Réserver la pièce unique. POST /commerce/v1/inventory/reservations lie une quantité d’une pièce en stock concrète (stockItemId, quantity) à une ligne de commande ; salesOrderId et orderLineId sont obligatoires. Les réservations actives entrent dans la quantité disponible (availableQuantity) ; la réservation atomique n’est pas encore activée dans le contrat. Libérer et consommer sont des appels distincts.
4. Publier l’offre. PUT /commerce/v1/offers/{offerId} relie stockItemId, connectionId, price et publicationState. L’offre est liée au canal, l’article non : le même article peut être à des prix différents sur deux canaux sans être décrit deux fois.

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'

Ce que l’on obtient

Il reste un stock dont la quantité disponible découle de la quantité physique, du stock de sécurité et des réservations actives, et une pièce unique dont la réservation est liée à une ligne de commande et entre dans la quantité disponible. Description, exemplaire et prix se gèrent séparément — un changement de prix ne touche pas la description.

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.