Traiter un litige commercial

Objectif métier

Le dispute conserve le périmètre contesté et la conclusion commerciale. Le processus qui lui est associé orchestre la collecte de preuves, les analyses, les revues humaines et les effets correctifs. Le statut du processus ne remplace jamais la résolution du dossier.

Prérequis

Ouvrir le litige

Le point d’entrée public est POST /v1/disputes. La création persiste le dossier en status=open, resolution_status=pending puis démarre son processus propriétaire. Si plusieurs processus sont possibles, fournissez explicitement process_definition_id ; sinon le launcher dispute du marchand est utilisé.

POST /v1/disputes

{
  "merchant_id": "mer_0123456789abcdef0123456789abcdef",
  "buyer_id": "cmp_0123456789abcdef0123456789abcdef",
  "reference": "DSP-2026-0042",
  "source_reference": "CASE-18472",
  "subjects": [
    {
      "type": "invoice",
      "invoice_id": "inv_0123456789abcdef0123456789abcdef",
      "amount": 12000,
      "reason": "incorrect_amount"
    }
  ],
  "amount_disputed": 12000
}

Pour une ligne, conservez le contexte de l’invoice ou de l’order qui permet d’expliquer où elle se situe. N’élargissez pas le dossier à des documents qui ne sont pas réellement contestés : le périmètre du litige alimente aussi les projections de facture et de créance.

Parcours de résolution

Tant que le dossier est open, le processus peut ajuster son périmètre avec update_dispute. Une fois résolu ou annulé, le dossier est fermé et son histoire ne doit plus être réécrite.

Qualifier, analyser et décider

Commencez par qualifier précisément les subjects, le motif et le montant contesté. update_dispute permet d’ajuster ces éléments lorsqu’une nouvelle preuve modifie le périmètre du dossier. Le montant contesté est exprimé en unité mineure de devise ; tous les subjects monétaires d’un dossier restent dans une devise cohérente.

Une Decision peut formaliser une politique déterministe. Un Agent peut analyser des pièces, classifier le motif ou produire une recommandation si son activité et ses tools sont conçus pour cela. Une recommandation d’Agent ne devient jamais automatiquement la conclusion du litige : la décision finale doit rester matérialisée par le processus et les contrôles que votre politique exige.

Lorsque l’enjeu impose une revue humaine, utilisez une action utilisateur ou une demande d’approbation appropriée, puis transformez sa réponse en décision explicite. Le dossier ne doit pas être finalisé simplement parce qu’une notification a été envoyée ou qu’un opérateur a ouvert l’écran.

Matérialiser les effets de la résolution

Une résolution accepted ou partially_accepted peut nécessiter un ou plusieurs effets séparés : avoir contre une facture, remboursement d’un paiement, création d’un retour, remplacement de commande ou pièce justificative. finalize_dispute ne crée aucun de ces objets.

Créez les objets correctifs avec leurs nodes ou APIs canoniques, puis ajoutez-les à related_objects avec update_dispute avant la clôture lorsque leur lien est utile à l’explication du dossier. Par exemple, un avoir peut porter la correction comptable tandis qu’une intention de remboursement traite séparément la restitution des fonds.

Finaliser ou annuler le dossier

finalize_dispute clôture le dossier avec accepted, partially_accepted, rejected ou withdrawn. Siamount_accepted est fourni, il ne peut pas dépasser amount_disputed. Utilisez resolution_detail pour conserver une explication lisible de la décision lorsque cela aide l’exploitation ou l’audit métier.

cancel_dispute correspond à un abandon administratif sans résolution commerciale normale — dossier ouvert par erreur, doublon identifié par vos opérations ou cas devenu sans objet. Ne l’utilisez pas pour masquer un rejet ou une acceptation déjà décidés.

Tant qu’un litige open couvre une facture, celle-ci expose son état contesté et la projection de receivable distingue les montants contestés des montants non contestés. Lorsque plus aucun litige ouvert ne couvre la facture, cette projection est levée.

Événements et suivi

Utilisez dispute.created, dispute.resolved et dispute.cancelled pour synchroniser le lifecycle du dossier. Les événements de facture décrivent la projection « contestée » de la facture et peuvent être utiles pour suspendre ou reprendre des parcours de recouvrement.

Checklist de mise en œuvre

• Configurer un launcher dispute avec une entrée platform.dispute.
• Ouvrir le dossier uniquement sur les documents ou lignes réellement contestés.
• Conserver une devise cohérente et un montant contesté explicite lorsque le dossier est monétaire.
• Mettre à jour le périmètre tant que le dossier est ouvert plutôt que créer des dossiers artificiellement fragmentés.
• Distinguer analyse, recommandation, revue humaine et décision finale.
• Créer explicitement les avoirs, remboursements, retours ou autres effets correctifs nécessaires.
• Rattacher les effets importants à related_objects avant la finalisation si l’audit métier doit les relier au dossier.
• Finaliser avec une résolution et un montant accepté cohérents, ou annuler uniquement les dossiers réellement abandonnés.