Toda petición debe incluir tu API key. Es una credencial de servidor personal, distinta de cualquier token de sesión de usuario, y debe tratarse con el mismo cuidado que una contraseña de base de datos.

Puedes enviarla de dos formas, ambas válidas y equivalentes:

Opción A — Header dedicado (recomendado):

x-api-key: <TU_API_KEY>

Opción B — Header estándar Authorization:

Authorization: Bearer <TU_API_KEY>

No es necesario enviar ambos headers a la vez; con uno de los dos es suficiente. Si envías los dos, el header x-api-key tiene prioridad.

Qué ocurre si la autenticación falla

Antes de procesar cualquier archivo, el sistema valida:

• Que la API key exista y esté activa.
• Que la cuenta asociada a esa API key esté en estado activo (no suspendida).

Si cualquiera de estas comprobaciones falla, la petición se rechaza inmediatamente con código 401, sin llegar a procesar el documento adjunto.

Método HTTP: POST

Content-Type: multipart/form-data (obligatorio)

La petición debe construirse como un formulario multipart (el mismo tipo que al subir un archivo desde un <form> HTML con enctype="multipart/form-data", o al usar FormData en JavaScript, multipart/form-data en Python requests, o un body de tipo Form-Data en Postman/n8n/Insomnia).

Campos que debe contener el formulario

No se admiten campos adicionales con otros nombres para el archivo (por ejemplo, documento, doc, upload) — el nombre de campo debe ser exactamente file, y el del identificador del schema exactamente schema_id.

Requisito importante sobre el schema

El schema_id debe corresponder a un schema configurado específicamente para extracción de documento a JSON. Si envías el identificador de un schema pensado para otra dirección de conversión (por ejemplo, Excel a JSON o PDF a JSON), la petición será rechazada con un error 400, sin llegar a procesar el archivo.

Formatos de archivo admitidos

Formato explícitamente NO soportado: .doc (Word 97-2003, formato binario legacy). Si envías un archivo de este tipo (application/msword, o extensión .doc), la petición se rechaza con 400 y un mensaje pidiendo convertirlo a .docx primero.

Si el tipo MIME del archivo no coincide exactamente con la tabla (algunos clientes envían tipos genéricos como application/octet-stream), el sistema también revisa la extensión del nombre de archivo como respaldo.

Requisitos del archivo

• El archivo no puede estar vacío (0 bytes).
• Tamaño máximo admitido: 10 MB. Si envías un archivo más pesado, la petición se rechaza con código 413 antes de intentar procesarlo.
• El texto extraído del documento no puede superar los 300.000 caracteres. Este es un límite independiente del tamaño del archivo original. Si se supera, la petición se rechaza con 413 después de la extracción pero antes de llamar a la IA.
• El documento debe contener texto extraíble. Un documento vacío, o compuesto únicamente de imágenes sin texto, será rechazado.

1. Ten a mano tu API key.
2. Ten a mano el schema_id del schema correspondiente (creado previamente en tu cuenta, del tipo correcto para este endpoint).
3. Construye una petición POST a la URL del endpoint.
4. Añade el header de autenticación (x-api-key o Authorization: Bearer).
5. Construye el cuerpo como multipart/form-data con dos partes: una parte de tipo archivo con nombre de campo file, y una parte de tipo texto con nombre de campo schema_id conteniendo el UUID como string.
6. Envía la petición y espera la respuesta.
7. Comprueba el código de estado HTTP antes de asumir éxito: solo 200 indica que el documento se procesó correctamente.

Consulta el panel de la derecha para ver ejemplos en cURL, JavaScript, Node.js, Python, PHP y n8n.

200 OK · Content-Type: application/json

{
  "success": true,
  "schema_utilizado": "Contratos legales",
  "total_registros": 1,
  "data": [
    {
      "parte_a": "Inmobiliaria Norte S.L.",
      "parte_b": "Carlos Méndez",
      "fecha_firma": "2026-03-01"
    }
  ],
  "agent_data": {
    "clausula_penalizacion": true,
    "tipo_renovacion": "automatica",
    "resumen_contrato": "Arrendamiento con renovación automática y cláusula de penalización por impago."
  }
}

Toda respuesta de error es JSON, con al menos un campo error con un mensaje legible. Algunos errores incluyen además un campo detalle con información técnica adicional.

{
  "error": "Descripción legible del problema.",
  "detalle": "Información técnica adicional (solo presente en algunos casos)."
}

400 — Petición inválida

Casos concretos:

• No se envió el campo file, o no es un archivo válido.
• No se envió el campo schema_id.
• El body no pudo interpretarse como multipart/form-data.
• El archivo está vacío (0 bytes).
• El formato del archivo no está entre los soportados (.docx, .txt, .md, .rtf).
• Se envió un archivo .doc (formato legacy de Word 97-2003) — mensaje específico pidiendo convertirlo a .docx.
• El .docx está corrupto o no se pudo abrir como ZIP válido.
• El .docx no contiene la estructura interna esperada (word/document.xml).
• No se pudo extraer ningún texto del documento (documento vacío de contenido, o solo con imágenes).
• El schema indicado en schema_id no es del tipo correcto para este endpoint.

401 — No autorizado — API key ausente, inexistente, desactivada, o cuenta no activa.

404 — No encontrado — El schema_id no existe o no pertenece a la cuenta de tu API key.

413 — Archivo o texto demasiado grande — El archivo supera 10 MB, o el texto extraído supera 300.000 caracteres.

422 — No procesable — El texto se extrajo correctamente pero no se pudo extraer ningún dato relacionado con tu schema.

502 — Fallo del servicio de procesamiento — Problema de comunicación con el servicio de IA (transitorio; reintentar con backoff).

405 — Método no permitido — Método HTTP distinto de POST.

500 — Error interno — Problema no esperado del lado del servidor.

• Valida el código de estado HTTP antes de intentar leer data[0] de la respuesta; un error 4xx o 5xx no tendrá esa estructura.
• Prefiere .docx o .txt sobre .rtf cuando tengas la opción: la extracción de estos dos primeros formatos es más fiable que la del .rtf.
• Si generas los documentos tú mismo desde otro sistema, considera exportar directamente a .txt o .md cuando el layout visual no importe.
• Recuerda que data siempre contiene exactamente un elemento en este endpoint — uno por documento completo, no por página ni por sección.
• Implementa reintentos automáticos únicamente para los códigos 500 y 502, nunca para 400, 401, 404, 413 o 422.
• Cuanto más claras sean las descripciones de las propiedades de tu schema, mejor será la precisión de la extracción.
• No incluyas tu API key en código de frontend ni en repositorios públicos.