Contrôler une pièce retournée et décider de son usage

Un calculateur revient : l’acheteur écrit qu’il ne convient pas. Au déballage, un connecteur endommagé apparaît. Que la pièce retourne en vente, doive être réparée ou soit recyclée ne dépend pas du motif de l’acheteur, mais du contrôle à la réception.

Le contrat sépare donc trois affirmations que la pratique range volontiers dans un seul champ : pourquoi l’acheteur renvoie, ce que révèle le contrôle et ce qu’il advient de la pièce. Accepté ne veut pas dire revendable — l’usage se décide par un appel distinct.

Ce que ce cas suppose

• Une commande avec des lignes. Le retour renvoie à salesOrderId et aux lignes retournées.
• Un contrôle par quelqu’un qui connaît la pièce. La décision d’usage est technique, non administrative.
• Des motifs fixes pour constat et usage. reasonCode est ici votre propre code en minuscules ; un catalogue interne le garde cohérent.
• Une révision attendue. Contrôle et usage exigent expectedRevision ; selon le contrat, le retour lui-même ne porte pas de révision.

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. Enregistrer le retour. POST /commerce/v1/returns prend salesOrderId, les lignes, reasonCode avec not_as_described, damaged, incompatible, buyer_withdrawal ou other, et en option receivedAt. C’est le motif de l’acheteur — pas encore un constat.
2. Contrôler la marchandise. POST /commerce/v1/returns/{returnId}/review prend decision avec accept, reject, partial ou attention_required et par ligne reviewedQuantity, finding et reasonCode. La réponse indique decisionActorReference : le contrôle est imputé à un acteur.
3. Décider de l’usage. POST /commerce/v1/returns/{returnId}/disposition tranche par ligne entre restock, repair, recycle, dispose et hold. hold est une valeur propre de disposition ; le contrat ne décrit aucun effet sur les offres.
4. Lire le journal de stock. GET /commerce/v1/inventory/ledger renvoie par écriture entryType, quantityDelta et balance. entryType connaît physical_set, safety_stock_set, reserved, released, consumed et expired ; le contrat ne décrit aucun lien avec la décision d’usage.
5. Mettre à jour la pièce en stock. PUT /commerce/v1/stock-items/{stockItemId} redéfinit condition avec new, used ou refurbished et locationKey. Si l’état ou l’emplacement change après le contrôle ou la réparation, la modification relève de la pièce en stock, non d’une note.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: verwendung-ruecksendung-4711' \
  -d '{"lines":[{"lineId":"<lineId>","quantity":1,"disposition":"repair","reasonCode":"<reasonCode>"}],"expectedRevision":"<revision>"}' \
  'https://commerce-preview.invalid/commerce/v1/returns/<returnId>/disposition'

Ce que l’on obtient

Au final, chaque pièce revenue a un devenir décidé, un contrôle imputé et un stock à jour. Pour le calculateur au connecteur endommagé, repair est retenu.

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.