# Lavorare con i file

Come allegare i file di input a una richiesta: un solo PDF, un elenco ordinato per l’unione, una seconda immagine per le filigrane e i limiti di ciascuno.

Gli input vengono inviati come parti binarie di una richiesta
`multipart/form-data`. La maggior parte delle azioni accetta esattamente un PDF
in un campo `file`, ma due azioni chiedono di più: l’unione accetta un array
ordinato di file e la filigrana immagine accetta un secondo binario accanto al
PDF. Questa pagina copre tutte e tre le forme di input.

## Un solo file

Il caso predefinito. Allegare un PDF nel campo `file` e aggiungere le opzioni
dell’azione come campi stringa:

```bash title="cURL"
curl https://api.pdfblocks.com/v1/extract_pages \
  -H 'X-API-Key: your_api_key' \
  -F file=@input.pdf \
  -F pages='1..3' \
  -o extract.pdf
```

La `@` in `-F file=@input.pdf` dice a cURL di inviare il contenuto del file.
Ogni azione a input singolo (filigrane, sicurezza, operazioni sulle pagine,
divisioni) funziona così.

## Più file: l’unione

[Unire documenti](/docs/api/merge-pdf-documents) è l’unica azione che accetta un
array. Inviare il campo `file` **più di una volta**: i documenti vengono uniti
nell’ordine in cui le parti compaiono nella richiesta. Fornire almeno un file;
se ne possono inviare molti in un’unica chiamata.

<Warning>
  L’ordine è posizionale, quindi inviare le parti nella sequenza in cui si vuole
  unirle. Quando il client HTTP espone un oggetto form, usare il suo metodo
  *append* (non *set*), in modo che ripetere `file` aggiunga parti invece di
  sovrascrivere la precedente.
</Warning>

<CodeGroup>

```bash title="cURL"
curl https://api.pdfblocks.com/v1/merge_documents \
  -H 'X-API-Key: your_api_key' \
  -F file=@cover.pdf \
  -F file=@body.pdf \
  -F file=@appendix.pdf \
  -o merged.pdf
```

```python title="Python"
# pip install requests
import requests

files = [
    ('file', ('cover.pdf', open('cover.pdf', 'rb'), 'application/pdf')),
    ('file', ('body.pdf', open('body.pdf', 'rb'), 'application/pdf')),
    ('file', ('appendix.pdf', open('appendix.pdf', 'rb'), 'application/pdf')),
]

response = requests.post(
    'https://api.pdfblocks.com/v1/merge_documents',
    headers={'X-API-Key': 'your_api_key'},
    files=files,
)

response.raise_for_status()
with open('merged.pdf', 'wb') as output:
    output.write(response.content)
```

```javascript title="Node.js"
// Node.js 18+
import { readFile, writeFile } from 'node:fs/promises';

const body = new FormData();
for (const name of ['cover.pdf', 'body.pdf', 'appendix.pdf']) {
  body.append('file', new Blob([await readFile(name)]), name);
}

const response = await fetch('https://api.pdfblocks.com/v1/merge_documents', {
  method: 'POST',
  headers: { 'X-API-Key': 'your_api_key' },
  body,
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
await writeFile('merged.pdf', Buffer.from(await response.arrayBuffer()));
```

</CodeGroup>

<Note>
  Se ripetere il campo `file` risulta scomodo nel proprio client HTTP (cURL in
  PHP, gli helper per i form in Ruby), inviare invece i campi numerati da
  `file_1` a `file_10`: vengono uniti in ordine numerico. Usare l’array `file`
  ripetuto quando servono più di dieci documenti.
</Note>

## Un’immagine accanto al PDF: la filigrana immagine

[Aggiungere una filigrana immagine](/docs/api/add-image-watermark-to-pdf)
accetta due parti binarie: il PDF in `file` e l’immagine della filigrana in un
campo `image`. L’immagine deve essere **PNG o JPEG**. Entrambe le parti sono
obbligatorie.

```bash title="cURL"
curl https://api.pdfblocks.com/v1/add_image_watermark \
  -H 'X-API-Key: your_api_key' \
  -F file=@input.pdf \
  -F image=@logo.png \
  -o watermarked.pdf
```

I campi restanti (`transparency`, `margin`, `pages`) sono normali opzioni
stringa: vedere il riferimento dell’azione per i loro intervalli e i valori
predefiniti.

## Input accettati e dimensioni

- L’input `file` (e ogni file unito) deve essere un PDF leggibile. Un file che
  non può essere analizzato come PDF restituisce un `400` che nomina il campo
  `file`. Vedere [Errori](/docs/api/errors).
- L’input `image` della filigrana immagine deve essere PNG o JPEG.
- Quali pagine un’azione tocca è una questione distinta da come si allega il
  file. Le selezioni di pagine si esprimono con il campo `pages` documentato in
  [Selezionare le pagine](/docs/api/selecting-pages).

Per i documenti di grandi dimensioni, con l’upload e il download in streaming, i
timeout e i nuovi tentativi, vedere [Lavorare con file di grandi
dimensioni](/docs/api/working-with-large-files).