---
seo_title: API XML in CSV | Converti XML tabellare in CSV | EnConvert
meta_desc: Converti XML in CSV con POST /v1/convert/xml-to-csv. Appiattisce XML tabellare con elementi ripetuti in righe separate da virgola, diretto o via URL prefirmato.
keywords: xml in csv api, convertire xml in csv, api conversione xml csv, xml to csv rest api, xml tabellare in csv api, xml in csv python, xml in csv curl, esportare dati xml in csv api
---

# API XML in CSV

L'API XML in CSV converte un file XML tabellare in formato CSV con una singola richiesta a `POST /v1/convert/xml-to-csv`. Si aspetta elementi fratelli piatti e ripetuti con elementi figli coerenti, e rimuove automaticamente i wrapper `<root>` e `<item>`. La risposta è CSV grezzo per impostazione predefinita, oppure imposta `direct_download=false` per i metadati con un URL di download prefirmato.

---

## Endpoint

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

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

**Input accettato:** file `.xml` (codificati in UTF-8)

**Formato di output:** `.csv` (`text/csv`)

---

## Autenticazione

Richiede una chiave API privata oppure un token JWT ottenuto da una chiave pubblica.

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

Oppure:

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

---

## Parametri della richiesta

| Parametro | Tipo | Obbligatorio | Predefinito | Descrizione |
|-----------|------|----------|---------|-------------|
| `file` | file | Sì | -- | Il file `.xml` da convertire. Deve contenere dati tabellari (elementi ripetuti con campi coerenti). Codificato in UTF-8. |
| `output_filename` | `string` | No | Nome file di input | Nome file di output personalizzato. L'estensione `.csv` viene aggiunta automaticamente. |
| `direct_download` | `boolean` | No | `true` | Con `true`, restituisce i byte CSV grezzi. Con `false`, restituisce i metadati con un URL di download prefirmato. |

---

## Regole di conversione

```xml
<root>
  <item>
    <name>Alice</name>
    <age>30</age>
    <city>London</city>
  </item>
  <item>
    <name>Bob</name>
    <age>25</age>
    <city>Paris</city>
  </item>
</root>
```

Diventa:

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

- Rimuove automaticamente il wrapper `<root>` (dict radice a chiave singola)
- Rimuove automaticamente il wrapper `<item>` (dict a chiave singola contenente la lista)
- Se viene trovato un singolo record XML (non racchiuso in una lista), viene automaticamente racchiuso in una lista
- Le intestazioni di colonna derivano dai nomi dei tag figli del primo elemento
- Il delimitatore è la virgola (non configurabile), il quoting è minimale

<div class="alert alert-warning">
<strong>Importante:</strong> Questo endpoint funziona solo con XML "tabellare" -- elementi fratelli piatti e ripetuti con elementi figli coerenti. XML con nidificazione profonda o contenuto misto fallirà o produrrà risultati imprevisti. Per strutture XML complesse, usa invece <a href="/it/docs/endpoints/convert/data-formats/xml-to-json">xml-to-json</a>.
</div>

---

## Risposta

### Download diretto (`direct_download=true`, predefinito)

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

### Risposta con metadati (`direct_download=false`)

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

---

## Esempi di codice

### Python

```python
import requests

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

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

### Node.js

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

const response = await fetch("https://api.enconvert.com/v1/convert/xml-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/xml-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.xml", "application/xml")]
]);
$csv = curl_exec($ch);
curl_close($ch);
```

### Go

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

req, _ := http.NewRequest("POST", "https://api.enconvert.com/v1/convert/xml-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)
```

---

## Risposte di errore

| Stato | Condizione |
|--------|-----------|
| `400 Bad Request` | Il file non è un file `.xml` |
| `400 Bad Request` | La struttura XML non può essere convertita in CSV (non tabellare) |
| `400 Bad Request` | L'XML deve contenere elementi con campi coerenti per la conversione in CSV |
| `400 Bad Request` | Codifica XML non valida (attesa UTF-8) |
| `401 Unauthorized` | Chiave API / token JWT mancante o non valido |
| `402 Payment Required` | Quota mensile di ops esaurita |
| `413 Payload Too Large` | Il file supera la dimensione massima prevista dal piano |

---

## Limiti

| Limite | Valore |
|-------|-------|
| Dimensione massima del file | Dipende dal piano (Founding: 5 MB) |
| Codifica di input | Solo UTF-8 |
| Struttura XML | Solo tabellare (elementi piatti e ripetuti) |
| Conversioni mensili | Dipende dal piano |

---

## Domande frequenti

### Come convertire XML in CSV con un'API REST?

Invia una richiesta POST `multipart/form-data` a `POST /v1/convert/xml-to-csv` con il file `.xml` nel campo `file`, autenticandoti con un header `X-API-Key` o un token JWT `Authorization: Bearer`. Per impostazione predefinita il corpo della risposta contiene i byte CSV grezzi.

### Perché la conversione da XML a CSV fallisce con un errore 400?

Un `400 Bad Request` viene restituito quando la struttura XML non è tabellare, gli elementi non hanno campi coerenti, il file non è un `.xml` oppure la codifica non è UTF-8.

### Posso convertire in CSV un XML con nidificazione profonda?

No. Questo endpoint funziona solo con XML tabellare, ovvero elementi fratelli piatti e ripetuti con elementi figli coerenti. Per strutture XML complesse o con nidificazione profonda, usa invece l'endpoint xml-to-json.

### Come vengono determinate le intestazioni di colonna del CSV a partire dall'XML?

Le intestazioni di colonna derivano dai nomi dei tag figli del primo elemento. I wrapper `<root>` e `<item>` vengono rimossi automaticamente e un record singolo viene automaticamente racchiuso in una lista.

### Posso cambiare il delimitatore del CSV in output?

No. Il delimitatore è la virgola e non è configurabile; il quoting è minimale.