Documentación API

Extracción -> Markdown

Convierte archivos a Markdown. Sin schema. save=true opcional inserta la fila en la base conectada y devuelve row_id.

Excel/CSV → Markdown

Excel o CSV a Markdown

Endpoint

POSThttps://claix.dev/api/excel-markdown

Convierte la primera hoja de un .xlsx o .csv en una tabla Markdown. No usa schema ni llama a un modelo: el archivo se parsea en el servidor, igual que en Excel → JSON antes del mapeo de columnas.

No hay schema_id. El Markdown siempre se devuelve. Con save=true se inserta en la base conectada, según las reglas activas de Markdown, y la respuesta incluye row_id. Si omites save, o envías save=false, solo se devuelve el Markdown.

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 el archivo, 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

CampoTipoObligatorioDescripción
fileArchivo binarioSí.xlsx y .csv. Si hay varias hojas, solo se procesa la primera. Hace falta al menos una fila de encabezados y una de datos.
saveBooleanoNotrue inserta el Markdown en la base conectada y devuelve row_id. Si no viene, o es false, solo se devuelve el Markdown. space_id, window_time y window_context se rechazan.

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

Modelo: No. La tabla se construye en local.

No hay schema_id. Los nombres de campo tienen que coincidir exactamente con la tabla.

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 file.
  5. Para guardar la fila, envía también save=true. Hacen falta reglas activas de Markdown. save=false no inserta.
  6. 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. Puedes cambiar el lenguaje con el selector y copiar el código. «save=true» añade ese campo.

5. Formato de la respuesta exitosa

200 OK · Content-Type: application/json

Sin save:

{
  "success": true,
  "markdown": "# Contrato de suministro\n\nImporte: 12.400 €",
  "log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}

Con save=true, el mismo cuerpo incluye además row_id:

{
  "success": true,
  "markdown": "# Contrato de suministro\n\nImporte: 12.400 €",
  "row_id": "9b1e4c80-2a7d-4e11-8f33-0c6d5a4b2e18",
  "log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}
CampoTipoDescripción
successbooleanSiempre true cuando el HTTP es 200.
markdownstringEl documento convertido.
row_idstring, opcionalSolo aparece si save es true. Id de la fila insertada en la base conectada.
log_idstring (UUID)Identifica la llamada en el panel de logs. También aparece en la mayoría de errores una vez autenticada la petición.

6. Códigos de error

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

400 — Falta file, el multipart es incorrecto, el formato no es .xlsx ni .csv, la hoja no tiene filas de datos, save no es true ni false, o llegan space_id, window_time o window_context.

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

409 — La fila choca con una clave única. El cuerpo incluye code unique_conflict.

422 — El archivo se leyó, pero el Markdown resultante está vacío. Con save=true, este estado también indica que el insert se rechazó antes de escribir: no hay reglas activas de Markdown, no hay base conectada, o la tabla o columna de la regla no coincide. El cuerpo incluye error y code.

502 — Fallo del servicio de IA, o el insert fue rechazado. Si falla el insert, el cuerpo incluye error y code, y la fila no se guarda.

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

7. Resumen de códigos

CódigoCategoría¿Reintentar?
200Éxito—
400Error del cliente (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
422Sin correspondencias encontradasNo, revisa los datos/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 markdown.
  • row_id solo se devuelve si save es true. space_id, window_time y window_context se rechazan.
  • Si el libro tiene varias hojas, deja los datos en la primera.
  • 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/api/excel-markdown" \
  -H "x-api-key: <TU_API_KEY>" \
  -F "file=@./leads.xlsx"