Modèle de tâche asynchrone

L'upload d'un document ne le traite pas, et le lancement du traitement ne se termine pas dans la même requête. Chaque document et chaque lot passe par un ensemble fixe et fermé de statuts — cette page couvre ce cycle de vie de bout en bout.

Cycle de vie des statuts

Chaque document (et, globalement, chaque lot) se trouve toujours dans exactement un des cinq états suivants :

queued → processing → succeeded | failed | canceled

queued — uploadé et/ou en attente qu'un worker le prenne en charge.
processing — un worker a pris le document et en extrait activement les données.
succeeded — extraction terminée ; le champ line_items dans la réponse des résultats est renseigné.
failed — l'extraction n'a pas pu aboutir pour ce document (il s'agit d'un résultat au niveau du document, pas d'une erreur d'appel API — voir la note sur processing_error dans Gestion des erreurs).
canceled — le document a été retiré de la file d'attente avant le début du traitement (par exemple, son lot a été supprimé alors qu'il était encore queued).

Cet ensemble de cinq valeurs est un contrat public, délibérément découplé des états internes que le système utilise en arrière-plan. De nouveaux états intermédiaires internes pourront être introduits ultérieurement sans jamais ajouter une sixième valeur ici — chaque réponse v1 que vous analysez aujourd'hui continuera de fonctionner.

La chaîne d'horodatage

Les réponses du document (GET /documents/{id}) et du batch (GET /batches/{batch_name}/results) contiennent les trois mêmes champs, ce qui permet de distinguer « en file d'attente mais bloqué » de « en cours d'exécution active » et de « vraiment terminé » :

Champ	Défini quand
`created_at`	Le document a été téléchargé (ou, pour un batch, le premier téléchargement qu'il contient).
`started_at`	Un worker a pris en charge le document et a commencé à le traiter. Reste `null` tant que le `status` est encore `queued`.
`completed_at`	Le document a atteint un état terminal — `succeeded`, `failed` ou `canceled`. Reste `null` tant qu'il est encore `queued` ou `processing`. Au niveau du batch, reste `null` jusqu'à ce que tous les documents du batch en aient un — un batch contenant encore des documents en cours n'est pas encore « terminé », même si certains de ses documents sont déjà finis.

Polling vs. webhooks

Vous avez deux façons de savoir quand un batch est terminé :

Polling — appelez GET /batches/{batch_name} périodiquement et vérifiez all_done. Simple, aucune infrastructure requise de votre côté, mais gaspille des requêtes si vous interrogez trop agressivement (voir Limites de débit pour le plafond de 120/minute sur les endpoints de statut) ou trop lentement (latence ajoutée avant de remarquer la fin).
Webhooks — enregistrez une URL de callback une fois avec PUT /batches/{batch_name}/webhook et soyez notifié dès que le batch se termine, au lieu de demander à plusieurs reprises. Consultez le guide Webhooks — il couvre également ce qui se passe si vous ajoutez d'autres documents à un batch et le traitez à nouveau après qu'il vous a déjà notifié une fois (en résumé : vous êtes notifié à nouveau automatiquement, sans inscription supplémentaire).

Pour un petit batch unique traité une fois, interroger quelques fois est le plus simple. Pour tout ce qui est plus volumineux, ou si vous ne voulez pas qu'une boucle de requêtes reste en attente, les webhooks sont la meilleure solution.