Multi-Document

Multi-Document

Envía hasta 10 archivos, convierte cada uno a Markdown y responde preguntas tipadas cruzando esos textos.

Multi-Document

Preguntar a varios documentos

Endpoint

POSThttps://claix.dev/multi-document

Envía hasta 10 archivos en una sola llamada, junto con las mismas preguntas tipadas que Consultar espacio. Cada archivo se convierte a Markdown y las respuestas se construyen cruzando esos textos. No hay schema_id y los archivos no tienen que estar guardados de antemano.

Los formatos admitidos son los mismos que Extracción → Markdown: PDF, Excel/CSV, Word y texto, HTML/XML, imágenes y audio. Si un archivo no se puede convertir, falla la petición entera y no se devuelve ninguna respuesta.

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.

1. Autenticación

Toda petición debe incluir tu API key. Es una credencial de servidor personal, distinta de cualquier token de sesión, 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 los archivos, 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 los archivos.

2. Formato de la petición

Método: POST · Content-Type: multipart/form-data

CampoTipoObligatorioDescripción
fileArchivo binarioSíRepite el campo de 1 a 10 veces. También se aceptan files y documents. Mismos formatos y límites de tamaño que Extracción → Markdown.
questionsTexto JSONSíArray de { question, format }. Máximo 5 preguntas, 400 caracteres cada una. format: string | int | boolean | timestamp | array.
window_contextBooleanoNotrue conserva cada documento convertido. Si no viene, o es false, solo se responden las preguntas.
window_timeNúmero o textoObligatorio si window_context es trueMinutos: 5, 10, 15, 30, 45, 60, 90, 120, 180, 240, 360, 480, 720, 1440, o infinity. infinity exige el modo persistente activo en la cuenta.
space_idTexto (UUID)NoEspacio de conocimiento del dueño de la API key. Solo si window_context es true. Los documentos conservados se asocian a ese espacio.

3. Cómo construir la llamada

  1. Ten a mano tu API key. No necesitas schema_id.
  2. Construye un POST a la URL del endpoint.
  3. Añade el header de autenticación.
  4. Envía multipart/form-data con 1 a 10 campos file y un JSON questions.
  5. Para conservar los documentos, envía también window_context=true y window_time. space_id es opcional y solo aplica en ese caso.
  6. Comprueba el código HTTP: solo 200 indica éxito. Después lee ia_response.

4. Ejemplos de llamada

Consulta el panel de la derecha para ver ejemplos en cURL, JavaScript, Node.js, Python, PHP y n8n. Puedes cambiar el lenguaje con el selector y copiar el código. «Conservar los documentos» añade window_context, window_time y space_id.

5. Formato de la respuesta exitosa

200 OK · Content-Type: application/json

Las respuestas quedan alineadas con las preguntas y usan el format pedido, o null si el dato no está en los archivos. Si la verificación de fuente está activada en la consulta a espacios de conocimiento, cada respuesta es { value, source }.

{
  "user_ask": [
  { "question": "¿Qué proveedor factura más en total?", "format": "string" },
  { "question": "¿El importe del contrato coincide con la factura?", "format": "boolean" }
],
  "ia_response": [
    "Suministros Omega S.A.",
    true
  ],
  "documents_processed": 2,
  "log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}

Si window_context es true, los archivos convertidos se conservan y sus ids aparecen en esa llamada dentro del panel de logs. No son un campo extra de este JSON. Si no los conservas, el panel indica que no se guardaron.

CampoTipoDescripción
user_askarrayLas preguntas respondidas, en el mismo orden en que se enviaron.
ia_responsearrayUna respuesta por pregunta, en el format pedido, o null si los archivos no contienen el dato.
documents_processednumberCuántos archivos se convirtieron y se usaron para responder.
log_idstring (UUID)Identifica la llamada en el panel de logs.

6. Códigos de error

{
  "error": "Descripción legible del problema.",
  "detalle": "Información técnica adicional (solo presente en algunos casos).",
  "log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}

400 — Falta questions, está vacío, tiene más de 5 ítems, una pregunta supera 400 caracteres, o un format no es string, int, boolean, timestamp o array. También: no hay archivos, hay más de 10, un formato no está soportado, window_time no es válido, space_id llega sin window_context, o infinity llega sin el modo persistente activo.

401 — Autenticación fallida: key ausente, inexistente, desactivada o cuenta suspendida.

404 — space_id no existe en esta cuenta.

413 — Un archivo supera el límite de tamaño de su formato.

422 — Un archivo no pudo convertirse en Markdown legible. Falla la petición entera.

502 — Fallo del servicio de IA (transitorio; reintenta con backoff).

405 — Método distinto de POST. · 500 — Error interno.

7. Resumen de códigos

CódigoCategoría¿Reintentar?
200Éxito—
400Error del cliente (documento o datos mal formados)No, corrige la petición primero
401Error de autenticaciónNo, corrige las credenciales primero
404Recurso no encontradoNo, corrige el schema_id primero
405Método HTTP incorrectoNo, corrige el método primero
413Archivo o texto extraído demasiado grandeNo, reduce el tamaño primero
422Sin datos extraíblesNo, revisa el documento/schema primero
500Error interno del servidorSí, con precaución
502Fallo del servicio de IASí, recomendado con backoff

8. Buenas prácticas

  • Valida el código HTTP antes de leer ia_response.
  • No pases de 5 preguntas ni de 10 archivos. Una conversión fallida rechaza la llamada entera.
  • Los ids de los documentos conservados aparecen en el panel de logs solo si window_context es true. Si lo omites, los archivos no se guardan.
  • Reintenta automáticamente solo en 500 y 502, nunca en 4xx salvo cambios en la petición.
  • No incluyas tu API key en frontend ni repositorios públicos.

Ejemplos de petición

curl -X POST "https://claix.dev/multi-document" \
  -H "x-api-key: <TU_API_KEY>" \
  -F "file=@./factura.pdf" \
  -F "file=@./contrato.docx" \
  -F 'questions=[  { "question": "¿Qué proveedor factura más en total?", "format": "string" },  { "question": "¿El importe del contrato coincide con la factura?", "format": "boolean" }]'