Excel-to-JSON
Conversión de Excel / CSV a JSON
Endpoint
https://claix.dev/api/excel-jsonEste endpoint recibe un archivo tabular (.xlsx o .csv) y lo devuelve transformado en JSON con la estructura exacta que definas mediante un schema. No necesitas que las columnas del archivo coincidan literalmente con los nombres del schema: el sistema reconoce sinónimos, abreviaturas, traducciones y variantes de forma automática.
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í | Excel (.xlsx) o CSV (.csv). Debe ser el archivo en sí, no una ruta ni URL. |
| schema_id | Texto (UUID) | Sí | Identificador del schema de tipo excel-json creado en tu cuenta. |
| space_id | Texto (UUID) | No | Opcional. Espacio de conocimiento al que se asocia el documento guardado. Debe pertenecer a la misma cuenta que la API key. Solo tiene efecto si el schema tiene la ventana de contexto activada, que es cuando el documento se guarda. Después puedes preguntar a todo el espacio con POST /space-context/{space_id}. |
Método: POST · Content-Type: multipart/form-data
Los nombres de campo deben ser exactamente file y schema_id. El schema debe ser del tipo Excel → JSON; si envías uno del tipo contrario, recibirás 400.
Requisitos del archivo:
- Formatos: .xlsx, .csv.
- Al menos una fila de encabezados y una de datos.
- Si hay varias hojas, se procesa solo la primera.
3. Cómo construir la llamada
- Ten a mano tu API key y el schema_id correcto.
- Construye un POST a la URL del endpoint.
- Añade el header de autenticación.
- Envía
multipart/form-dataconfileyschema_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. Puedes cambiar el lenguaje con el selector superior y copiar el código directamente.
5. Formato de la respuesta exitosa
200 OK · Content-Type: application/json
{
"success": true,
"schema_utilizado": "Leads de Ventas",
"total_filas_procesadas": 247,
"mapa_columnas": {
"Nom_cliente": "nombre_completo",
"Tlf": "telefono_movil",
"mail de contacto": "email_contacto"
},
"data": [
{
"nombre_completo": "Ana María Gómez",
"cargo": "CEO & Founder",
"empresa": "TechSolutions",
"email_contacto": "ana.gomez@techsolutions.com",
"telefono_movil": "+1 (555) 019-2231"
}
],
"log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34"
}| Campo | Tipo | Descripción |
|---|---|---|
| success | boolean | Siempre true cuando el HTTP es 200. |
| schema_utilizado | string | Nombre del schema aplicado (no el id). |
| total_filas_procesadas | number | Filas transformadas en data (sin contar filas vacías). |
| mapa_columnas | objeto | Emparejamiento columna original → propiedad del schema. |
| data | array | Registros con claves iguales a las propiedades del schema. Si la verificación de fuente está activa en el schema, cada propiedad es { value, source }. |
| log_id | string (UUID) | Identificador del registro en usage_logs de esta llamada. Presente en éxito y en la mayoría de errores autenticados. |
Toda respuesta incluye log_id (UUID de usage_logs) cuando el registro se ha podido guardar. También aparece en la mayoría de errores una vez autenticada la petición. Úsalo para localizar la llamada en el panel de logs.
Si la verificación de fuente está activada en el schema, cada propiedad extraída (y cada campo de agent_data en modo agente) deja de ser un valor plano y pasa a { "value": ..., "source": "..." }. source es obligatorio: cita la evidencia (página, párrafo, celda, fragmento, zona de la imagen, o el segundo / rango de segundos en audio). Si no hay evidencia, source vale exactamente requires_human_revision. Si la verificación de fuente está desactivada, el formato no cambia.
Ejemplo con verificación de fuente activada:
{
"success": true,
"schema_utilizado": "Leads de Ventas",
"total_filas_procesadas": 1,
"log_id": "7c2e1a90-4b3d-4f8a-9e21-6d5c8b0a1f34",
"mapa_columnas": {
"Nom_cliente": "nombre_completo",
"Tlf": "telefono_movil"
},
"data": [
{
"nombre_completo": {
"value": "Ana María Gómez",
"source": "columna \"Nom_cliente\", fila 2"
},
"telefono_movil": {
"value": "+1 (555) 019-2231",
"source": "columna \"Tlf\", fila 2"
}
}
]
}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 — Petición inválida: falta file o schema_id, multipart incorrecto, archivo corrupto, sin filas de datos, o schema de tipo incorrecto.
401 — Autenticación fallida: key ausente, inexistente, desactivada o cuenta suspendida.
404 — schema_id inexistente o no pertenece a tu cuenta.
422 — Archivo leído pero sin correspondencias con el schema.
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ó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 data.
- Solo aparecen columnas con correspondencia real en el schema.
- Reintenta automáticamente solo en 500 y 502, nunca en 4xx salvo cambios en la petición.
- Guarda
mapa_columnaspara trazabilidad durante pruebas. - No incluyas tu API key en frontend ni repositorios públicos.