# Litiges sur les ventes de vos vendeurs

> Laissez un vendeur Lite répondre à un litige sur sa propre vente, avec sa preuve de livraison, et complétez sa réponse par l'API.

Un litige sur une vente faite avec `X-Sync` est un litige du compte du vendeur. C'est souvent lui qui
détient la preuve : le bon de livraison, les messages échangés avec l'acheteur. Avec Sync, un vendeur
Lite peut répondre depuis son portail ou depuis le [composant embarqué](https://docs.wajub.com/fr/sync/embedded-components)
`disputes`, et vous en êtes prévenu.

## Qui répond

Chaque connexion porte `dispute_handling` :

| Valeur     | Qui répond                                                                                                                                                            | Par défaut                                                                    |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `both`     | Le vendeur envoie ses preuves ; vous en êtes prévenu et pouvez les compléter par l'API. Le vendeur peut encore modifier sa réponse jusqu'à 24 heures avant l'échéance | `lite`                                                                        |
| `seller`   | Le vendeur répond ; sa réponse est **définitive** une fois envoyée                                                                                                    |                                                                               |
| `platform` | Vous seul, par l'API. Le vendeur voit le litige, en lecture                                                                                                           | `relay`, et sa seule valeur : un vendeur Relay n'a pas d'espace d'où répondre |

**Vous pouvez toujours répondre par l'API avec `X-Sync`**, quelle que soit la valeur. Un marchand
`direct` répond depuis son propre Dashboard : le réglage est refusé pour lui. Un [paiement
partagé](https://docs.wajub.com/fr/sync/split-payments#one-payment-several-sellers) est le vôtre : ses litiges aussi.

Réglez-le avec `POST /accounts`, ou changez-le tout de suite avec `PUT /accounts/{id}` ; une réponse
déjà envoyée par le vendeur reste dans le litige.

```bash title="Le vendeur répond seul"
curl -X PUT https://api.wajub.com/accounts/acc_Gt6yU3nE8rM1kS5vX9bQ \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -d '{"dispute_handling":"seller"}'
```

| `error_code`                     | Statut | Quand                                                                            |
| -------------------------------- | ------ | -------------------------------------------------------------------------------- |
| `dispute_handling_not_available` | `400`  | `seller` ou `both` sur un compte `relay`, ou toute valeur sur un compte `direct` |
|                                  | `422`  | Une valeur inconnue (`errors.dispute_handling`)                                  |

## Ce que fait le vendeur

1. **Il prépare un brouillon**

   Une pièce par type de preuve : `proof_of_delivery`, `customer_communication`, `receipt`,
   `product_description`, `refund_policy` ou `other`. Un texte de 2 000 caractères au plus, un
   fichier, ou les deux. Rien n'atteint le litige tant qu'il ne l'a pas envoyé.

2. **Il joint des fichiers**

   PDF, JPG ou PNG seulement, 5 Mo au plus. Le contenu est contrôlé : un script déguisé en PDF ou en
   image est refusé.

3. **Il l'envoie**

   Chaque pièce pas encore envoyée entre dans le litige, le litige passe `under_review`, et vous
   recevez `account.dispute_evidence_submitted`.

**24 heures avant l'échéance**, le vendeur ne peut plus écrire. Ce qu'il a enregistré sans l'envoyer
est **envoyé pour lui**, et une réponse `both` devient définitive ; s'il n'a rien écrit, sa réponse
passe `lapsed`. Un litige sans échéance n'a ni coupure ni rappel : le vendeur peut répondre tant qu'il est
ouvert. Quand un litige se termine alors que la réponse du vendeur est encore ouverte, elle passe
`closed`. Avec `platform`, le vendeur lit que « votre plateforme répond à ce litige ».

Vous n'êtes pas coupé à ce moment-là : l'API vous reste ouverte jusqu'à la décision du litige.
Complétez tout de même la réponse **avant** la coupure du vendeur, pour qu'il la voie entière.

Le vendeur est prévenu par e-mail, à [votre marque](https://docs.wajub.com/fr/sync/own-domain#e-mails-in-your-brand), quand le
litige s'ouvre, et 3 jours avant l'échéance s'il n'a rien envoyé, quand la connexion le laisse
répondre. Un litige sans échéance n'a que l'e-mail d'ouverture.

## Compléter sa réponse

Lisez le dossier avec `GET /disputes/{id}` et `X-Sync`, puis complétez-le avec
`POST /disputes/{id}/submit-evidence`. Une pièce que vous envoyez sous un type que le vendeur a déjà
envoyé **remplace** la sienne : un type, une pièce. Un vendeur qui renvoie en `both` ne réécrit que
les pièces qu'il a modifiées, si bien que ce que vous avez envoyé sous un autre type reste. Vous et le
vendeur pouvez envoyer en même temps : chaque pièce s'ajoute par son type sans effacer celle de
l'autre. Une pièce envoyée après la clôture du litige est refusée avec `422`.

Qui a envoyé chaque pièce est dans le `evidence_submitted_by` du litige, par type de preuve, pièce
texte seul comprise :

| Valeur     | Qui                                                           |
| ---------- | ------------------------------------------------------------- |
| `merchant` | Le marchand, dans le Dashboard ou par l'API sans `X-Sync`     |
| `platform` | Vous, par l'API avec `X-Sync`                                 |
| `seller`   | Le vendeur Lite, depuis son espace ou le composant `disputes` |
| `null`     | Une pièce envoyée avant que Wajub garde qui l'a envoyée       |

```json title="Qui a envoyé quoi"
"evidence": {
"proof_of_delivery": { "file_name": "bon-de-livraison.pdf", "submitted_by": "seller", "url": "https://…" },
"customer_communication": "L'acheteur a confirmé la réception par message le 18 novembre."
},
"evidence_submitted_by": {
"proof_of_delivery": "seller",
"customer_communication": "platform"
}
```

`evidence` lui-même ne change pas : une pièce texte seul est toujours rendue comme son texte, si bien
qu'un code qui lit une chaîne continue de marcher, et une pièce avec fichier est un objet qui porte
aussi son propre `submitted_by`.

## L'événement

`account.dispute_evidence_submitted` parvient à votre plateforme, dans l'environnement du litige,
chaque fois qu'un envoi du vendeur ajoute ou change une pièce, et quand la coupure envoie son
brouillon pour lui. C'est une [livraison du cycle de vie Sync](https://docs.wajub.com/fr/developer-tools/webhooks/events#sync-lifecycle-deliveries) :
listez-le par son nom dans les événements de votre endpoint.

```json title="Une livraison account.dispute_evidence_submitted"
{
"event": "account.dispute_evidence_submitted",
"account": "acc_Gt6yU3nE8rM1kS5vX9bQ",
"sandbox": false,
"timestamp": "2026-11-21T09:12:04+00:00",
"dispute": {
  "id": "dsp_8Hq2Lw4Tz6Nc1Vb3Xk9R",
  "payment": "trx_Lw2Ka8Qd1Fz6Tn4Bc7Xm",
  "status": "under_review",
  "reason": "product_not_received",
  "amount": 20000,
  "currency": "XAF",
  "due_date": "2026-11-30T10:00:00+00:00"
},
"submitted_by": "seller",
"evidence_types": ["proof_of_delivery"],
"dispute_handling": "both",
"seller_may_change_until": "2026-11-29T10:00:00+00:00"
}
```

`submitted_by` vaut `seller`, ou `auto` quand la coupure a envoyé le brouillon.
`seller_may_change_until` est renseigné en `both` tant que la réponse reste ouverte au vendeur,
`null` sinon. Les copies `dispute.*` que vous recevez déjà ne changent pas.

## Le composant `disputes`

Activez-le avec `components: { disputes: { enabled: true } }` sur
`POST /accounts/{id}/embedded_sessions`, puis `wajub.create('disputes').mount('#wajub-disputes')`.
Comptes `lite` seulement : un compte `relay` répond `component_not_available`. Il n'a aucune fonction
à activer : il suit `dispute_handling`, un formulaire pour `seller` et `both`, la lecture seule pour
`platform`. Il ne montre jamais vos propres pièces ni l'adresse d'un fichier.

## L'argent ne change pas

Un litige perdu est débité comme il l'a toujours été ([Remboursements Sync](https://docs.wajub.com/fr/sync/refunds#a-lost-dispute-is-always-debited)).
Un litige gagné sur une vente [bloquée jusqu'à la livraison](https://docs.wajub.com/fr/sync/holds) rend au vendeur ce que le
litige retenait, et la vente reste bloquée jusqu'à votre libération.

- [Litiges](https://docs.wajub.com/fr/api/disputes): Le cycle de vie d'un litige et l'API des preuves.
- [Composants embarqués](https://docs.wajub.com/fr/sync/embedded-components): Le composant `disputes` et les autres.
- [Remboursements Sync](https://docs.wajub.com/fr/sync/refunds): Qui paie un remboursement ou un litige perdu.
