Integrar Invofox

La integración esencial — el camino directo, de la subida al JSON.

Invofox es una sola API para extraer datos estructurados de PDFs e imágenes — envía cualquier documento (facturas, recibos, extractos bancarios, albaranes, contratos y muchos más, incluidos tipos de documento personalizados) y recibe JSON limpio y estructurado. Por dentro es una plataforma de procesamiento inteligente de documentos (IDP): OCR + IA que clasifican cada documento y extraen sus campos automáticamente — sin plantillas, sin introducción manual de datos.

Esta página es la integración esencial — el camino directo (“happy path”), de la subida al JSON. Para casos de uso, precisión y precios, consulta invofox.com →

¿Usas un agente de IA para programar? Conéctate al servidor MCP de Invofox para que tu agente pueda buscar en esta documentación en tiempo real. Integrar con un agente de IA →

Paso 1 — Consigue tu API key

Las API keys están vinculadas a un entorno. Para crear una:

  1. Inicia sesión en app.invofox.com y abre tu entorno — crea una cuenta gratis si aún no tienes una.
  2. Pulsa API y Webhooks en el menú de la izquierda.
  3. Crea una nueva API key y cópiala.

Paso 2 — Sube un documento

Envía tu archivo como multipart/form-data con un campo JSON info. La respuesta devuelve un documentId — es todo lo que necesitas. Referencia completa de la API →

POSThttps://api.invofox.com/v1/ingest/uploads
$curl -s -X POST "https://api.invofox.com/v1/ingest/uploads" \
>  -H "x-api-key: $INVOFOX_API_KEY" \
>  -F "files=@invoice.pdf" \
>  -F 'info={"type":"<TYPE_ID>","clientData":{"internalId":"inv-1234"}}'

El campo info

CampoTipoObligatorioDescripción
typestringObligatorioEl Document Type a extraer — su id o alias. Lo encuentras en Invofox → Document Types. *
clientDataobjectOpcionalCualquier objeto JSON que quieras que Invofox guarde y devuelva junto al documento — tanto en la respuesta del GET como en el payload del webhook. Útil para llevar tus propios identificadores: {"internalId": "inv-1234"}.
Dónde encontrar los IDs de Document Type
  • Abre Document Types en el menú de la izquierda de Invofox.
  • Cada Document Type muestra una tarjeta con su id y su alias.
  • Usa el alias si lo tiene; si no, usa el id.
  • ¿Necesitas un Document Type que no está? Invofox puede definir Document Types personalizados para tu caso — escribe a support@invofox.com.

Respuesta de la subida

La subida devuelve inmediatamente un documentId — no los datos extraídos. Invofox procesa el documento de forma asíncrona. Guarda el documentId de files[0] y úsalo en el Paso 3 para recuperar los resultados.

Respuesta de la subida
1{
2  "accountId": "666839c78ea472012a9b8875",
3  "environmentId": "6a338e5239207f9311eccd36",
4  "importId": "6a34a304f55a9cdc5e6d1c76",
5  "files": [
6    {
7      "id": "6a34a304f55a9cdc5e6d1c79",
8      "filename": "invoice.pdf",
9      "documentId": "6a34a304f55a9cdc5e6d1c7a"   // ← guarda esto
10    }
11  ]
12}

Paso 3 — Obtén los datos extraídos

El procesamiento es asíncrono. Los webhooks son la opción recomendada; el polling vale para pruebas rápidas y prototipos.

Opción A · Webhooks (Recomendado)

Invofox envía un evento document.processed a tu servidor cuando la extracción termina. Orientado a eventos, sin sobrecarga de polling. Recomendado para todas las integraciones en producción.

Opción B · Polling

Sin infraestructura — ideal para prototipos y pruebas rápidas. No recomendado para producción.

Opción A · Webhooks (recomendado para producción)

En Invofox, abre tu entorno y ve a API y Webhooks → Webhooks para añadir la URL de tu endpoint. Tu servidor recibirá entonces un evento document.processed en cuanto termine la extracción.

Para la lista completa de eventos y sus esquemas de payload (más firma y verificación), consulta la Referencia de Webhooks →. El ejemplo de abajo muestra un payload document.processed.

payload document.processed
1{
2  "type": "document.processed",
3  "version": "1.2",
4  "timestamp": 1781834535319,
5  "url": "",
6  "data": {                                // ← aquí vive el documento (no bajo "result" como en el GET); sin flags de permisos
7    "_id": "6a34a304f55a9cdc5e6d1c7a",
8    "clientData": { "internalId": "inv-1234" },   // ← el mismo clientData que enviaste en la subida
9    "type": "6a338ee0fdcde8d97ac96784",           // ← el id del Document Type (o su alias, si lo tiene)
10    "name": "invoice.pdf",
11    "publicState": "approved",
12    "confidence": "high",
13    "pageCount": 1,
14    "images": [
15      "https://storage.invofox.com/documents/6a34a304f55a9cdc5e6d1c7a/page-1.jpeg?token=..."
16    ],
17    "original": "https://storage.invofox.com/documents/6a34a304f55a9cdc5e6d1c7a/original.pdf?token=...",
18    "data": {                              // ← campos extraídos en data.data.<campo>
19      "receiptNumber":  { "value": "A16030202" },
20      "issueDate":      { "value": "2023-12-04" },
21      "subtotalAmount": { "value": 31.32 },
22      "taxAmount":      { "value": 0 },
23      "totalAmount":    { "value": 31.32 },
24      "paymentMethod":  { "value": "Transferencia bancaria" },
25      "merchant":       { "name": { "value": "Invofox Inc" } },
26      "items": [
27        { "description": { "value": "Permanente Sharpie" }, "quantity": { "value": 1 }, "unitPrice": { "value": 2.1 }, "totalAmount": { "value": 2.1 } }
28      ]
29    }
30  }
31}

Un archivo también puede fallar antes de producir ningún documento (protegido con contraseña, corrupto, formato no soportado). Escucha el webhook file.rejected para no esperar eternamente un documento que nunca llegará — esto aplica tanto si usas webhooks como polling. Consulta Archivos rechazados.

Opción B · Polling

Haz polling a GET /documents/{documentId} con backoff exponencial (empieza en 5 s, duplica en cada reintento). El endpoint puede devolver 404 durante los primeros segundos — es lo esperado, sigue haciendo polling. Para cuando recibas un 200 con publicState en approved, pendingCorrection o discarded.

GEThttps://api.invofox.com/documents/{documentId}

Los campos de la respuesta final viven bajo result.data. El ejemplo de abajo es ilustrativo.

El conjunto de campos lo define el Document Type configurado en tu entorno — no es fijo. La estructura siempre es la misma: cada campo es un objeto { "value": ... }, que puede anidarse, con arrays para las líneas. Para ver los campos exactos de tu Document Type, consulta Document Types en el panel o procesa un documento de ejemplo.

GET /documents/{documentId}
1{
2  "canEdit": true, "canComment": false, "canLock": true, "canAction": true,   // ← flags de permisos (no están en el webhook)
3  "result": {
4    "_id": "6a34a304f55a9cdc5e6d1c7a",
5    "clientData": { "internalId": "inv-1234" },   // ← tu clientData, devuelto sin cambios
6    "type": "6a338ee0fdcde8d97ac96784",           // ← el id del Document Type (o su alias, si lo tiene)
7    "name": "invoice.pdf",
8    "publicState": "approved",
9    "confidence": "high",
10    "pageCount": 1,
11    "images": [
12      "https://storage.invofox.com/documents/6a34a304f55a9cdc5e6d1c7a/page-1.jpeg?token=..."
13    ],
14    "original": "https://storage.invofox.com/documents/6a34a304f55a9cdc5e6d1c7a/original.pdf?token=...",
15    "data": {                              // ← campos extraídos en result.data.<campo>
16      "receiptNumber":  { "value": "A16030202" },
17      "issueDate":      { "value": "2023-12-04" },
18      "subtotalAmount": { "value": 31.32 },
19      "taxAmount":      { "value": 0 },
20      "totalAmount":    { "value": 31.32 },
21      "paymentMethod":  { "value": "Transferencia bancaria" },
22      "merchant":       { "name": { "value": "Invofox Inc" } },
23      "items": [
24        { "description": { "value": "Permanente Sharpie" }, "quantity": { "value": 1 }, "unitPrice": { "value": 2.1 }, "totalAmount": { "value": 2.1 } }
25      ]
26    }
27  }
28}

Pasos opcionales adicionales

Envía feedback sobre los valores extraídos

Si un valor extraído falta o es incorrecto, puedes devolver el valor correcto vía PUT /documents/{id}. Cada corrección alimenta directamente el entrenamiento del modelo, mejorando la precisión de extracción con el tiempo — automáticamente, sin configuración extra. Consulta la página Bucle de feedback para la referencia completa.

Funciones adicionales

La integración esencial está completa. Estas funciones están disponibles si tu caso de uso las requiere:

Bucle de feedback

Devuelve las correcciones humanas a la API para cerrar el ciclo de revisión.

Splitter

Sube un PDF que contiene varios documentos y recíbelos por separado, automáticamente.

Classifier

Olvídate de indicar el tipo de documento — Invofox lo detecta automáticamente.