# Envoyer des documents

```
POST /api/v1/submissions
```

Un **envoi** (`submission`) regroupe un ou plusieurs fichiers déposés ensemble. Chaque document qu'il contient devient une **vérification** (`check`), analysée séparément.

## Ce qui compte comme un document

| Fichier envoyé | Vérifications créées |
|---|---|
| Une image (JPG, PNG, HEIC...) | 1 |
| Un PDF d'une page | 1 |
| Un PDF de N pages | N : une par page, car un dossier scanné contient souvent plusieurs pièces différentes |
| Une archive ZIP ou RAR | une par fichier qu'elle contient (et une par page de chaque PDF) |

Chaque vérification coûte le même nombre de crédits que sur le site (valeur exacte : `credits_per_document` dans [GET /account](/developpeurs/compte-et-referentiels)). Les crédits sont débités à l'envoi, puis **rendus automatiquement** si le fichier n'est pas un document ou si l'analyse échoue (`refunded: true`).

## Paramètres

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `files[]` | fichier(s) | oui | Envoi en `multipart/form-data`. Pour un seul fichier, `file` est aussi accepté. |
| `files` | tableau JSON | oui (en JSON) | Envoi en `application/json` : `[{"filename": "rib.pdf", "content_base64": "JVBERi0..."}]`. |
| `final_check` | texte | non | Demande une vérification croisée de tout le dossier. Voir [Dossiers](/developpeurs/dossiers). |

En-têtes facultatifs :

| En-tête | Description |
|---|---|
| `Idempotency-Key` | Une valeur unique de votre choix (1 à 255 caractères). Si la même valeur est renvoyée dans les 24 heures, l'API rend l'envoi déjà créé, sans rien débiter une deuxième fois (réponse `200`, en-tête `Idempotent-Replayed: true`). À utiliser pour rejouer une requête sans risque après une coupure réseau. |

Paramètre de réponse facultatif : `?detail=full` renvoie aussi le détail des analyses (voir [Objets](/developpeurs/objets)).

## Limites

Les limites exactes de votre compte sont renvoyées par [GET /account](/developpeurs/compte-et-referentiels), dans `limits` :

- `max_file_size_mb` : taille maximale d'un fichier ;
- `max_files_per_submission` : nombre maximal de fichiers dans un envoi ;
- `allowed_extensions` : formats acceptés.

Une archive peut contenir au plus 300 fichiers et 1 Go une fois décompressée. Les fichiers d'un format non accepté sont ignorés à l'intérieur d'une archive (ils ne sont pas facturés).

## Exemple : plusieurs fichiers en multipart

```bash
curl -X POST https://france-verification.com/api/v1/submissions \
  -H "Authorization: Bearer $FV_API_KEY" \
  -H "Idempotency-Key: dossier-client-8841" \
  -F "files[]=@piece-identite.jpg" \
  -F "files[]=@bulletins-de-salaire.pdf"
```

## Exemple : JSON et base64 (Zapier, Make, n8n)

Les outils sans code gèrent souvent mal l'envoi de fichiers. Envoyez alors le contenu encodé en base64 :

```bash
curl -X POST https://france-verification.com/api/v1/submissions \
  -H "Authorization: Bearer $FV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      { "filename": "rib.pdf", "content_base64": "JVBERi0xLjQKJ..." }
    ]
  }'
```

## Réponse

`202 Accepted` et l'objet [Submission](/developpeurs/objets). À ce stade, les vérifications sont en `pending` : lisez la suite dans [Suivre un envoi](/developpeurs/suivre-un-envoi).

## Erreurs possibles

| Statut | Code | Cause |
|---|---|---|
| 402 | `insufficient_credits` | Solde insuffisant. `details` donne `credits_available`, `credits_required` et `documents_count`. Rien n'est débité. |
| 422 | `validation_failed` | Aucun fichier, format refusé, fichier trop lourd, trop de fichiers, `final_check` inconnu. `details.fields` dit quel champ pose problème. |
| 413 | `validation_failed` | Requête trop volumineuse. |