Claix

Conversión de Excel / CSV a JSON

Endpoint

POST https://claix.dev/api/excel-json

Este endpoint acepta un archivo tabular (.xlsx o .csv) y lo devuelve transformado en JSON con la estructura exacta que definas mediante un esquema. Las columnas del archivo no necesitan coincidir literalmente con los nombres de las propiedades del esquema: el sistema reconoce automáticamente sinónimos, abreviaturas, traducciones y variantes.

Está pensado para integraciones de servidor a servidor (backends, scripts, n8n/Zapier/Make). No debe llamarse desde el navegador de un usuario final porque requiere una clave API secreta.

1. Autenticación

Cada solicitud debe incluir tu clave API. Es una credencial personal del servidor, 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 — Cabecera dedicada (recomendada):

x-api-key: <YOUR_API_KEY>

Opción B — Cabecera estándar de Authorization:

Authorization: Bearer <YOUR_API_KEY>

Cualquiera de las dos es suficiente. Si envías ambas, x-api-key tiene prioridad.

Antes de procesar el archivo, el sistema valida que:

• La clave API existe y está activa.
• La cuenta asociada está activa (no suspendida).

Si la validación falla, la solicitud se rechaza con 401 sin procesar el archivo.

2. Formato de la solicitud

Campo	Tipo	Obligatorio	Descripción
file	Archivo binario	Sí	Excel (.xlsx) o CSV (.csv). Debe ser el archivo en sí, no una ruta ni una URL.
schema_id	Texto (UUID)	Sí	Identificador del esquema excel-json creado en tu cuenta.
space_id	Texto (UUID)	No	Opcional. Espacio de conocimiento al que se adjunta el documento almacenado. Debe pertenecer a la misma cuenta que la clave API. Solo tiene efecto cuando el esquema tiene habilitada la ventana de contexto, que es cuando se almacena el documento. Entonces puedes consultar todo el espacio con POST /space-context/{space_id}.

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

Los nombres de los campos deben ser exactamente file y schema_id. El esquema debe ser del tipo Excel → JSON; si envías uno del tipo opuesto, recibirás 400.

Requisitos del archivo:

• Formatos: .xlsx, .csv.
• Al menos una fila de encabezado y una fila de datos.
• Si hay varias hojas, solo se procesa la primera.

3. Cómo construir la solicitud

1. Ten lista tu clave API y el schema_id correcto.
2. Construye una solicitud POST a la URL del endpoint.
3. Añade la cabecera de autenticación.
4. Envía multipart/form-data con file y schema_id.
5. Comprueba el código de estado HTTP: solo 200 indica éxito.

4. Ejemplos de solicitud

Consulta el panel de la derecha para ver ejemplos en cURL, JavaScript, Node.js, Python, PHP y n8n. Puedes cambiar de idioma con el selector de la parte superior y copiar el código directamente.

5. Formato de respuesta correcta

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	booleano	Siempre true cuando HTTP es 200.
schema_utilizado	cadena	Nombre del esquema aplicado (no el id).
total_filas_procesadas	número	Filas transformadas en data (las filas vacías no se cuentan).
mapa_columnas	objeto	Mapeo de columna original → propiedad del esquema.
data	matriz	Registros con claves que coinciden con las propiedades del esquema. Si la verificación de origen está habilitada en el esquema, cada propiedad es { value, source }.
log_id	cadena (UUID)	UUID de la fila usage_logs de esta llamada. Presente en caso de éxito y en la mayoría de errores autenticados.

Toda respuesta incluye log_id (el UUID de la fila usage_logs) cuando el registro pudo almacenarse. También aparece en la mayoría de errores después de que la solicitud se autentique. Úsalo para encontrar la llamada en el panel de registros.

Si la verificación de origen está habilitada en el esquema, cada propiedad extraída (y cada campo agent_data en modo Agente) se convierte en { "value": ..., "source": "..." } en lugar de un valor simple. source es obligatorio: cita la evidencia (página, párrafo, celda, fragmento citado, región de imagen o el segundo / rango de segundos en audio). Si no hay evidencia, source es exactamente requires_human_revision. Si la verificación de origen está desactivada, el formato no cambia.

Ejemplo con verificación de origen habilitada:

{
  "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 — Solicitud no válida: falta el archivo o schema_id, multipart incorrecto, archivo corrupto, sin filas de datos o esquema de tipo incorrecto.

401 — Error de autenticación: clave faltante, inexistente, desactivada o cuenta suspendida.

404 — schema_id no existe o no pertenece a tu cuenta.

422 — Archivo leído pero sin coincidencias con el esquema.

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

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

8. Buenas prácticas

• Valida el código de estado HTTP antes de leer los datos.
• Solo aparecen las columnas con una coincidencia real en el esquema.
• Reintenta automáticamente solo en 500 y 502, nunca en 4xx a menos que la solicitud cambie.
• Guarda mapa_columnas para trazabilidad durante las pruebas.
• No incluyas tu clave API en código de frontend ni en repositorios públicos.