Envoyer un fichier et le lire

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.

Shell
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"
ChampSignification
fileObligatoire. 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.
nameLe nom du fichier. Sans lui, Ocost prend celui de l'envoi.
external_refVotre 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 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 explique chacun. Pour de nombreux fichiers à la fois, restez synchronisé 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.

Shell
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 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.

Shell
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.

Shell
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éponseQue faire
409 urn:ocost:file:readingLe fichier est en cours de lecture. Réessayez plus tard.
409 urn:ocost:file:linkedOcost 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