PDF-to-JSON · Modo agente
PDF a JSON con Modo agente
Endpoint
https://www.claix.dev/agent/pdf-jsonModo agente activo
Este endpoint ejecuta primero la extracción estructurada del schema principal y después una fase de razonamiento con agent_definition. La respuesta incluye data[] (extracción) y agent_data (inferencia tipada). El schema debe tener is_agent_mode activado.
Este endpoint recibe un archivo PDF y devuelve un único objeto JSON con los datos extraídos del documento, siguiendo exactamente la estructura que definas mediante un schema. Funciona con PDFs de texto seleccionable y con PDFs escaneados, porque el análisis lo realiza un modelo de IA con comprensión nativa de documentos, no un extractor de texto plano.
Está pensado para integraciones server-to-server (backends, scripts, n8n/Zapier/Make). No debe llamarse desde el navegador de un usuario final porque requiere una API key secreta.
A diferencia de Excel/CSV, el PDF completo se trata como una única fuente de datos y la respuesta contiene exactamente un registro en data — ideal para facturas, contratos, formularios, certificados o informes.
1. Autenticación
Toda petición debe incluir tu API key. Es una credencial de servidor personal y debe tratarse con el mismo cuidado que una contraseña de base de datos.
Opción A — Header dedicado (recomendado):
x-api-key: <TU_API_KEY>
Opción B — Header estándar Authorization:
Authorization: Bearer <TU_API_KEY>
Con uno de los dos es suficiente. Si envías ambos, x-api-key tiene prioridad.
Antes de procesar el PDF, el sistema valida que:
- La API key exista y esté activa.
- La cuenta asociada esté activa (no suspendida).
Si falla, se rechaza con 401 sin procesar el archivo.
2. Formato de la petición
Método: POST · Content-Type: multipart/form-data (obligatorio)
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| file | Archivo binario | Sí | El PDF a analizar. Debe ser el archivo en sí, no una ruta ni URL. |
| schema_id | Texto (UUID) | Sí | Schema previamente creado en tu cuenta, del tipo PDF → JSON. |
Los nombres de campo deben ser exactamente file y schema_id. No se admiten alias como pdf, documento o upload.
El schema_id debe corresponder a un schema de tipo PDF → JSON. Si envías uno de Excel → JSON u otro tipo, recibirás 400.
Requisitos del archivo:
- Formato: .pdf únicamente (validado por MIME y extensión).
- No puede estar vacío (0 bytes).
- Tamaño máximo: 15 MB (error 413 si se supera).
- Compatible con PDFs de texto y escaneados.
3. Cómo construir la llamada
- Ten a mano tu API key y el schema_id del tipo correcto.
- Construye un POST a la URL del endpoint.
- Añade el header de autenticación.
- Envía
multipart/form-dataconfile(PDF) yschema_id. - Comprueba el código HTTP: solo 200 indica éxito.
4. Ejemplos de llamada
Consulta el panel de la derecha para ver ejemplos en cURL, JavaScript, Node.js, Python, PHP y n8n.
5. Formato de la respuesta exitosa
200 OK · Content-Type: application/json
{
"success": true,
"schema_utilizado": "Contratos",
"total_registros": 1,
"data": [
{
"puesto a ocupar": "Ing. Software Principal (Backend)",
"Nombre contratante": "Tech Solutions S.L.",
"fecha del contrato": "8 de Agosto de 2026",
"persona contratada": "Gael Anaya"
}
],
"agent_data": {
"salario": 55000,
"es_parcial": false,
"fecha_contrato": "después del 20/07/2026",
"resumen_contrato": "Contrato indefinido: Gael Anaya como Backend en Tech Solutions S.L. Jornada completa, 55.000 €/año."
}
}| Campo | Tipo | Descripción |
|---|---|---|
| success | boolean | Siempre true cuando el HTTP es 200. |
| schema_utilizado | string | Nombre del schema aplicado en la extracción. |
| total_registros | number | Número de registros en data. |
| data | array | Objetos extraídos según el schema principal (igual que en extracción). |
| agent_data | object | Respuestas tipadas del Modo Agente según agent_definition (booleanos, números, strings). |
6. Códigos de error
{
"error": "Descripción legible del problema.",
"detalle": "Información técnica adicional (solo presente en algunos casos)."
}400 — Falta file o schema_id, multipart inválido, no es PDF, archivo vacío, corrupto, o schema de tipo incorrecto.
401 — Autenticación fallida.
404 — schema_id inexistente o no pertenece a tu cuenta.
413 — PDF supera 15 MB.
422 — PDF leído pero sin datos extraíbles según el schema.
502 — Fallo del servicio de IA (transitorio).
405 — Método distinto de POST. · 500 — Error interno.
7. Resumen de códigos
| Código | Categoría | ¿Reintentar? |
|---|---|---|
| 200 | Éxito | — |
| 400 | Error del cliente (archivo o datos mal formados) | No, corrige la petición primero |
| 401 | Error de autenticación | No, corrige las credenciales primero |
| 404 | Recurso no encontrado | No, corrige el schema_id primero |
| 405 | Método HTTP incorrecto | No, corrige el método primero |
| 413 | PDF demasiado grande | No, reduce el tamaño del archivo primero |
| 422 | Sin datos extraíbles | No, revisa el PDF/schema primero |
| 500 | Error interno del servidor | Sí, con precaución |
| 502 | Fallo del servicio de IA | Sí, recomendado con backoff |
8. Buenas prácticas
- Valida el código HTTP antes de leer data[0].
- Comprueba el tamaño del PDF en tu cliente antes de enviarlo.
- Recuerda: data siempre tiene exactamente un elemento (un documento = un objeto).
- Reintenta automáticamente solo en 500 y 502, nunca en 400, 401, 404, 413 o 422.
- Descripciones claras en las propiedades del schema mejoran la precisión en documentos con layouts poco estandarizados.
- No incluyas tu API key en frontend ni repositorios públicos.