Seguimiento del procesamiento

Monitoriza imports, files y documents a través de sus estados de procesamiento.

Invofox hace seguimiento de los elementos principales mencionados en nuestros conceptos básicos mediante un sistema de estados simplificado:

  • Imports: operaciones que procesan uno o varios archivos
  • Files: archivos individuales subidos
  • Documents: salidas procesadas con los datos extraídos

Cada elemento avanza por estados claramente definidos, generando eventos de webhook cuando cambian de estado. Esto proporciona visibilidad en tiempo real de tu pipeline de procesamiento de documentos.

Para los endpoints de la API con los que recuperar la información de estado actual, consulta Recuperación de información.

Procesamiento de Imports

Estados y lógica de transición

  • processing - Import creado y archivos en proceso
  • processed - Todos los archivos han terminado de procesarse (ya sea procesados o rechazados)

Lógica de transición: un Import pasa a processed cuando cada File del Import ha alcanzado el estado processed o rejected.

Ciclo de vida del Import

Solo el estado processed dispara eventos de webhook para los Imports.

Eventos de webhook

  • import.processed - Se dispara cuando un Import alcanza el estado processed

Procesamiento de Files

Estados y lógica de transición

  • pending - File registrado desde un Import o extraído de un ZIP
  • processing - File ingerido y procesándose internamente
  • rejected - File rechazado antes de procesarse (formato inválido, problemas de configuración, corrupción)
  • processed - El File ha generado Documents y todos los Documents están procesados

Lógica de transición: un File pasa a processed cuando:

  • Documento único: el Document asociado alcanza el estado processed
  • Varios documentos (Splitter): todos los Documents asociados alcanzan el estado processed
  • Archivo ZIP: todos los Files extraídos alcanzan el estado processed o rejected

Ciclo de vida del File

Los eventos de webhook se disparan cuando los Files alcanzan estados finales: rejected o processed.

Códigos de error de File

Cuando un File alcanza el estado rejected, incluye un campo error con un código de error concreto (por ejemplo ERR_UNSUPPORTED_FILE_FORMAT). Consulta la lista completa y actualizada en Archivos rechazados.

Eventos de webhook

  • file.rejected - Se dispara cuando un File alcanza el estado rejected
  • file.processed - Se dispara cuando un File alcanza el estado processed

Procesamiento de Documents

Estados y lógica de transición

Los Documents tienen dos sistemas de estado:

Estado de procesamiento (interno):

  • processing - Document con ID asignado y procesándose
  • processed - Procesamiento automático completado

Estados públicos (flujo de trabajo):

  • pendingCorrection - Document a la espera de correcciones manuales o revisión
  • approved - Document aprobado (manual o automático)
  • discarded - Document descartado (manual o automático)
  • processing - ⚠️ Obsoleto - estado público heredado, usa el estado de procesamiento en su lugar
  • exported - ⚠️ Obsoleto - estado exportado heredado
  • error - ⚠️ Obsoleto - estado de error heredado

Nota: El sistema de flujo de trabajo de documentos, incluido el campo publicState y los eventos relacionados (approved, discarded, updated), se está reevaluando y refinando actualmente. Los detalles de implementación pueden cambiar en versiones futuras.

Lógica de transición: un Document pasa del estado processing a processed cuando se completa toda la lógica de extracción y procesamiento automáticos. De forma independiente, los documentos pueden recibir estados públicos de flujo de trabajo (pendingCorrection, approved, discarded) para la gestión de procesos de negocio.

Ciclo de vida del Document

Los eventos de webhook se disparan tanto para los estados de procesamiento como para los estados públicos de flujo de trabajo.

Flujo del estado de procesamiento:

Flujo del estado público (independiente del procesamiento):

Eventos de webhook

Eventos de procesamiento:

  • document.created - Se dispara cuando se crea un Document y entra inmediatamente en estado processing
    • Al Document se le asigna un ID y entra en el pipeline de procesamiento
    • Nota: No hay estados intermedios — el documento se crea y pasa inmediatamente al estado processing. En ese momento el documento estará vacío. La API devolverá un estado 202 Accepted indicando que el documento está reservado pero aún no disponible para su recuperación. Los datos completos del documento estarán disponibles tras el evento document.processed.
  • document.processed - Se dispara cuando un Document alcanza el estado processed
    • Extracción y procesamiento automáticos completados
    • El estado del documento pasa a processed
    • Contiene toda la información extraída

Para la configuración de webhooks y los detalles de implementación, consulta Implementación de webhooks.

Casos especiales

Estos escenarios de procesamiento especiales afectan a cómo funcionan las transiciones de estado para tipos de archivo y configuraciones complejas.

División de documentos (Splitting)

Cuando un File genera varios Documents (p. ej. un PDF de varias páginas):

  1. El File está en estado processing mientras se procesa, lo que da lugar a la creación de Documents
  2. Cada Document sigue su propio ciclo de vida independiente
  3. El File alcanza processed solo cuando todos los Documents alcanzan el estado processed

Esta división puede ocurrir automáticamente con la función premium Splitter de Invofox, que detecta de forma inteligente los límites de los documentos y crea registros de Document separados.

Los metadatos del File incluirán información sobre las divisiones de páginas, como se muestra en la estructura ImportInfo.

Para los detalles de estado de Document y la estructura de la API, consulta Estructura de Document.

Archivos ZIP

Cuando se sube un archivo ZIP a través de los endpoints de subida de múltiples archivos:

  1. El ZIP se acepta y pasa inmediatamente del estado pending a processing
  2. El ZIP se extrae, creando Files hijos
  3. El File padre alcanza processed solo cuando todos los Files hijos alcanzan processed o rejected
  4. Los Files hijos siguen el ciclo de vida normal de un File de forma independiente

Importante: Los archivos ZIP solo se admiten a través de los endpoints de subida de múltiples archivos (Subida Directa y Subida por URL). Los archivos ZIP se procesan de forma asíncrona y pasan directamente al estado pending al aceptarse.

Para flujos avanzados de procesamiento de ZIP, puedes combinar las funciones premium Splitter + Classifier para separar e identificar automáticamente distintos tipos de documento dentro de los archivos ZIP.

El evento file.processed del File padre incluirá información sobre todos los Files hijos extraídos. Para la estructura de metadatos de archivos comprimidos, consulta Estructura de File API.