JSON-to-Excel
Conversión de JSON a Excel
Endpoint
https://www.claix.dev/api/json-excelRecibe uno o varios documentos JSON y devuelve un archivo Excel (.xlsx) binario, con columnas en el orden y nombres definidos por tu schema. Las claves JSON no tienen que coincidir literalmente: el sistema reconoce sinónimos y variantes automáticamente.
Integración server-to-server. Acepta archivo(s), campos de texto con JSON, o cuerpo application/json puro.
1. Autenticación
Igual que Excel-to-JSON: envía x-api-key o Authorization: Bearer. Si falla, responde 401 sin procesar datos.
x-api-key: <TU_API_KEY>
2. Formatos de petición admitidos
Forma A — multipart/form-data (recomendado con archivos)
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| schema_id | Texto (UUID) | Sí | Schema de tipo json-excel. |
| (cualquier nombre) | Archivo / texto | Sí (≥1) | Uno o varios campos con JSON válido (objeto o array). |
Puedes repetir el mismo nombre de campo para varios archivos. El contenido de todos se combina antes de generar el Excel.
Forma B — application/json
El schema_id puede ir en el cuerpo, o en la URL:
POST https://www.claix.dev/api/json-excel?schema_id=<uuid>
Estructuras admitidas:
- Array directo de registros
- Un único objeto
- Sobre con schema_id + data (o records)
El schema debe ser del tipo JSON → Excel. Datos vacíos o JSON inválido → 400.
3. Cómo construir la llamada
Multipart: POST + auth + schema_id + uno o más campos JSON. La respuesta exitosa es binaria, no JSON.
JSON puro: POST + auth + Content-Type application/json + cuerpo en una de las tres formas. Trata la respuesta como bytes/blob.
4. Ejemplos de llamada
En el panel derecho encontrarás ejemplos para multipart y JSON puro en cURL, JavaScript, Node.js, Python, PHP y n8n. Usa el selector de lenguaje para alternar entre ellos.
5. Formato de la respuesta exitosa
200 OK — respuesta binaria del Excel generado.
| Header | Valor |
|---|---|
| Content-Type | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
| Content-Disposition | attachment; filename="<nombre_del_schema>.xlsx" |
Comprueba siempre el código HTTP: 200 = binario Excel; 4xx/5xx = JSON con campo error.
6. Códigos de error
{
"error": "Descripción legible del problema.",
"detalle": "Información técnica adicional (solo presente en algunos casos)."
}400 — Sin JSON reconocible, schema_id ausente, JSON inválido, cero registros, o schema de tipo incorrecto.
401 — Autenticación fallida. · 404 — schema_id inexistente o de otra cuenta.
422 — Datos leídos pero sin correspondencias con el schema. · 502 — Fallo del servicio de IA.
405 — Método ≠ 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
- Comprueba el HTTP antes de tratar la respuesta como binario o JSON.
- Configura responseType/Response Format como binario (arraybuffer, blob, File).
- Reintenta solo en 500 y 502.
- No homogeneices claves manualmente: el sistema reconcilia variantes.
- No expongas tu API key en frontend ni repos públicos.