Glosario
Definiciones canónicas de cada concepto de Invofox.
Account
El espacio de trabajo de nivel superior de tu organización dentro de Invofox. Contiene uno o varios Environments.
Environment
Un espacio de trabajo dentro de tu Account para organizar los flujos de procesamiento de documentos. Cada uno puede configurarse como entorno TEST o PRODUCTION, cada uno con su propia configuración. Las API keys están vinculadas a un Environment.
API Key
La credencial usada para autenticar las peticiones a la API. Se crea y gestiona en los ajustes del Environment, y está vinculada a un único Environment.
Roles y permisos
El acceso se concede por Account y por Environment a través de tres roles, cada uno construido sobre el anterior:
- User — trabaja con documentos (revisar, corregir, modificar…) pero no puede cambiar la configuración del Account ni del Environment.
- Developer — todo lo que puede hacer un User, más la configuración: API keys, webhooks y el resto de ajustes.
- Admin — acceso total, incluida toda la configuración del Account y del Environment.
Import
La operación de subida y el contenedor de nivel superior. Cada subida (vía API, web o email) crea un Import que agrupa uno o varios Files. Sigues el progreso haciendo polling al Import a través de su importId.
File
Un único archivo subido dentro de un Import. Una vez procesado, cada File produce uno o varios Documents — uno para un PDF simple, o varios cuando un PDF multidocumento se divide o un ZIP se expande.
Document
El resultado extraído producido a partir de un File: los datos estructurados (Fields). Un solo File puede generar varios Documents. Se identifica con un documentId y se obtiene con GET /documents/{documentId}.
Archivo comprimido (ZIP)
Un archivo comprimido (application/zip) que contiene varios archivos. Los endpoints de subida lo aceptan, se extrae de forma asíncrona y cada File hijo extraído sigue luego su propio ciclo de vida. El File padre se marca con compressed: true.
clientData
Un objeto de metadatos opcional que adjuntas al subir. Invofox nunca lo procesa — se devuelve literalmente en las respuestas de la API y en los eventos de webhook. Es especialmente útil para:
- Seguimiento de referencias internas — guarda tus propios IDs, números de referencia o metadatos.
- Integración con webhooks — el dato se devuelve en las notificaciones de webhook, para correlacionarlo fácilmente con tus sistemas internos.
- Recuperación de información — accede a tus datos personalizados al recuperar la información del documento extraído mediante la API.
Document Type
La configuración que define cómo se procesa un tipo concreto de documento y qué Fields se extraen de él. Puede asignarse manualmente en la subida o detectarse automáticamente con el Classifier.
Field
Un único dato extraído de un documento — por ejemplo un número de factura, un importe total o una fecha. Qué Fields se extraen lo determina el Document Type.
Estado de procesamiento
El estado interno del ciclo de vida de un Import, File o Document. Los valores habituales incluyen pending, processing, processed y rejected (el conjunto exacto depende de la entidad). Los cambios de estado son los que disparan los eventos de webhook.
Estado público
Un estado separado, de flujo de trabajo de negocio, asignado a un Document e independiente del estado de procesamiento interno. Es uno de:
pendingCorrection— a la espera de revisión humana.approved— revisado y aceptado.discarded— rechazado o no válido.
Correcciones
Enviar de vuelta a Invofox los valores de Field corregidos (o el Document Type correcto) vía PUT /documents/{id} una vez procesado el Document. Cada corrección alimenta el entrenamiento del modelo, así que la precisión de extracción mejora con el tiempo. Consulta la página Bucle de feedback.
Código de error
El valor devuelto en el campo error de un File cuando es rechazado (por ejemplo, ERR_UNSUPPORTED_FILE_FORMAT). Se devuelve como cadena para manejarlo de forma programática.
Webhook
Una llamada HTTP que Invofox envía a tu endpoint cuando ocurre un evento, para que recibas actualizaciones en tiempo real en lugar de hacer polling.
Evento de webhook
El payload que Invofox entrega a tu endpoint. Siempre incluye type, id, timestamp, data y version. El type coincide con una transición de estado (p. ej. document.processed). Consulta la Referencia de Webhooks → para la lista completa de eventos y los esquemas de payload.
Firma HMAC
Una firma opcional que Invofox añade a las peticiones de webhook para que puedas verificar que provienen realmente de Invofox. Configuras un secreto compartido y validas la firma en tu endpoint.
Idempotencia
Procesar cada evento de webhook exactamente una vez, usando su id único. Como la entrega puede reintentarse, tu handler debería ignorar un id de evento que ya haya procesado.
Polling
Llamar repetidamente a la API para comprobar si algo está listo, en vez de dejar que un Webhook te avise. Desaconsejado en producción — genera muchas peticiones “vacías” y añade latencia; si es inevitable, espacia las llamadas con backoff exponencial. Los webhooks son la alternativa recomendada.
Splitter
Una función que separa automáticamente un File multidocumento en Documents individuales, detectando los límites entre documentos con IA. Elimina la necesidad de dividir los archivos en lote manualmente.
Classifier
Una función que identifica automáticamente el tipo de un documento, asignando el Document Type correcto para que no tengas que indicarlo en la subida. Combinada con el Splitter, permite el procesamiento totalmente automático de lotes con documentos mezclados.