Excel-to-JSON · Modo agente
Excel / CSV a JSON con Modo agente
Endpoint
https://www.claix.dev/agent/excel-jsonModo agente activo
Este endpoint ejecuta primero la extracción estructurada del schema principal y después una fase de razonamiento con agent_definition. La respuesta incluye data[] (extracción) y agent_data (inferencia tipada). El schema debe tener is_agent_mode activado.
Este 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. |
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": "Inventario Q3",
"total_registros": 2,
"data": [
{ "sku": "SKU-001", "stock": 120, "precio": 19.99 },
{ "sku": "SKU-002", "stock": 45, "precio": 34.5 }
],
"agent_data": {
"stock_critico": true,
"productos_bajo_minimo": 1,
"resumen_inventario": "Un producto por debajo del umbral mínimo de stock."
}
}| Campo | Tipo | Descripción |
|---|---|---|
| success | boolean | Siempre true cuando el HTTP es 200. |
| schema_utilizado | string | Nombre del schema aplicado en la extracción. |
| total_registros | number | Número de registros en data. |
| data | array | Objetos extraídos según el schema principal (igual que en extracción). |
| agent_data | object | Respuestas tipadas del Modo Agente según agent_definition (booleanos, números, strings). |
6. Códigos de error
{
"error": "Descripción legible del problema.",
"detalle": "Información técnica adicional (solo presente en algunos casos)."
}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.