# Envoyer un fichier et le lire
> Envoyer un fichier, le renvoyer sans risque, attendre qu'il soit lu, lire ses documents, récupérer l'original, le supprimer.
>
> Avant: [Clés et autorisations](https://ocost.io/docs/fr/authentication.md)

Envoyez un PDF, une image ou une facture électronique, attendez qu'Ocost l'ait lu, puis lisez ses documents. Un fichier peut contenir plusieurs documents. Un scan de trois factures est un fichier avec trois documents.

## Envoyer le fichier

Envoyez le fichier en `multipart/form-data` à `POST /public/v1/files`. La clé a besoin de l'autorisation [`documents:write`](https://ocost.io/docs/fr/authentication.md).

```bash
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  -F "file=@scan.pdf" -F "name=scan.pdf" -F "external_ref=account.move,42"
```

| Champ | Signification |
| --- | --- |
| `file` | Obligatoire. Un PDF, une image (JPEG, PNG, TIFF, WebP), un fichier Word (.docx, .doc) ou le XML d'une facture électronique (XRechnung, UBL, CII), jusqu'à 25 Mo. |
| `name` | Le nom du fichier. Sans lui, Ocost prend celui de l'envoi. |
| `external_ref` | Votre propre identifiant, jusqu'à 200 caractères, rendu avec le fichier. |

L'API refuse les tableurs (.xls, .xlsx) et les archives (.zip, .7z) avec `415`. Envoyez-les plutôt dans Ocost. Là, Ocost lit une facture dans un tableur d'une seule feuille, jusqu'à 200 lignes et 30 colonnes. Il décompresse une archive une fois, dans la société où elle arrive. Les autres XML et HTML sont stockés, mais finissent `not_read` avec `nothing_found`.

Un nouveau fichier répond `202 Accepted` avec `"status": "received"`, et la lecture commence aussitôt :

```json
{ "id": "01a1b08c-6e3a-7562-8f4a-7924722667b1", "name": "scan.pdf", "status": "received", "external_ref": "account.move,42", "external_refs": ["account.move,42"], "documents": [] }
```

Chaque réponse porte `X-Ocost-Documents-Left`, les documents qui restent à votre formule ce mois-ci. [Limites et erreurs](https://ocost.io/docs/fr/limits.md) liste les refus.

## Le renvoyer sans risque

Ocost reconnaît un fichier au SHA-256 de ses octets, pas à son nom. Les mêmes octets renvoyés répondent `200 OK` avec ce fichier tel qu'il est maintenant. Ocost ne le relit pas et ne le compte pas une seconde fois. Après un délai dépassé, renvoyez donc le fichier.

Un fichier garde chaque `external_ref` envoyé avec ses octets. `external_ref` reste le premier, et `external_refs` les liste tous, le premier en tête, chacun une fois, jusqu'à 50. Quand deux de vos enregistrements portent le même PDF, envoyez-le donc pour chacun : les deux identifiants reviennent avec le même fichier. Un 51e nouvel identifiant est refusé avec `422`.

## Attendre la lecture

Demandez le fichier avec `GET /public/v1/files/{file_id}`, autorisation `documents:read`. Interrogez toutes les 2 à 3 secondes pendant une demi-minute, puis toutes les 10 à 30 secondes. La plupart des PDF prennent moins d'une minute, les longs quelques-unes.

```python
def wait_for(session, file_id, timeout=300):
    started = time.monotonic()
    while time.monotonic() - started < timeout:
        file = session.get(f"{API}/files/{file_id}", timeout=15).json()
        if file["status"] not in ("received", "reading"):
            return file
        time.sleep(3 if time.monotonic() - started < 30 else 15)
    return file
```

Le fichier est terminé quand son `status` vaut `read`, `not_read` ou `failed`. [Statuts et raisons](https://ocost.io/docs/fr/statuses.md) explique chacun. Pour de nombreux fichiers à la fois, [restez synchronisé](https://ocost.io/docs/fr/sync.md) au lieu d'interroger chacun.

## Lire ses documents

Un fichier `read` liste ses documents dans `documents`, chacun avec son `id`, son `kind`, son `number` et ses `pages`. `GET /public/v1/files/{file_id}/document` renvoie le premier. `GET /public/v1/documents/{document_id}` renvoie n'importe lequel.

```bash
curl -sS https://api.ocost.io/public/v1/documents/01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11 \
  -H "Authorization: Bearer $OCOST_KEY"
```

La réponse est le document en `ocost.document.v1`. [Le document](https://ocost.io/docs/fr/document.md) en montre un entier et explique chaque champ.

## Récupérer l'original

`GET /public/v1/files/{file_id}/content` renvoie les octets tels que vous les avez envoyés.

```bash
curl -sS -o scan.pdf https://api.ocost.io/public/v1/files/$FILE_ID/content \
  -H "Authorization: Bearer $OCOST_KEY"
```

## Supprimer un fichier

`DELETE /public/v1/files/{file_id}` efface le fichier aussitôt et pour de bon. Cela comprend ses documents, ce qui a été lu, son index de recherche et l'original. La clé a besoin de `documents:write`.

```bash
curl -sS -X DELETE https://api.ocost.io/public/v1/files/$FILE_ID \
  -H "Authorization: Bearer $OCOST_KEY"
```

Ocost répond `204`, puis `404` à partir de là. Il refuse dans deux cas :

| Réponse | Que faire |
| --- | --- |
| `409 urn:ocost:file:reading` | Le fichier est en cours de lecture. Réessayez plus tard. |
| `409 urn:ocost:file:linked` | Ocost a encore besoin du fichier, pour une facture comptabilisée, un relevé bancaire, une question ouverte ou un projet. `detail` dit lequel. Supprimez-le dans Ocost dès que plus rien n'en a besoin. |

## Voir aussi

- [Statuts et raisons](https://ocost.io/docs/fr/statuses.md): Les statuts d'un fichier et les raisons pour lesquelles il n'a pas été lu, et que faire pour chacun.
- [Le document](https://ocost.io/docs/fr/document.md): Le schéma ocost.document.v1 dans les termes de l'EN 16931 (transposable en UBL et CII) : un exemple, type et sens, sources, contrôles, versions, et chaque champ et chaque valeur.
- [Rester synchronisé](https://ocost.io/docs/fr/sync.md): Récupérer chaque fichier modifié en un seul appel : GET /public/v1/files avec updated_since, un curseur et un filtre de statut.
- [Groupes de sociétés](https://ocost.io/docs/fr/groups.md): Groupes de sociétés : les sociétés qu’une clé atteint, l’en-tête Ocost-Business, l’orientation par les identifiants du document, needs_company et les fichiers du groupe.
- Sur ocost.io: [Invoice processing](https://ocost.io/en/product/invoice-processing)
