Excel/CSV → Markdown
Excel o CSV a Markdown
Endpoint
https://claix.dev/api/excel-markdownConvierte 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
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| file | Archivo binario | Sí | .xlsx y .csv. Si hay varias hojas, solo se procesa la primera. Hace falta al menos una fila de encabezados y una de datos. |
| save | Booleano | No | true 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
- Ten a mano tu API key. No necesitas schema_id.
- Construye un POST a la URL del endpoint.
- Añade el header de autenticación.
- Envía
multipart/form-dataconfile. - Para guardar la fila, envía también
save=true. Hacen falta reglas activas de Markdown.save=falseno inserta. - 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"
}| Campo | Tipo | Descripción |
|---|---|---|
| success | boolean | Siempre true cuando el HTTP es 200. |
| markdown | string | El documento convertido. |
| row_id | string, opcional | Solo aparece si save es true. Id de la fila insertada en la base conectada. |
| log_id | string (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ódigo | Categoría | ¿Reintentar? |
|---|---|---|
| 200 | Éxito | — |
| 400 | Error del cliente (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 |
| 422 | Sin correspondencias encontradas | No, revisa los datos/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 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.