PDF-to-JSON
Extracción de datos de PDF a JSON
Endpoint
https://www.claix.dev/api/pdf-jsonEste 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": "Facturas de Proveedores",
"total_registros": 1,
"data": [
{
"numero_factura": "F-2026-00456",
"fecha_emision": "2026-03-14",
"proveedor": "Suministros Industriales del Ebro S.L.",
"importe_total": 1284.50,
"moneda": "EUR"
}
]
}| Campo | Tipo | Descripción |
|---|---|---|
| success | boolean | Siempre true cuando el HTTP es 200. |
| schema_utilizado | string | Nombre del schema aplicado (no el id). |
| total_registros | number | Siempre 1: un documento = un registro extraído. |
| data | array | Contiene exactamente un objeto con las propiedades del schema. Valores no encontrados son null. |
Si una propiedad del schema representa una lista (p. ej. líneas de factura), las instancias se agrupan en un array. Si el schema espera un valor único pero hay varias instancias, se extrae la más relevante.
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.