---
seo_title: API Excel in PDF: converti XLSX e XLS in PDF | EnConvert
meta_desc: Converti Excel in PDF via API REST. POST /v1/convert/excel-to-pdf trasforma fogli di calcolo .xlsx e .xls in PDF ad alta fedeltà con rendering LibreOffice.
keywords: excel in pdf api, xlsx in pdf api, convertire xlsx in pdf api, api rest xls in pdf, foglio di calcolo in pdf api, api conversione excel pdf, xlsx in pdf api python, excel in pdf api node js
---

# API Excel in PDF

L'API Excel in PDF converte fogli di calcolo Microsoft Excel (`.xlsx`, `.xls`) in PDF tramite `POST /v1/convert/excel-to-pdf`, usando il motore di rendering ad alta fedeltà di LibreOffice. Formattazione, font e layout del foglio di calcolo vengono preservati nel PDF in output. La risposta è composta dai byte PDF grezzi per default, oppure da metadati JSON con un URL di download prefirmato quando `direct_download=false`.

---

## Endpoint

```
POST /v1/convert/excel-to-pdf
```

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

**Input accettato:** file `.xlsx or .xls`

**Formato di output:** `.pdf` (`application/pdf`)

---

## 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 | Default | Descrizione |
|-----------|------|----------|---------|-------------|
| `file` | file | Sì | -- | Il file `.xlsx or .xls` da convertire. |
| `output_filename` | `string` | No | Nome del file di input | Nome file di output personalizzato. L'estensione `.pdf` viene aggiunta automaticamente. |
| `direct_download` | `boolean` | No | `true` | Con `true`, restituisce i byte PDF grezzi. Con `false`, restituisce metadati JSON con un URL di download prefirmato. |
| `pdf_options` | `string` | No | `null` | Stringa JSON. Per questo endpoint è supportata solo l'opzione `grayscale` (vedi sotto). |

### Opzioni PDF

Per i convertitori di documenti basati su LibreOffice, il layout di pagina (formato, margini, orientamento) è determinato dalle impostazioni del documento stesso. L'unico campo `pdf_options` che si applica è:

| Parametro | Tipo | Default | Descrizione |
|-----------|------|---------|-------------|
| `grayscale` | `boolean` | `false` | Converte il PDF in output in scala di grigi tramite post-elaborazione con Ghostscript. |

<div class="alert alert-info">
<strong>Nota:</strong> formato pagina, margini, orientamento, scala, header e footer di <code>pdf_options</code> non si applicano a questo endpoint. Il PDF in output preserva la formattazione definita nel documento originale. Per cambiare il layout di pagina, modifica il documento sorgente prima del caricamento.
</div>

---

## Dettagli della conversione

- Usa **LibreOffice** (tramite unoserver) per il rendering dei documenti lato server
- Formattazione, font, layout di pagina e media incorporati del documento vengono preservati
- Timeout di conversione: 120 secondi
- L'output riproduce fedelmente il documento come apparirebbe stampato da LibreOffice

---

## Risposta

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

```
HTTP 200 OK
Content-Type: application/pdf
Content-Disposition: inline; filename="document_20260405_123456789.pdf"
```

Restituisce i byte PDF grezzi.

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

```json
{
    "presigned_url": "https://spaces.example.com/...",
    "object_key": "env/files/{project_id}/excel-to-pdf/document_20260405_123456789.pdf",
    "filename": "document_20260405_123456789.pdf",
    "file_size": 67890,
    "conversion_time_seconds": 3.5
}
```

---

## Esempi di codice

### Python

```python
import requests

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

with open("output.pdf", "wb") as out:
    out.write(response.content)
```

### Node.js

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

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

fs.writeFileSync("output.pdf", Buffer.from(await response.arrayBuffer()));
```

### PHP

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

### Go

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

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

### Con output in scala di grigi

```python
import requests
import json

with open("document.xlsx", "rb") as f:
    response = requests.post(
        "https://api.enconvert.com/v1/convert/excel-to-pdf",
        headers={"X-API-Key": "sk_your_private_key"},
        files={"file": ("document.xlsx", f)},
        data={"pdf_options": json.dumps({"grayscale": True})}
    )
```

---

## Risposte di errore

| Stato | Condizione |
|--------|-----------|
| `400 Bad Request` | Il file non è un file `.xlsx or .xls` |
| `400 Bad Request` | Conversione del documento non riuscita (file corrotto o non supportato) |
| `400 Bad Request` | JSON `pdf_options` non valido |
| `401 Unauthorized` | Chiave API / token JWT mancante o non valido |
| `402 Payment Required` | Quota mensile di ops esaurita |
| `402 Payment Required` | Limite di storage raggiunto |
| `413 Payload Too Large` | Il file supera la dimensione massima prevista dal piano |
| `500 Internal Server Error` | Timeout della conversione (limite di 120 secondi) |

---

## Limiti

| Limite | Valore |
|-------|-------|
| Dimensione massima del file | Dipende dal piano (Founding: 5 MB) |
| Timeout di conversione | 120 secondi |
| Conversioni mensili | Dipende dal piano |

## Domande frequenti

### Come converto un foglio di calcolo XLSX in PDF con un'API REST?

Invia una richiesta `multipart/form-data` a `POST /v1/convert/excel-to-pdf` con il file `.xlsx` o `.xls` nel campo `file`, autenticandoti con `X-API-Key` o un JWT Bearer. Per default la risposta è composta dai byte PDF grezzi con `Content-Type: application/pdf`.

### La conversione da Excel a PDF preserva la formattazione del foglio di calcolo?

Sì. L'endpoint usa LibreOffice (tramite unoserver) per il rendering lato server, quindi formattazione, font, layout di pagina e media incorporati del foglio di calcolo vengono preservati. L'output riproduce il documento come apparirebbe stampato da LibreOffice.

### Posso impostare formato pagina, margini o orientamento nella conversione da Excel a PDF?

No. Il layout di pagina è determinato dalle impostazioni del foglio di calcolo stesso e l'unico campo `pdf_options` supportato su questo endpoint è `grayscale`. Per cambiare il layout di pagina, modifica il file sorgente prima del caricamento.

### Perché la mia conversione da Excel a PDF è fallita o è andata in timeout?

Un `400 Bad Request` significa che il file non è `.xlsx` o `.xls`, è corrotto o non supportato, oppure il JSON `pdf_options` non è valido. Un `500 Internal Server Error` significa che la conversione ha superato il timeout di 120 secondi.

### Posso ottenere un URL di download invece dei byte PDF?

Sì. Imposta `direct_download=false` e l'endpoint restituisce metadati JSON che includono `presigned_url`, `object_key`, `filename`, `file_size` e `conversion_time_seconds`.