Claix

1. Autenticación

Cada solicitud debe incluir tu clave de 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 — Encabezado dedicado (recomendado):

x-api-key: <YOUR_API_KEY>

Opción B — Encabezado de autorización estándar:

Authorization: Bearer <YOUR_API_KEY>

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

Antes de procesar el archivo, el sistema valida que:

• La clave de 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 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.

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 tu clave de API y el schema_id correcto listos.
2. Construye una solicitud POST a la URL del endpoint.
3. Añade el encabezado 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 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" } ] }

Campo	Tipo	Descripción
success	booleano	Siempre true cuando HTTP es 200.
schema_utilizado	string	Nombre del esquema aplicado (no el id).
total_filas_procesadas	number	Filas transformadas en data (las filas vacías no se cuentan).
mapa_columnas	object	Mapeo de columna original → propiedad del esquema.
data	array	Registros con claves que coinciden con las propiedades del esquema.

6. Códigos de error

{ "error": "Descripción legible del problema.", "detalle": "Información técnica adicional (solo presente en algunos casos)." }

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; reintentar 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 de cliente (datos malformados)	No — corrige la solicitud primero
401	Error de autenticación	No — corrige las credenciales primero
404	Recurso no encontrado	No — corrige schema_id primero
405	Método HTTP incorrecto	No — corrige el método primero
422	Sin coincidencias encontradas	No — revisa datos/esquema 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 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 de API en código frontend ni en repositorios públicos.

Ejemplos de solicitud

cURLJavaScriptNode.jsPythonPHPn8n

Copiar

curl -X POST "https://www.claix.dev/api/excel-json"
-H "x-api-key: <TU_API_KEY>"
-F "file=@./leads_octubre.xlsx"
-F "schema_id=8f14e45f-ceea-4e6f-8b23-1e2d3c4b5a6f"