Ir al contenido
FirmEasy
← Inicio

Estado de la ingesta

GET
https://api.firmeasy.legal/api/v1/documents/envelopes/{{ingest_token}}/status

Estado de la ingesta

Sección titulada «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

Sección titulada «Autenticación»
Authorization
string
Token de autenticación Bearer.
Límites:Obligatorio (Bearer <token>)

Parámetros de Ruta

Sección titulada «Parámetros de Ruta»
ingest_token
string (UUID)
El token identificador del lote recibido en la respuesta 202 del endpoint asíncrono.
Límites:Obligatorio

Respuesta en Curso (200 OK)

Sección titulada «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
}
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)

Sección titulada «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"
}
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)

Sección titulada «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
}
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

Sección titulada «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.