Scegliere una API di generazione PDF sembra facile finché non si comincia. Ci sono circa 40 fornitori, le pagine marketing suonano tutte simili e i veri compromessi emergono solo dopo qualche migliaio di documenti in produzione.

Questa è una checklist da portare in una valutazione fornitori: neutrale, costruita sugli incidenti che i team incontrano davvero durante acquisti e post-mortem. Otto domande; se non riuscite a ottenere una risposta chiara a tutte, non avete abbastanza informazioni per scegliere.

1. Qual è il formato di input: HTML, JSON o un template DSL?

È la domanda più importante. La risposta determina cosa il vostro team dovrà scrivere e cosa dovrà debuggare alle 2 di notte.

HTML/CSS (Puppeteer, DocRaptor, Prince): familiare, infinitamente flessibile, costoso a runtime, difficile da rendere deterministico.
JSON / dati strutturati (gPdf): economico da renderizzare, byte-identical, richiede un piccolo mapper dal vostro modello dati al modello documento.
Template DSL (PDFKit, ReportLab, Apache PDFBox): controllo pieno, responsabilità piena; sarete voi a scrivere paginazione, layout e fallback dei font.

Non esiste una risposta sbagliata in assoluto. Esiste una risposta sbagliata per il vostro team. Chiedete agli ingegneri in quale modello preferirebbero risolvere un bug di paginazione da tre ore.

2. Qual è la latenza di cold start, ed è prevedibile?

Alcuni motori di rendering si avviano in microsecondi (WASM o binari nativi). Altri si avviano in secondi (quelli basati su Chromium). La differenza resta invisibile finché non arriva un picco di traffico.

Cosa chiedere al fornitore:

“Qual è la vostra latenza p99 per la prima richiesta a un worker freddo?”
“Dopo quanto tempo dall’ultima richiesta un worker torna freddo?”
“Pubblicate una pagina di stato con dati sui cold start?”

Se non sanno rispondere alla prima domanda con un numero, assumete che sia un brutto numero.

3. Come viene modellato il costo per rendering?

Tre modelli, in ordine di quanto spesso creano sorprese:

Prezzo per pagina (Anvil a 0,10 USD/PDF, DocRaptor a 89 USD/100K): prevedibile, semplice da mettere a budget, costoso in scala.
Abbonamenti con eccedenza (gPdf a 5-12 USD/mese + 0,00005 USD/pagina oltre soglia): economico a qualsiasi volume, più difficile da stimare per usi mai testati.
Prezzo basato sul compute (Puppeteer self-hosted su Lambda): pagate direttamente il compute, inclusi cold start e memoria Chromium.

Calcolate la vostra fattura REALE a tre livelli di traffico (attuale, 5×, 50×) prima di firmare. La forma della curva dei costi conta più del numero in evidenza.

4. L’output è deterministico?

Determinismo, cioè stesso input -> stessi byte, sembra accademico finché non serve davvero.

Serve quando:

Fate diff dei PDF in CI per intercettare modifiche indesiderate ai template.
Conservate documenti secondo regole e-invoice o fiscali: il PDF conservato e quello rigenerato devono coincidere.
Calcolate un hash del PDF per integrità di archiviazione.
Versionate l’output renderizzato per revisione legale.

I motori basati su browser (Puppeteer, qualsiasi cosa Chromium) NON sono deterministici tra versioni patch. I motori binari nativi (Prince, gPdf) di solito lo sono. Chiedete esplicitamente: “I byte del mio output cambieranno se rilasciate un aggiornamento del motore?”

5. Come gestisce i font, soprattutto CJK e RTL?

Questa è la domanda che ha bruciato più carriere nel mondo PDF.

Il modo in cui fallisce è ricorrente: lanciate nel mercato iniziale, i font sono a posto. Sei mesi dopo entrate in un mercato che usa uno script per cui il motore non ha glifi. Il PDF comincia a emettere riquadri □□□□. Il cliente scala. Il team passa due sprint ad aggiungere font a un Dockerfile.

Domande da fare:

“Quali script sono inclusi senza configurazione extra? (Latin, CJK, Cyrillic, Devanagari, Arabic, Hebrew?)”
“Cosa succede quando viene incontrato un glifo sconosciuto: fallback o tofu?”
“Posso aggiungere font custom al tempo della richiesta, o devo distribuirli prima?”
“Supportate shaping del testo RTL?”

Una buona risposta: “Incorporiamo NotoSans CJK e un set di fallback Noto; i glifi sconosciuti ricadono su Noto Symbols.” Una cattiva risposta: “Sì, supportiamo i font.”

6. Quali profili di conformità sono supportati?

Se la vostra azienda potrebbe mai:

emettere fatture in EU (Factur-X / ZUGFeRD / EN 16931, obbligatorio in DE/FR/IT/PL entro il 2026),
archiviare documenti secondo regole di retention SOX, HIPAA o GDPR (PDF/A),
inviare cartelle cliniche (PDF/A-3 con XML allegato),
incorporare firme digitali (PAdES),

allora chiedete quali profili di conformità il motore supporta nativamente. La risposta negativa è: “potete usare un altro tool per convertire dopo”. È una pipeline a più passaggi che ora possedete voi.

Le buone risposte di solito assomigliano a un singolo flag: per esempio, gPdf accetta settings.profile: "pdfa-3b" più un blocco settings.e_invoice con standard: "factur_x" e un CII XML incorporato. Integrato è drasticamente più leggero da gestire rispetto ad aggiunto dopo.

7. Il rendering è stateless? Dove finiscono i miei documenti dopo il rendering?

Sono due domande collegate.

Rendering stateless significa che la richiesta entra, il PDF viene emesso, nulla viene conservato. Gestite voi la persistenza (S3, database, qualsiasi storage interno). È quello che volete per carichi con forte attenzione alla privacy: il motore di rendering non diventa mai custode dei vostri dati.

Rendering stateful significa che il fornitore conserva il PDF (spesso sul proprio CDN) e vi restituisce un URL firmato. Comodo per usi occasionali, per esempio “manda al cliente un link”, problematico per processi regolati: ora un terzo possiede una copia di ogni documento che avete renderizzato.

Chiedete:

“Il rendering è stateless di default?”
“Dove viene conservato geograficamente il documento, se lo conservate?”
“Per quanto tempo viene mantenuto?”
“Posso avere una garanzia scritta di rendering stateless per la revisione privacy/conformità?”

Se la risposta è vaga, il team privacy/legal lo trasformerà in un problema tra 9 mesi.

8. Cosa succede quando il motore fallisce, e come lo scopro?

Ogni motore di rendering fallisce a volte. Le domande sono:

Come emerge l’errore? Un 500 con stack trace? Un 4xx con errore strutturato? Un PDF vuoto?
Qual è la policy di retry? È idempotente? I rendering falliti vengono fatturati?
Quale strumentazione fornisce il fornitore? Pagina di stato? Webhook per incidenti? Dashboard p50/p99 per regione?
Esiste una synthetic probe? Il fornitore monitora il percorso pubblico, o aspetta che apriate voi il ticket?

Test rapido: visitate subito la pagina di stato del fornitore. Se non esiste, non è real-time o mostra solo “all systems operational” senza dettagli, quello è il livello di trasparenza operativa che avrete dopo l’acquisto.

(Per riferimento: gPdf pubblica /status con dati di synthetic probe + Cloudflare Analytics sugli ultimi 7 giorni.)

Come si posiziona gPdf rispetto alle otto domande

Dato che questo è il nostro blog e sospetterete che abbiamo scelto domande favorevoli, ecco la nostra scorecard onesta:

#	Domanda	Risposta gPdf
1	Formato di input	JSON `DocumentRequest` (dati strutturati)
2	Cold start	5-20 ms (V8 isolate, nessun browser)
3	Modello di costo	0/5/8/12 USD al mese; 0,00005 USD/pagina oltre soglia
4	Determinismo	Byte-identical, garantito sulla stessa versione del motore
5	Font	NotoSans CJK + fallback Latin incorporati
6	Conformità	PDF/A-1b/2b/3b/4 + allegato Factur-X / ZUGFeRD integrato
7	Stateless	Sì, contrattualmente: nessuno storage documenti
8	Errori e visibilità	Pagina di stato pubblica con trend a 7 giorni; 4xx/5xx strutturati; idempotente

Dove perdiamo: Q1, se il vostro input è davvero HTML e non potete rifattorizzarlo (per esempio report generati dagli utenti o template legacy). In quel caso DocRaptor o Prince sono la scelta giusta.

TL;DR

Non chiedete “qual è la migliore API PDF”. Fate le otto domande, valutate le risposte e scegliete il fornitore allineato al vostro carico reale. Il team che ha perso una procurement contro un concorrente leggermente più economico perché nove mesi dopo è stato sorpreso dalla domanda #5 vi direbbe la stessa cosa.

Se il vostro carico si allinea a come gPdf è costruito, il Playground richiede 30 secondi per una valutazione. Se non si allinea, vi indicheremo volentieri lo strumento più adatto: di solito DocRaptor per problemi in forma HTML, Prince per self-hosting, o Puppeteer se l’input è davvero costituito da pagine web arbitrarie.