API y webhooks
La carga y lectura de documentos está disponible a través de la API REST. La gestión de cuentas, archivos, etiquetas y conexiones se mantiene en la aplicación.
Clave
Se crea en Configuración → Para desarrolladores. La clave se muestra una vez, al crearla; después ya no, ya que solo se guarda su huella. Una clave perdida no se puede recuperar, se debe crear una nueva y la antigua se elimina. Se pueden tener hasta cinco claves, cada una con una validez opcional de hasta dos años.
El propietario de la cuenta recibirá un correo electrónico sobre cada nueva clave, así como dos semanas antes de que la clave expire. Ver Notificaciones por correo electrónico.
La clave se envía en el encabezado X-API-Key.
Qué puede hacer la API
| Operación | Descripción |
|---|---|
POST /api/upload | Cargar un archivo con opciones: formato, dirección, tipo, moneda, esquema, archivo, webhook |
POST /api/upload/url | Lo mismo desde una dirección pública; descargamos el archivo nosotros mismos |
GET /api/jobs | Listado de documentos con filtros y paginación |
GET /api/jobs/{id} | Estado, datos leídos, hallazgos y resultado en el formato de destino |
GET /api/jobs/{id}/original | Archivo cargado |
DELETE /api/jobs/{id} | Eliminar a la papelera |
Excel y PDF se devuelven como Base64. Quien no necesite el resultado, puede enviar includeResult=false, ahorrando así la conversión en el servidor.
La descripción de la interfaz en formato OpenAPI se encuentra en la dirección /api/docs; el enlace está en la configuración de las claves. La descripción se genera a partir del código en ejecución, por lo que corresponde a lo que hace la API.
Control en los documentos de la API
El control antes del envío se aplica de forma predeterminada también a los documentos cargados con la clave: el documento espera la confirmación en la aplicación y el webhook solo se enviará después de esta. Quien esté construyendo una integración donde nadie esté frente a la pantalla, puede desactivar el canal API en Configuración → Control antes del envío, o desactivar la verificación.
MCP
Para agentes de IA, el servidor MCP está en /api/mcp con la misma clave. Puede leer y buscar documentos, no cargar; la carga devuelve como un comando completado que el agente ejecuta por su cuenta.
Webhooks
En lugar de consultar el estado, recibe el resultado cuando esté listo. La dirección se configura para toda la cuenta en Configuración → Para desarrolladores, o en cada carga individual mediante el parámetro targetWebhookUrl. Un botón en la configuración envía un mensaje de prueba.
Se enviará un POST con JSON: identificador del documento, nombre del archivo, formato y resultado en el formato de destino. Cuando el documento pasa la verificación o se procesa nuevamente, el webhook se enviará por segunda vez con el indicador de corrección (IsCorrection).
El mensaje no se firma. Verifique el remitente incluyendo su propio token secreto en la dirección. Las direcciones en redes privadas son rechazadas.
Si el webhook no llega después de todos los intentos, aproximadamente tras cuatro horas y media, se enviará un correo electrónico. Durante un solo fallo, solo una vez; los fracasos restantes se registran en la actividad. También se enviará un correo después de cada cambio en la dirección del webhook, si este fue modificado por alguien que no sea usted.
La entrega fallida se repetirá con un aumento en el intervalo, con once intentos durante aproximadamente cuatro horas y media. Cada intento está registrado en la actividad junto con la respuesta de su parte; en el documento en el listado hay un ícono con el resultado de la entrega.
Límites
La API no tiene un límite propio en el número de llamadas por minuto; las cargas están limitadas por créditos, el tamaño del archivo según la tarifa, y veinte páginas por documento. Una denegación se devuelve como un error 400 con un código que indica por qué. El servidor MCP está limitado a diez solicitudes por segundo.