Modelo de Tarefa Assíncrona

Fazer upload de um documento não o processa, e iniciar o processamento não o conclui na mesma requisição. Cada documento e lote passa por um conjunto fixo e fechado de status — esta página cobre esse ciclo de vida do início ao fim.

Ciclo de vida dos status

Cada documento (e, de forma agregada, cada lote) está sempre exatamente em um de cinco estados:

enfileirado → processando → sucesso | falha | cancelado

queued — enviado e/ou aguardando um worker pegá-lo.
processing — um worker assumiu o documento e está extraindo dados ativamente.
succeeded — extração concluída; o campo line_items na resposta de resultados está preenchido.
failed — a extração não pôde ser concluída para este documento (é um resultado em nível de documento, não um erro de chamada de API — veja a nota sobre processing_error em Tratamento de Erros).
canceled — o documento foi removido da fila antes do processamento começar (por exemplo, seu lote foi excluído enquanto ainda estava queued).

Este conjunto de cinco valores é um contrato público, deliberadamente desacoplado de quaisquer estados internos que o sistema use nos bastidores. Novos estados intermediários internos podem ser introduzidos posteriormente sem nunca adicionar um sexto valor aqui — toda resposta v1 que você analisa hoje continuará funcionando.

A cadeia de timestamps

Tanto as respostas de documento (GET /documents/{id}) quanto de lote (GET /batches/{batch_name}/results) trazem os mesmos três campos, permitindo distinguir entre "na fila mas travado", "em execução ativa" e "genuinamente concluído":

Campo	Definido quando
`created_at`	O documento foi enviado (ou, para um lote, o envio mais antigo dentro dele).
`started_at`	Um worker assumiu o documento e começou a processá-lo. Permanece `null` enquanto o `status` ainda for `queued`.
`completed_at`	O documento atingiu um estado terminal — `succeeded`, `failed` ou `canceled`. Permanece `null` enquanto ainda estiver `queued` ou `processing`. No nível do lote, permanece `null` até que todos os documentos do lote tenham um — um lote com qualquer documento ainda em andamento não está "concluído", mesmo que alguns de seus documentos já tenham terminado.

Polling vs. webhooks

Você tem duas maneiras de saber quando um lote está concluído:

Polling — chame GET /batches/{batch_name} periodicamente e verifique all_done. Simples, sem necessidade de infraestrutura da sua parte, mas desperdiça requisições se você fizer polling agressivamente demais (veja Limites de Taxa para o teto de 120/minuto nos endpoints de status) ou lentamente demais (latência adicional antes de perceber a conclusão).
Webhooks — registre uma URL de callback uma vez com PUT /batches/{batch_name}/webhook e seja notificado no momento em que o lote terminar, em vez de perguntar repetidamente. Consulte o guia de Webhooks — ele também cobre o que acontece se você adicionar mais documentos a um lote e processá-lo novamente depois que ele já notificou você uma vez (resumo: você é notificado novamente automaticamente, sem necessidade de registro extra).

Para um único lote pequeno processado uma vez, fazer polling algumas vezes é o mais simples. Para qualquer coisa de maior volume, ou onde você não queira um loop de requisições parado esperando, webhooks são a melhor opção.