Come inviare un PDF a un'API in Base64
Un'API di fatturazione elettronica, di firma digitale o di spedizioni vuole il documento in un campo JSON. Ecco come trasformare il PDF nel testo giusto, controllarlo ed evitare gli errori che fanno fallire la richiesta.
Di Metin Ersoy · Aggiornato il 10 novembre 2026
Cosa si aspetta di solito l'API
La maggior parte delle API per documenti descrive un corpo JSON con un campo chiamato content, file, data o document. Il suo valore è il codice Base64 del PDF, spesso accompagnato da un nome file e da un tipo:
{
"fileName": "invoice-1024.pdf",
"mimeType": "application/pdf",
"content": "JVBERi0xLjcKJ..."
}
Prima di scrivere codice, cerca tre cose nella documentazione: il nome del campo, se serve un prefisso data: (di solito no) e il limite di dimensione.
1. Trasforma il PDF in Base64
Il modo più rapido per ottenere un valore di prova è PDF in Base64. Scegli il PDF, seleziona Solo il codice Base64 e copia il risultato. Se vuoi partire da un corpo della richiesta completo, scegli invece JSON: aggiunge per te il nome e il tipo del file. Il PDF viene codificato nel tuo browser e non viene caricato, e questo conta quando il documento di prova è una fattura vera.
Controlla il risultato: deve iniziare con JVBERi0, non contenere spazi e, a parte uno o due segni = alla fine, solo lettere, cifre, + e /.
2. Invialo dal tuo codice
Lo stesso passaggio in tre linguaggi diffusi. Ogni esempio legge il file, lo codifica e invia il JSON:
# curl (Linux / macOS): base64 -w 0 tiene tutto su una riga
curl -X POST https://api.example.com/documents \
-H "Content-Type: application/json" \
-d "{\"fileName\":\"invoice.pdf\",\"content\":\"$(base64 -w 0 invoice.pdf)\"}"
// Node.js 18+
import { readFile } from 'node:fs/promises';
const content = (await readFile('invoice.pdf')).toString('base64');
await fetch('https://api.example.com/documents', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ fileName: 'invoice.pdf', content }),
});
# Python 3 con requests
import base64, requests
with open("invoice.pdf", "rb") as f:
content = base64.b64encode(f.read()).decode("ascii")
requests.post("https://api.example.com/documents",
json={"fileName": "invoice.pdf", "content": content})
Su macOS la riga di curl usa base64 -i invoice.pdf al posto di -w 0. L'indirizzo e i nomi dei campi sono solo esempi: usa quelli indicati nella documentazione del tuo servizio.
3. Verifica andata e ritorno
Se il servizio restituisce il documento o una copia archiviata in Base64, incolla la risposta in Base64 in PDF. Vedere la prima pagina e il numero di pagine è il modo più veloce per avere la prova che durante il tragitto non si è perso nulla. I passaggi dettagliati per questa direzione sono in Come salvare una stringa Base64 come file PDF.
Errori comuni
| Sintomo | Causa probabile | Soluzione |
|---|---|---|
| «Invalid Base64» | Interruzioni di riga (righe da 76 caratteri) o un prefisso data: | Invia il codice puro su una sola riga |
| «Payload too large» (413) | Dopo la codifica il PDF è troppo grande | Riducilo con Comprimere PDF |
| Il PDF si apre vuoto o danneggiato | La stringa è stata tagliata | Codifica di nuovo e invia il valore completo |
| I nomi con lettere accentate sono sbagliati | Nome del file inviato con la codifica sbagliata | Mantieni il corpo JSON in UTF-8 |
Vuoi provarlo? È gratis e il tuo file resta sul tuo dispositivo.
Apri PDF in Base64