# Préparer un export

`POST https://api.payiz.app/v1/exports`

Demande une clé secrète qui porte le geste « Rapports · exporter ».

Prépare un fichier CSV ou Excel de ce que la page Rapports exporte : paiements, essais, remboursements, retraits, litiges, mouvements du compte, factures ou clients, sur une période.

L’export naît « pending ». Le webhook « export.ready » prévient quand le fichier est prêt ; « file_url » le rend alors, avec votre clé secrète. Les numéros des payeurs y sont toujours masqués.

## Les en-têtes

| Champ | Type | Requis | Ce que c'est |
| --- | --- | --- | --- |
| `Idempotency-Key` | texte | — | Conseillée : la même clé rend le même export, sans en préparer un second. |

## Ce qu'on envoie

Un corps JSON.

| Champ | Type | Requis | Ce que c'est |
| --- | --- | --- | --- |
| `dataset` | texte | oui | Ce que vous exportez : « payments » (les paiements), « attempts » (les essais de paiement), « refunds », « payouts », « disputes », « ledger » (les mouvements du compte), « invoices » ou « customers ». |
| `from` | texte | oui | Le premier jour, au format AAAA-MM-JJ, à l’heure du pays de l’espace. |
| `to` | texte | oui | Le dernier jour, compris. |
| `format` | « csv » · « xlsx » | — | Par défaut « csv » : UTF-8 et point-virgule. « xlsx » : un classeur Excel, montants et dates en nombres. |
| `columns` | « accounting » · « full » ou liste | — | Par défaut « accounting », les colonnes du modèle Comptable ; « full », toutes ; ou la liste des colonnes voulues, dans l’ordre. Les en-têtes du fichier sont ces noms. |
| `currency` | texte | — | Sans précision : la monnaie de l’espace. Une monnaie à la fois. |
| `filters` | objet | — | Les filtres de la page Rapports : status, channel, operator, country, metadata. Ils valent pour les jeux qui les suivent. |

## Ce qu'on reçoit

`202` · un objet `export`

| Champ | Type | Requis | Ce que c'est |
| --- | --- | --- | --- |
| `id` | texte | — | Un identifiant préfixé « exp_ », par exemple exp_01j9zk4m2q8w5tz7m3kd6hw2pv. |
| `object` | « export » | — | Le genre de l’objet rendu : il ne change jamais. |
| `dataset` | texte | — | Ce qui est exporté, comme demandé. |
| `format` | « csv » · « xlsx » | — | Le format du fichier. |
| `columns` | liste | — | Les colonnes du fichier, dans l’ordre. |
| `from` | texte | — | Le premier jour couvert. |
| `to` | texte | — | Le dernier jour couvert. |
| `currency` | texte | — | Le code ISO 4217, en majuscules. |
| `status` | « pending » · « ready » · « failed » | — | Où en est le fichier. « failed » : il n’a pas pu se préparer ; demandez-en un autre. |
| `rows` | entier | — | Le nombre de lignes du fichier. |
| `file_url` | texte ou null | — | L’adresse du fichier une fois prêt (GET, avec votre clé secrète). Null tant qu’il se prépare. |
| `expires_at` | entier | — | Des secondes depuis 1970 : le fichier s’efface ensuite. |
| `created` | entier | — | Des secondes depuis 1970. |
| `livemode` | vrai ou faux | — | Faux en mode test : aucun argent ne circule. |

## La demande

```bash
curl https://api.payiz.app/v1/exports \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: rapports-exporter-01" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset": "payments",
    "from": "2026-09-01",
    "to": "2026-09-30",
    "format": "xlsx",
    "columns": "accounting"
  }'
```

## La réponse

```json
{
  "id": "exp_01j9zk4m2q8w5tz7m3kd6hw2pv",
  "object": "export",
  "dataset": "payments",
  "format": "xlsx",
  "columns": [
    "date",
    "reference",
    "description",
    "status",
    "amount",
    "fee",
    "net",
    "currency"
  ],
  "from": "2026-09-01",
  "to": "2026-09-30",
  "currency": "XOF",
  "status": "pending",
  "rows": 92,
  "file_url": null,
  "expires_at": 1793433600,
  "created": 1790841600,
  "livemode": false
}
```