# Rapports et relevés

> Rapprochez chaque versement à vos vendeurs, déclarez votre commission, et remettez à chaque vendeur un relevé annuel à votre marque.

Votre comptable rapproche chaque versement fait à vos vendeurs de votre relevé bancaire ou opérateur,
et déclare votre commission. Demandez à Wajub un **rapport**, sous **Sync, Rapports** ou avec
`POST /sync/reports` : il est préparé en arrière-plan, en général en une minute ou deux, puis

- `report.ready` parvient à vos endpoints ;
- le membre qui l'a demandé dans le Dashboard reçoit un e-mail, avec un lien vers le Dashboard, jamais
  vers le fichier ;
- il est gardé **30 jours**, et se télécharge par un lien **signé pour 15 minutes**.

## Les cinq rapports

| `type`                  | Formats       | Contient                                                                                                                                                                                                 |
| ----------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payout_reconciliation` | `csv`, `xlsx` | Chaque élément de chaque versement à chaque vendeur, une ligne chacun                                                                                                                                    |
| `seller_summary`        | `csv`, `xlsx` | Par vendeur et devise : ventes, remboursements, litiges perdus, commission prise, rendue et nette, versé ; et, au moment de la préparation, ce qui lui est dû, ce qui est retenu, sa dette de couverture |
| `platform_commission`   | `csv`, `xlsx` | Votre commission par mois, vendeur et devise : prise, rendue, nette                                                                                                                                      |
| `relay_dues`            | `csv`, `xlsx` | Les dus de vos vendeurs Relay : leur état, et le versement qui les a payés                                                                                                                               |
| `seller_statement`      | `pdf`         | Le relevé d'un vendeur Lite ou Relay sur la période                                                                                                                                                      |

| Règle                |                                                                                                                                                                                                                        |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Période              | Jours UTC, de `period_start` à minuit jusqu'à la fin de `period_end`, **366 jours au plus**                                                                                                                            |
| Montants             | Unités majeures avec leur devise, en décimal exact avec les décimales de la devise (`19000.00`, `-286.50`). Un montant négatif reste un nombre                                                                         |
| Dates                | ISO 8601 UTC avec décalage (`2026-11-06T07:00:00+00:00`) ; un jour seul en `YYYY-MM-DD`                                                                                                                                |
| Colonnes stables     | `format_version` (aujourd'hui `1`) est dans le rapport **et dans le nom du fichier** : `payout_reconciliation_v1_2026-11-01_2026-11-30.csv`. Une colonne ne change jamais de sens dans une version                     |
| Données personnelles | Le nom du vendeur seulement. Aucune adresse e-mail, aucun numéro de téléphone, aucune pièce d'identité                                                                                                                 |
| CSV                  | UTF-8 avec BOM, virgule, guillemets RFC 4180, noms des colonnes en première ligne. Une cellule texte qui commence par `=`, `+`, `-` ou `@` reçoit une apostrophe devant : elle n'est jamais exécutée comme une formule |
| XLSX                 | Une feuille, « Report », en-tête en gras figé ; textes en chaînes, jamais en formules ; montants et compteurs en nombres. Au-delà de 1 048 576 lignes, il échoue avec `too_many_rows` : demandez-le en CSV             |
| Clé de test          | Préparé sur les données de test (`rpt_test_…`), avec `report.ready` en test                                                                                                                                            |
| Attente              | 5 rapports au plus à la fois, en préparation ou en file. Un rapport encore `pending` peut être annulé sous **Sync, Rapports** : il passe `failed` avec `cancelled` et libère sa place                                  |

## En demander un

```bash title="Les versements de novembre, en CSV"
curl https://api.wajub.com/sync/reports \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -d '{"type":"payout_reconciliation","format":"csv","period_start":"2026-11-01","period_end":"2026-11-30"}'
```

| Champ                        |                                                                                                                                                                                        |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                       | Requis : l'un des cinq ci-dessus                                                                                                                                                       |
| `period_start`, `period_end` | Requis, `YYYY-MM-DD`, UTC ; `period_end` le même jour que `period_start` ou après                                                                                                      |
| `format`                     | `csv` ou `xlsx` pour un export, requis ; `pdf` pour un relevé, la valeur par défaut                                                                                                    |
| `account`                    | Le `acc_…` du vendeur, requis pour `seller_statement` : un de vos comptes `lite` ou `relay`, du même environnement                                                                     |
| `locale`                     | La langue d'un `seller_statement` : `en`, la valeur par défaut, ou `fr`. Les exports sont les mêmes dans les deux : leurs colonnes ne changent jamais. Toute autre valeur répond `422` |

La réponse est `202` avec le `report`, `pending`. Appelé avec votre propre clé, jamais avec `X-Sync`.

| `error_code`              | Statut | Quand                                                                                |
| ------------------------- | ------ | ------------------------------------------------------------------------------------ |
| `format_not_available`    | `422`  | `pdf` pour un export, `csv` ou `xlsx` pour un relevé, ou aucun format pour un export |
| `period_too_long`         | `422`  | Plus de 366 jours                                                                    |
| `account_required`        | `422`  | `seller_statement` sans `account`                                                    |
| `statement_not_available` | `400`  | Un relevé pour un compte `direct` : il a ses propres rapports Wajub                  |
| `too_many_reports`        | `429`  | 5 rapports déjà en attente                                                           |
|                           | `404`  | `account` inconnu, d'une autre plateforme, ou de l'autre environnement               |

## Le télécharger

Quand `report.ready` arrive, `GET /sync/reports/{id}` rend le rapport avec `url`, un lien signé pour
15 minutes (`url_expires_at`). Rappelez-le pour un lien neuf, et ne stockez jamais le lien.

| `status`              |                                                                                                                                                                                                                                                          |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pending`, `building` | En route. Une année d'une grande plateforme peut rester `building` quelques minutes : vous recevez tout de même un seul fichier, et un seul `report.ready`                                                                                               |
| `ready`               | `url`, `row_count` (exports, sans l'en-tête), `file_name`, `file_size` en octets, `completed_at`, `expires_at`                                                                                                                                           |
| `failed`              | `failure_reason` : `too_many_rows` (un XLSX au-delà de la dernière ligne d'Excel, demandez-le en CSV), `build_failed` (trois essais ont échoué, redemandez-le) ou `cancelled` (annulé dans le Dashboard). Un rapport en échec ne compte plus parmi les 5 |
| `expired`             | Le fichier a été supprimé après 30 jours                                                                                                                                                                                                                 |

`report.ready` est envoyé une fois par rapport. 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. Son corps porte `event`, `sandbox`, `timestamp` et le `report`, sans lien. Un
rapport en échec n'envoie rien : lisez-le avec `GET`.

## Les colonnes de `payout_reconciliation`

Une ligne par **élément** de chaque versement que Wajub a fait à vos vendeurs. Un versement est dans
la période par sa **date de valeur**, ou, pas encore payé, par sa création. &#x2A;*Les `amount` des lignes
d'un versement totalisent son `payout_amount`, au centime.** Les versements se suivent dans ce même
ordre, par date de valeur (ou création), puis versement par versement, et les lignes d'un versement
gardent leur ordre (`line`).

| Colonne                                            |                                                                                       |
| -------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `payout_id`, `payout_status`                       | `po_…` ; `pending`, `processing`, `succeeded`, `failed` ou `cancelled`                |
| `payout_created_at`, `payout_value_date`           | Création ; date de valeur, vide tant qu'il n'a pas réussi                             |
| `operator_reference`                               | La référence de l'opérateur, celle de votre relevé                                    |
| `payout_amount`, `currency`                        | Ce que le versement a payé                                                            |
| `account`, `account_type`, `seller_name`           | Le vendeur                                                                            |
| `line`, `element`, `amount`                        | Le rang de la ligne dans le versement, ce qu'elle est, et sa part signée du versement |
| `payment`, `refund`, `dispute`                     | Les identifiants publics concernés                                                    |
| `occurred_at`                                      | Quand l'élément a eu lieu                                                             |
| `escrow_amount`, `hold_status`, `hold_released_at` | Le [blocage jusqu'à la livraison](https://docs.wajub.com/fr/sync/holds) de la vente concernée                  |

| `element`                                            | Signe |                                                                                                                                           |
| ---------------------------------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `sale`, `share`                                      | +     | Une vente, ou une part d'un paiement partagé, brute                                                                                       |
| `wajub_fee`                                          | −     | Les frais de Wajub sur elle                                                                                                               |
| `commission`                                         | −     | Votre commission                                                                                                                          |
| `refund`, `dispute`                                  | −     | Ce qu'un remboursement ou un litige perdu a repris                                                                                        |
| `commission_returned`                                | +     | Votre commission rendue avec lui                                                                                                          |
| `cover`, `recovery`                                  | + / − | Ce que vous avez couvert pour le vendeur, et ce que vous avez repris                                                                      |
| `debt`                                               | −     | La dette d'un vendeur Relay, compensée                                                                                                    |
| `payout_fee`                                         | −     | Les frais du versement lui-même                                                                                                           |
| `reserve_brought_forward`, `balance_brought_forward` | +     | Ce que le versement précédent avait laissé                                                                                                |
| `reserve_held`, `balance_carried_forward`            | −     | Ce que ce versement laisse pour plus tard                                                                                                 |
| `adjustment`                                         | ±     | Un mouvement de solde qu'aucun autre élément n'explique                                                                                   |
| `rounding`                                           | ±     | Un écart au centime entre le brut, les frais, la commission et ce qui a été versé                                                         |
| `escrow_released`                                    | 0     | Une vente Lite bloquée libérée depuis le versement précédent, payée au travers de `balance_brought_forward` ; `escrow_amount` dit combien |
| `unreported`                                         | +     | Un versement dont le détail n'a jamais été écrit : une ligne de tout son montant                                                          |

Les autres exports donnent leurs colonnes de la même façon, dans l'en-tête du fichier :
`seller_summary` (`balance_due`, `withheld` et `cover_debt` sont ceux du moment de la préparation,
`as_of`, et vides pour un vendeur `direct` ; sa dernière colonne, `card_reserve`, est ce que les
ventes par carte du vendeur gardent contre les rétrofacturations, compris dans `withheld`), `platform_commission` (une ligne par mois, vendeur et
devise) et `relay_dues` (un dû par ligne, `outstanding` comme le lit `GET /accounts/{id}/dues`).

## Les relevés de vos vendeurs

Un `seller_statement` est un PDF pour un vendeur Lite ou Relay, **à votre marque** : par devise, ce
qui a été encaissé pour lui, remboursé, perdu en litige, gardé comme votre commission et versé, puis
mois par mois. Il dit être un justificatif pour sa comptabilité, pas une déclaration fiscale ; les
frais de Wajub sont dans le détail de chaque versement. Par l'API, il est en anglais sauf si vous
demandez `locale: fr` ; depuis le Dashboard, dans la langue du membre qui le demande.

Un litige que le marchand a accepté ne compte qu'une fois, dans les litiges perdus, jamais aussi dans
les remboursements : dans le relevé, dans `seller_summary` et dans les chiffres du vendeur. Les
remboursements ordinaires restent dans les remboursements.

| Qui                                      | Où                                                                                                                                                  |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Vous                                     | La page du vendeur dans **Sync, Comptes**, un bouton par année depuis sa connexion ; ou `POST /sync/reports` sur toute période de 366 jours au plus |
| Un vendeur Lite                          | Son portail, sous Versements                                                                                                                        |
| Un vendeur Lite ou Relay, dans vos pages | Le [composant](https://docs.wajub.com/fr/sync/embedded-components) `payouts` montre ses relevés par année                                                                    |

- [Analyses](https://docs.wajub.com/fr/sync/analytics): Le même grand livre, en chiffres sur une période.
- [Ce que règle un versement](https://docs.wajub.com/fr/sync/payouts#what-a-payout-settles): Les lignes de chaque versement, dans l'API.
- [Demander un rapport](https://docs.wajub.com/fr/api/subaccounts/create-report): La spécification de l'endpoint.
