JSON-to-Excel
JSON to Excel conversion
Endpoint
https://www.claix.dev/api/json-excelAccepts one or more JSON documents and returns a binary Excel (.xlsx) file, with columns in the order and names defined by your schema. JSON keys do not need to match literally: the system automatically recognizes synonyms and variants.
Server-to-server integration. Accepts file(s), text fields with JSON, or a pure application/json body.
1. Authentication
Same as Excel-to-JSON: send x-api-key or Authorization: Bearer. If authentication fails, it responds with 401 without processing data.
x-api-key: <YOUR_API_KEY>
2. Supported request formats
Form A — multipart/form-data (recommended with files)
| Field | Type | Required | Description |
|---|---|---|---|
| schema_id | Text (UUID) | Yes | Schema of type json-excel. |
| (any name) | File / text | Yes (≥1) | One or more fields with valid JSON (object or array). |
You can repeat the same field name for multiple files. Content from all fields is combined before generating the Excel file.
Form B — application/json
schema_id can go in the body, or in the URL:
POST https://www.claix.dev/api/json-excel?schema_id=<uuid>
Supported structures:
- Direct array of records
- A single object
- Envelope with schema_id + data (or records)
The schema must be of the JSON → Excel type. Empty data or invalid JSON → 400.
3. How to build the request
Multipart: POST + auth + schema_id + one or more JSON fields. A successful response is binary, not JSON.
Pure JSON: POST + auth + Content-Type application/json + body in one of the three forms. Treat the response as bytes/blob.
4. Request examples
The right panel contains examples for multipart and pure JSON in cURL, JavaScript, Node.js, Python, PHP, and n8n. Use the language selector to switch between them.
5. Successful response format
200 OK — binary response of the generated Excel file.
| Header | Value |
|---|---|
| Content-Type | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
| Content-Disposition | attachment; filename="<schema_name>.xlsx" |
Always check the HTTP status code: 200 = Excel binary; 4xx/5xx = JSON with an error field.
6. Error codes
{
"error": "Descripción legible del problema.",
"detalle": "Información técnica adicional (solo presente en algunos casos)."
}400 — No recognizable JSON, missing schema_id, invalid JSON, zero records, or schema of the wrong type.
401 — Authentication failed. · 404 — schema_id does not exist or belongs to another account.
422 — Data read but no matches with the schema. · 502 — AI service failure.
405 — Method ≠ POST. · 500 — Internal error.
7. Code summary
| Code | Category | Retry? |
|---|---|---|
| 200 | Success | — |
| 400 | Client error (malformed data) | No — fix the request first |
| 401 | Authentication error | No — fix credentials first |
| 404 | Resource not found | No — fix schema_id first |
| 405 | Incorrect HTTP method | No — fix the method first |
| 422 | No matches found | No — review data/schema first |
| 500 | Internal server error | Yes, with caution |
| 502 | AI service failure | Yes, recommended with backoff |
8. Best practices
- Check HTTP status before treating the response as binary or JSON.
- Set responseType/Response Format to binary (arraybuffer, blob, File).
- Retry only on 500 and 502.
- Do not normalize keys manually: the system reconciles variants.
- Do not expose your API key in frontend code or public repos.