Annulation, retour et remboursement en un seul processus

Un client se rétracte, une pièce revient endommagée, une autre ne convient pas. Trois cas différents qui, en pratique, disparaissent souvent dans le même avoir. En fin de mois, ni le stock ni la comptabilité ne concordent, et personne ne sait quel remboursement correspondait à quel retour.

Le contrat sépare donc les trois cas et les relie par des identifiants : le remboursement renvoie toujours à la commande et, si returnId est renseigné, au retour. Chaque remboursement enregistré est ainsi imputable à une commande, et au retour lorsqu’il est renseigné — en amont comme en aval.

Ce que ce cas suppose

• Une commande avec des lignes. Annulation et reprise se font par ligne et quantité, non en bloc ; le remboursement est un montant rattaché à la commande.
• Une date d’arrivée. Un retour annoncé diffère d’un retour arrivé ; receivedAt consigne l’arrivée. Le contrat ne lie pas le remboursement à ce champ.
• Des motifs par dossier. Rétractation, dommage de transport et erreur de commande sont trois motifs aux trois conséquences différentes pour le stock.
• Une comptabilité qui traite les avoirs. Les avoirs sont distincts de la facture et renvoient à la facture et à la commande ; ils ne contiennent aucun renvoi au remboursement ni au retour.

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. Annuler avant expédition. POST /commerce/v1/cancellations prend salesOrderId, reasonCode et les lignes avec quantités. Tant que rien n’est parti, c’est la voie la moins coûteuse — aucun retour que personne ne veut payer.
2. Enregistrer le retour. POST /commerce/v1/returns porte receivedAt. Ce champ sépare l’annonce du fait. Le contrat ne lie pas le remboursement à ce champ.
3. Rembourser. POST /commerce/v1/refunds prend salesOrderId, amount avec amountMinor et currency, ainsi que reasonCode ; returnId est facultatif. Quand le remboursement se rapporte à un retour, ce lien devrait être posé via returnId, car le contrat ne l’impose pas : un remboursement sans dossier ne s’explique à personne ensuite.
4. Tirer l’avoir. GET /commerce/v1/credit-notes liste les avoirs, distincts de la facture ; chacun renvoie à la facture via invoiceId et à la commande via salesOrderId. Le contrat ne prévoit pas de renvoi au remboursement lui-même dans l’avoir ; il ne partage avec lui que le salesOrderId.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: erstattung-4711-ruecksendung-1' \
  -d '{"salesOrderId":"<salesOrderId>","returnId":"<returnId>","amount":{"amountMinor":8900,"currency":"EUR"},"reasonCode":"return"}' \
  'https://commerce-preview.invalid/commerce/v1/refunds'

Ce que l’on obtient

Au final, chaque remboursement enregistré est rattaché à une commande via salesOrderId, et chaque avoir renvoie à la facture et à la commande via invoiceId et salesOrderId. Un remboursement créé avec returnId se retrace jusqu’à son retour.

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.