---
seo_title: API JSON a CSV | Convertir arrays JSON a CSV | EnConvert
meta_desc: Convierte JSON a CSV con POST /v1/convert/json-to-csv. Requiere un array JSON de objetos; cabeceras desde las claves del primer objeto. Salida delimitada por comas.
keywords: json a csv api, convertir json a csv api, api rest json a csv, array json a csv, exportar json como csv api, json a csv online api, endpoint json a csv, aplanar json a csv api
---

# API de JSON a CSV

Convierte un archivo JSON a CSV con una sola petición a `POST /v1/convert/json-to-csv`. La entrada debe ser un array JSON de objetos; las cabeceras de columna se derivan de las claves del primer objeto y las filas se delimitan con comas usando entrecomillado `QUOTE_MINIMAL`. Por defecto la respuesta son los bytes CSV sin procesar; establece `direct_download=false` para recibir en su lugar metadatos con una URL de descarga prefirmada.

---

## Endpoint

```
POST /v1/convert/json-to-csv
```

**Content-Type:** `multipart/form-data`

**Entrada aceptada:** archivos `.json` (codificados en UTF-8)

**Formato de salida:** `.csv` (`text/csv`)

---

## Autenticación

Requiere una clave API privada o un token JWT obtenido de una clave pública.

```
X-API-Key: sk_your_private_key
```

O bien:

```
Authorization: Bearer <jwt_token>
```

---

## Parámetros de la petición

| Parámetro | Tipo | Obligatorio | Por defecto | Descripción |
|-----------|------|----------|---------|-------------|
| `file` | file | Sí | -- | El archivo `.json` a convertir. Debe contener un array JSON de objetos. Codificado en UTF-8. |
| `output_filename` | `string` | No | Nombre del archivo de entrada | Nombre de archivo de salida personalizado. La extensión `.csv` se añade automáticamente. |
| `direct_download` | `boolean` | No | `true` | Con `true`, devuelve los bytes CSV sin procesar. Con `false`, devuelve metadatos con una URL de descarga prefirmada. |

---

## Reglas de conversión

```json
[
  {"name": "Alice", "age": 30, "city": "London"},
  {"name": "Bob", "age": 25, "city": "Paris"}
]
```

Se convierte en:

```csv
name,age,city
Alice,30,London
Bob,25,Paris
```

- La entrada **debe** ser un array JSON de objetos (lista de diccionarios)
- Las cabeceras de columna se derivan **solo de las claves del primer objeto**
- El delimitador es la coma (no configurable)
- El entrecomillado sigue `QUOTE_MINIMAL` -- los valores que contienen comas, comillas o saltos de línea se entrecomillan
- Los objetos o arrays anidados en los valores se serializan como su representación en string (no se aplanan)

<div class="alert alert-warning">
<strong>Importante:</strong> Si los objetos del array tienen claves distintas, las claves adicionales de los objetos posteriores se descartan silenciosamente. Las claves ausentes producen valores vacíos. Para obtener los mejores resultados, asegúrate de que todos los objetos tengan el mismo conjunto de claves.
</div>

---

## Respuesta

### Descarga directa (`direct_download=true`, por defecto)

```
HTTP 200 OK
Content-Type: text/csv
Content-Disposition: inline; filename="data_20260405_123456789.csv"
```

### Respuesta con metadatos (`direct_download=false`)

```json
{
    "presigned_url": "https://spaces.example.com/...",
    "object_key": "env/files/{project_id}/json-to-csv/data_20260405_123456789.csv",
    "filename": "data_20260405_123456789.csv",
    "file_size": 1234,
    "conversion_time_seconds": 0.03
}
```

---

## Ejemplos de código

### Python

```python
import requests

with open("data.json", "rb") as f:
    response = requests.post(
        "https://api.enconvert.com/v1/convert/json-to-csv",
        headers={"X-API-Key": "sk_your_private_key"},
        files={"file": ("data.json", f, "application/json")}
    )

with open("data.csv", "wb") as out:
    out.write(response.content)
```

### Node.js

```javascript
const form = new FormData();
form.append("file", fs.createReadStream("data.json"));

const response = await fetch("https://api.enconvert.com/v1/convert/json-to-csv", {
    method: "POST",
    headers: { "X-API-Key": "sk_your_private_key" },
    body: form
});

const csv = await response.text();
```

### PHP

```php
$ch = curl_init("https://api.enconvert.com/v1/convert/json-to-csv");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: sk_your_private_key"],
    CURLOPT_POSTFIELDS => ["file" => new CURLFile("data.json", "application/json")]
]);
$csv = curl_exec($ch);
curl_close($ch);
```

### Go

```go
body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
part, _ := writer.CreateFormFile("file", "data.json")
file, _ := os.Open("data.json")
io.Copy(part, file)
writer.Close()

req, _ := http.NewRequest("POST", "https://api.enconvert.com/v1/convert/json-to-csv", body)
req.Header.Set("Content-Type", writer.FormDataContentType())
req.Header.Set("X-API-Key", "sk_your_private_key")
resp, _ := http.DefaultClient.Do(req)
```

---

## Respuestas de error

| Estado | Condición |
|--------|-----------|
| `400 Bad Request` | El archivo no es un archivo `.json` |
| `400 Bad Request` | Contenido JSON no válido |
| `400 Bad Request` | El JSON debe ser un array de objetos para la conversión a CSV |
| `400 Bad Request` | El array JSON está vacío |
| `400 Bad Request` | El array JSON debe contener objetos (diccionarios) |
| `401 Unauthorized` | Clave API o token JWT ausente o no válido |
| `402 Payment Required` | Cuota mensual de ops agotada |
| `413 Payload Too Large` | El archivo supera el tamaño máximo de archivo del plan |

---

## Límites

| Límite | Valor |
|-------|-------|
| Tamaño máximo de archivo | Según el plan (Founding: 5 MB) |
| Codificación de entrada | Solo UTF-8 |
| Estructura de entrada | Solo array de objetos |
| Conversiones mensuales | Según el plan |

## Preguntas frecuentes

### ¿Cómo convierto un array JSON a CSV con una API REST?

Envía una petición POST `multipart/form-data` a `/v1/convert/json-to-csv` con un archivo `.json` que contenga un array de objetos en el campo `file`, autenticada con una cabecera `X-API-Key` o un token JWT `Authorization: Bearer`. La respuesta es CSV delimitado por comas.

### ¿Qué pasa si los objetos JSON tienen claves distintas?

Las cabeceras de columna provienen solo de las claves del primer objeto. Las claves adicionales de los objetos posteriores se descartan silenciosamente y las claves ausentes producen valores vacíos, así que asegúrate de que todos los objetos compartan el mismo conjunto de claves para obtener los mejores resultados.

### ¿Los objetos JSON anidados se aplanan en columnas CSV?

No. Los objetos o arrays anidados en los valores se serializan como su representación en string en lugar de aplanarse en columnas separadas.

### ¿Puedo cambiar el delimitador del CSV?

No. El delimitador es siempre la coma y no es configurable. El entrecomillado sigue `QUOTE_MINIMAL`, así que los valores que contienen comas, comillas o saltos de línea se entrecomillan automáticamente.

### ¿Por qué la API de JSON a CSV devuelve 400 Bad Request?

Se devuelve un `400` cuando el archivo no es `.json`, el JSON no es válido, el JSON no es un array de objetos o el array está vacío. Los archivos demasiado grandes devuelven `413 Payload Too Large`.