ormuz
Guides métier/Retour client

Gérer un retour client

Ouvrez un dossier de retour depuis une commande, faites vivre séparément les faits logistiques et la décision commerciale, puis créez explicitement les avoirs et remboursements nécessaires avant de clôturer le dossier.

Objectif métier

Le return est le dossier durable du retour. Il conserve ce qui a été demandé, autorisé, expédié, reçu et inspecté. Le processus décide comment obtenir ces faits et quelle résolution commerciale appliquer.

Retour ≠ avoir ≠ remboursement Le dossier de retour explique pourquoi une correction commerciale est nécessaire. Un avoir corrige la facturation ; un remboursement inverse un mouvement financier. Ces effets restent des objets et des étapes séparés.

Prérequis

ÉlémentRôle
Commande sourceLe retour appartient à une commande existante ; ses lignes bornent les articles et quantités retournables.
Launcher returnAssocie le dossier à une définition de processus qui accepte une entrée platform.return nommée return.
Politique de retourDétermine ce qui est autorisable, les contrôles à l’inspection et la résolution commerciale attendue.
Contexte financierLes factures et paiements réels de la commande sont nécessaires si le parcours doit produire un avoir ou un remboursement.

Une return_url est utile uniquement si le processus expose des actions utilisateur dans un parcours utilisateur. Un parcours entièrement opéré par vos systèmes ou vos équipes peut rester côté serveur.

Ouvrir le retour

Vous pouvez ouvrir le dossier depuis votre backend avec POST /v1/returns, ou depuis un processus parent avec le Core node create_return. Dans les deux cas, Ormuz crée le return puis démarre son processus propriétaire. Le marchand est déduit de la commande : il n’est pas un paramètre de création du retour.

HTTP
POST /v1/returns
{5 items
"order_id":"ord_0123456789abcdef0123456789abcdef"
"reference":"RET-2026-0042"
"source_reference":"RMA-8472"
"return_url":"https://shop.example/orders/42/return"
"items":[1 item
0:{...}3 items
]
}
{
  "order_id": "ord_0123456789abcdef0123456789abcdef",
  "reference": "RET-2026-0042",
  "source_reference": "RMA-8472",
  "return_url": "https://shop.example/orders/42/return",
  "items": [
    {
      "line_item_id": "li_0123456789abcdef0123456789abcdef",
      "quantity_requested": 2,
      "reason": "defective"
    }
  ]
}

Tant qu’aucune autorisation, expédition, réception ou création d’avoir n’a figé le dossier, la demande peut encore être corrigée sans remplacer les lignes existantes. Une fois le parcours engagé, traitez les changements comme de nouveaux faits plutôt que comme une réécriture du passé.

Parcours de retour

DépartRetour ouvert
Autoriser
Expédier
Recevoir
Inspecter
Résoudre

Parcours usuel : les jalons logistiques sont des faits distincts ; la résolution commerciale intervient explicitement après les constats nécessaires.

Autoriser les quantités

authorize_return fixe les quantités réellement éligibles. Une autorisation n’est ni une expédition ni une acceptation finale.

Observer le mouvement physique

record_return_shipment enregistre l’expédition ; receive_return enregistre les quantités réellement reçues. Ne synthétisez pas ces faits si votre logistique ne les a pas observés.

Inspecter

inspect_return qualifie les articles reçus et fixe les quantités acceptées. Une quantité acceptée ne peut pas dépasser la quantité reçue.

Résoudre

La résolution finale traduit le résultat commercial : accepté, partiellement accepté, rejeté ou retiré. Elle doit être cohérente avec la base quantitative choisie.

Interactions humaines : collecter puis appliquer

Lorsque l’autorisation, la réception ou l’inspection est saisie par un opérateur, utilisez les actions utilisateur dédiées : collect_return_authorization, collect_return_receipt et collect_return_inspection. Elles produisent une réponse structurée mais ne modifient pas à elles seules le dossier.

Enchaînez toujours la collecte avec le node métier correspondant — authorize_return, receive_return ou inspect_return — afin que le fait canonique soit validé et persisté. Cette séparation évite de confondre une saisie utilisateur avec une transition métier réussie.

Avoirs et remboursements

Si la résolution doit corriger la facturation, create_return_credit_note_drafts crée des avoirs persistés au statut draft à partir d’une base quantitative explicite : demandée, autorisée, reçue ou acceptée. Une fois une base utilisée pour les avoirs du retour, conservez cette même convention pour les corrections suivantes.

L’avoir ne rembourse pas les fonds. Si la vente a déjà été réglée, créez ensuite les intentions de remboursement depuis les avoirs et les paiements réellement alloués : create_credit_note_psp_refunds pour les paiements PSP ou create_credit_note_payment_refunds pour les encaissements non PSP. L’exécution externe du remboursement reste une étape distincte.

Ne clôturez pas sur une intention Un avoir au statut draft ou une intention de remboursement ne prouve pas qu’un document a été émis ni que les fonds ont été restitués. Si ces objets expliquent la résolution, créez-les et reliez-les explicitement avant de finaliser le retour.

Résoudre ou annuler

finalize_return clôture un dossier open avec une résolution explicite et peut rattacher les objets déjà créés qui expliquent cette issue. Pour une résolution fondée sur les quantités acceptées, l’inspection fournit généralement la base la plus fidèle au fait physique.

cancel_return est réservé à l’abandon administratif d’un dossier encore ouvert avant expédition ou réception. Si le client retire sa demande sans mouvement physique, une résolution withdrawn peut aussi être utilisée tant que le retour n’a pas été expédié ou reçu. N’utilisez pas l’annulation pour effacer un retour déjà traité ou des effets financiers déjà produits.

Événements et suivi

ÉvénementUsage
return.createdLe dossier est créé et son processus propriétaire démarre.
return.authorizedLes quantités autorisées ont été enregistrées.
return.shippedL’expédition retour est observée pour la première fois.
return.receivedLes quantités physiquement reçues ont été enregistrées.
return.inspectedL’inspection et les quantités acceptées ont été enregistrées.
return.resolvedLe dossier est clôturé avec une résolution commerciale explicite.
return.cancelledLe dossier est annulé avant sa résolution normale.

Utilisez ces événements pour synchroniser les systèmes autour du dossier, mais relisez le return lorsque votre décision dépend des quantités ou des objets liés courants. Les événements décrivent les jalons ; la ressource reste la référence du dossier complet.

Checklist de mise en œuvre

  • Configurer un launcher return dont le processus accepte platform.return.
  • Ouvrir le retour depuis une commande existante et réserver uniquement des quantités réellement retournables.
  • Séparer autorisation, expédition, réception, inspection et résolution.
  • Utiliser les actions utilisateur uniquement pour collecter les faits qui nécessitent une saisie humaine.
  • Choisir une base quantitative explicite pour les avoirs et la conserver.
  • Créer les avoirs et remboursements comme effets séparés du dossier de retour.
  • Ne considérer un remboursement comme réalisé qu’après confirmation de son propre lifecycle financier.
  • Finaliser le retour avec une résolution cohérente et les objets liés utiles à l’audit.