Modelo de Tareas Asíncronas

Subir un documento no lo procesa, y comenzar el procesamiento no lo termina en la misma solicitud. Cada documento y lote avanza a través de un conjunto fijo y cerrado de estados; esta página cubre ese ciclo de vida de principio a fin.

Ciclo de vida de los estados

Cada documento (y, en conjunto, cada lote) siempre está exactamente en uno de cinco estados:

encolado → procesando → completado | fallido | cancelado

queued — subido y/o esperando a que un worker lo tome.
processing — un worker ha tomado el documento y está extrayendo datos activamente.
succeeded — extracción finalizada; line_items en la respuesta de resultados está poblado.
failed — la extracción no pudo completarse para este documento (es un resultado a nivel de documento, no un error de llamada a la API; consulta la nota sobre processing_error en Manejo de Errores).
canceled — el documento se eliminó de la cola antes de que comenzara el procesamiento (por ejemplo, su lote se eliminó mientras aún estaba queued).

Este conjunto de cinco valores es un contrato público, deliberadamente desacoplado de los estados internos que el sistema usa entre bastidores. Se pueden introducir nuevos estados intermedios internos más adelante sin agregar nunca un sexto valor aquí — cada respuesta v1 que analices hoy seguirá funcionando.

La cadena de marcas de tiempo

Tanto las respuestas de documento (GET /documents/{id}) como las de lote (GET /batches/{batch_name}/results) incluyen los mismos tres campos, para que puedas distinguir entre «en cola pero atascado», «ejecutándose activamente» y «realmente terminado»:

Campo	Se establece cuando
`created_at`	El documento fue subido (o, para un lote, la subida más antigua en él).
`started_at`	Un worker tomó el documento y comenzó a procesarlo. Permanece como `null` mientras `status` siga siendo `queued`.
`completed_at`	El documento alcanzó un estado terminal — `succeeded`, `failed` o `canceled`. Permanece como `null` mientras siga `queued` o `processing`. A nivel de lote, permanece `null` hasta que todos los documentos del lote tengan uno — un lote con algo aún en proceso no está «completado» todavía, incluso si algunos de sus documentos ya terminaron.

Sondeo vs. webhooks

Tienes dos formas de saber cuándo un lote está listo:

Sondeo — llama a GET /batches/{batch_name} periódicamente y verifica all_done. Simple, no requiere infraestructura de tu parte, pero desperdicia solicitudes si sondeas demasiado agresivamente (consulta Límites de tasa para el límite de 120/minuto en los endpoints de estado) o demasiado lento (latencia añadida antes de que notes la finalización).
Webhooks — registra una URL de callback una vez con PUT /batches/{batch_name}/webhook y recibe una notificación en el momento en que el lote termine, en lugar de preguntar repetidamente. Consulta la guía de Webhooks — también cubre qué sucede si agregas más documentos a un lote y lo procesas de nuevo después de que ya te notificó una vez (resumen: recibes una notificación de nuevo automáticamente, sin necesidad de registro adicional).

Para un solo lote pequeño procesado una vez, sondear unas cuantas veces es lo más simple. Para volúmenes más altos, o donde no quieras tener un bucle de solicitudes esperando, los webhooks son la mejor opción.