Estado de la ingesta

GET {{base_url}}/v1/documents/envelopes/{{ingest_token}}/status

Estado de la ingesta

Devuelve el progreso del procesamiento por lotes. Cuando el estado cambia a ready, la respuesta incluye el document_token real, el cual debe utilizarse para realizar las consultas posteriores en los endpoints de lectura de documentos.

Autenticación

Parámetro	Tipo	Descripción	Límites
`Authorization*`	string	Token de autenticación Bearer.	Obligatorio (Bearer <token>)

Parámetros de Ruta

Parámetro	Tipo	Descripción	Límites
`ingest_token*`	string (UUID)	El token identificador del lote recibido en la respuesta 202 del endpoint asíncrono.	Obligatorio

Respuesta en Curso (200 OK)

Muestra el estado del lote mientras los archivos se están descargando y armando en background.

{
  "ingest_token": "01234567-...",
  "status": "ingesting",
  "documents_total": 80,
  "documents_ingested": 67,
  "documents_failed": 0,
  "bytes_ingested": 743891200,
  "bytes_limit": 1073741824,
  "errors": [],
  "document_token": null,
  "external_id": "BATCH-12345",
  "started_at": "2026-04-15T14:30:00Z",
  "completed_at": null
}

Nombre	Tipo	Descripción
`ingest_token`	string (UUID)	Identificador único del proceso de ingesta.
`status`	string	Estado actual del lote: ingesting · assembling · ready · failed · cancelled.
`documents_total`	integer	Cantidad total de documentos enviados en el lote.
`documents_ingested`	integer	Cantidad de documentos que ya fueron descargados y procesados con éxito.
`documents_failed`	integer	Cantidad de documentos que fallaron durante la ingesta.
`bytes_ingested`	integer	Cantidad de bytes procesados hasta el momento.
`bytes_limit`	integer	Límite máximo de peso permitido para el lote (1 GB total).
`errors`	array	Colección con el detalle de los errores individuales por documento.
`document_token`	string (UUID)	Token final del sobre (null mientras esté en curso).
`external_id`	string	Identificador externo enviado en la creación del lote (pass-through).
`started_at`	string (ISO8601)	Fecha y hora de inicio del procesamiento en background.
`completed_at`	string (ISO8601)	Fecha y hora de finalización del lote (null mientras esté en curso).

Respuesta Completada con Éxito (200 OK)

Estructura de la respuesta cuando el procesamiento ha concluido correctamente y el sobre está listo para producción.

{
  "ingest_token": "01234567-...",
  "status": "ready",
  "documents_total": 80,
  "documents_ingested": 80,
  "documents_failed": 0,
  "document_token": "abcdef01-...",
  "external_id": "BATCH-12345",
  "started_at": "2026-04-15T14:30:00Z",
  "completed_at": "2026-04-15T14:42:00Z"
}

Nombre	Tipo	Descripción
`ingest_token`	string (UUID)	Identificador único del proceso de ingesta.
`status`	string	Estado final exitoso: ready.
`documents_total`	integer	Cantidad total de documentos procesados.
`documents_ingested`	integer	Cantidad de documentos procesados con éxito.
`documents_failed`	integer	Cantidad de documentos fallidos (0 en caso de éxito total).
`document_token`	string (UUID)	Token definitivo del sobre generado para consumir en el resto de la API.
`external_id`	string	Identificador externo asociado al lote.
`started_at`	string (ISO8601)	Fecha y hora de inicio de la ingesta.
`completed_at`	string (ISO8601)	Fecha y hora exacta de la finalización del proceso.

Respuesta con Errores de Procesamiento (200 OK)

Estructura devuelta si uno o más archivos no pudieron integrarse al sobre (por ejemplo, fallas de descarga en las URLs origen).

{
  "ingest_token": "01234567-...",
  "status": "failed",
  "failure_reason": "source_error",
  "documents_total": 80,
  "documents_ingested": 79,
  "documents_failed": 1,
  "errors": [
    {
      "ref_id": "doc-43",
      "error": "La URL de 'doc-43' respondió HTTP 404."
    }
  ],
  "document_token": null
}

Nombre	Tipo	Descripción
`ingest_token`	string (UUID)	Identificador único del proceso de ingesta.
`status`	string	Estado terminal con fallas: failed.
`failure_reason`	string	Código del motivo del fallo general. Valores posibles: `timeout` (tiempo de espera agotado), `size_limit` (excede el límite de peso), `source_error` (error al descargar desde la URL origen) o `internal_error` (error interno del servidor).
`documents_total`	integer	Cantidad total de documentos solicitados.
`documents_ingested`	integer	Cantidad de documentos que llegaron a procesarse antes del fallo.
`documents_failed`	integer	Cantidad de documentos que desencadenaron el error.
`errors`	array	Lista de objetos de error con el ref_id del documento afectado y el detalle del mensaje de error.
`document_token`	null	No se genera token de sobre si la ingesta falla.

Respuestas de Error Comunes

Código	Estado	Descripción
`401`	Unauthorized	El token de autenticación es inválido, expiró o no fue enviado.
`404`	Not Found	El `ingest_token` provisto no existe o no corresponde a la organización activa.