PDF Blocks
PrezziSupporto
Iniziare gratis
Aprire la pagina

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:

cURLbash
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 è 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.

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.

cURLbash
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
Pythonpython
# 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)
Node.jsjavascript
// 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()));

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.

Un’immagine accanto al PDF: la filigrana immagine

Aggiungere una filigrana immagine 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.

cURLbash
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.
  • 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.

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.