API y webhooks
La carga y lectura de documentos está disponible a través del API REST. La gestión de la cuenta, carpetas, etiquetas y conexiones permanece en la aplicación.
Clave
Se establece en Configuración → Para desarrolladores. La clave se muestra una vez, al ser creada — después ya no, porque sólo se guarda su huella. No se puede recuperar una clave perdida, se debe crear una nueva y se elimina la antigua. Se pueden tener cinco claves, cada una con un período de validez opcional de hasta dos años.
La clave se envía en la cabecera X-API-Key.
Qué puede hacer el API
| Operación | Descripción |
|---|---|
POST /api/upload | Carga de archivo con opciones: formato, dirección, tipo, moneda, esquema, carpeta, 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} | Eliminación a la papelera |
Excel y PDF llegan en el resultado como Base64. Quien no necesite el resultado, envía includeResult=false, ahorrando así la conversión en el servidor.
La descripción de la interfaz en formato OpenAPI está en la dirección /api/docs; el enlace está en la configuración junto a las claves. La descripción se genera a partir del código en ejecución, por lo que corresponde a lo que hace el API.
Control en los documentos del API
El control antes del envío aplica por defecto también a los documentos cargados con la clave: el documento espera confirmación en la aplicación y el webhook se enviará solo después de esto. Quien está construyendo una integración en la que nadie está frente a la pantalla, puede eliminar el canal API en Configuración → Control antes del envío o desactivar el control.
MCP
Para agentes de IA, en la dirección /api/mcp se encuentra el servidor MCP con la misma clave. Puede leer y buscar documentos, no cargar; la carga se devuelve como un comando listo, que el agente ejecutará por sí mismo.
Webhooks
En lugar de consultar el estado, reciba el resultado cuando esté listo. La dirección se configura para toda la cuenta en Configuración → Para desarrolladores, o para cada carga individual a través del parámetro targetWebhookUrl. El botón en la configuración envía un mensaje de prueba.
Se envía 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 de nuevo, se recibirá el webhook nuevamente con la bandera de corrección (IsCorrection).
El mensaje no se firma. Verifique el remitente añadiendo su propio token secreto a la dirección. Las direcciones a redes privadas son rechazadas.
La entrega fallida se repetirá con un aumento en la demora, once intentos durante aproximadamente cuatro horas y media. Cada intento está en la actividad junto con la respuesta de su parte; en el documento listado hay un ícono con el resultado de la entrega.
Límites
El API no tiene un límite propio en el número de llamadas por minuto; la carga está limitada por créditos, tamaño del archivo según la tarifa y un máximo de veinte páginas por documento. Las negativas se recibirán como error 400 con un código que indica la razón. El servidor MCP está limitado a diez consultas por segundo.