Scegliere una API per generare PDF sembra facile finché non inizi. Ci sono molti fornitori, le pagine marketing sembrano uguali e i veri tradeoff emergono solo dopo migliaia di documenti in produzione.
Questa checklist è pensata per valutare i vendor. È neutrale e nasce da problemi reali visti in acquisti, operazioni e post-mortem. Sono otto domande; senza risposte chiare, non hai abbastanza informazioni per scegliere.
1. Qual è il formato di input: HTML, JSON o template DSL?
È la domanda più importante perché decide cosa scriverà il team e cosa dovrà debuggare.
- HTML/CSS (Puppeteer, DocRaptor, Prince): familiare, molto flessibile, costoso a runtime, difficile da rendere deterministico.
- JSON / dati strutturati (gPdf): economico da renderizzare, byte-identical, ma richiede un mapper dal modello dati al modello documento.
- Template DSL (PDFKit, ReportLab, Apache PDFBox): controllo totale e responsabilità totale su paginazione, layout e fallback dei font.
Non esiste una risposta giusta per tutti. Esiste quella sbagliata per il tuo team. Chiedi agli ingegneri in quale modello preferirebbero correggere un bug di paginazione di tre ore.
2. Qual è la cold-start latency ed è prevedibile?
WASM e binari nativi possono partire in microsecondi. Soluzioni basate su Chromium possono richiedere secondi. La differenza si vede durante i picchi.
Chiedi il p99 della prima request su worker freddo, dopo quanto torna freddo e se i dati sono pubblicati nella status page.
3. Come viene calcolato il costo per render?
Modelli comuni:
- Prezzo per pagina: prevedibile, ma caro in scala.
- Abbonamento + overage: spesso economico, ma richiede stime d’uso.
- Compute-based: paghi Lambda, container, memoria Chromium e cold start.
Calcola la fattura per traffico attuale, 5x e 50x. La curva dei costi conta più del prezzo in homepage.
4. L’output è deterministico?
Stesso input, stessi byte. Serve per diff PDF in CI, conservazione fiscale, hash di archivio e revisione legale.
I renderer browser-based spesso non sono deterministici tra versioni di Chromium. I renderer nativi sono di solito migliori. Chiedi se un aggiornamento del motore cambierà i byte.
5. Come gestisce font, CJK e RTL?
I font sono una fonte frequente di incidenti. Tutto funziona nel mercato iniziale, poi un nuovo script produce □□□□.
Chiedi quali script sono inclusi, cosa succede con glyph sconosciuti, se puoi passare font custom per request e se c’è RTL shaping.
6. Quali profili di compliance supporta?
Se potresti emettere fatture UE, archiviare PDF/A, allegare XML o firmare digitalmente, chiedi supporto nativo. “Converti dopo con un tool” significa gestire una pipeline in più.
Le buone risposte sono concrete: { profile: "PDF/A-3b" } o { einvoice: { format: "factur-x", xml: "..." } }.
7. Il rendering è stateless? Dove vanno i documenti?
Stateless significa request in ingresso, PDF in uscita, nessuno storage. Tu gestisci la persistenza. È preferibile per workload regolati.
Stateful significa che il vendor conserva il PDF e restituisce una signed URL. Comodo, ma un terzo possiede copie dei documenti.
8. Cosa succede quando fallisce?
Ogni renderer fallisce a volte. Verifica errori strutturati, retry idempotente, costi su fallimenti, status page, webhook, metriche per regione e synthetic probes.
gPdf in breve
| # | Domanda | Risposta gPdf |
|---|---|---|
| 1 | Input | JSON DocumentRequest |
| 2 | Cold start | 5-20 ms, V8 isolate, niente browser |
| 3 | Costo | $0/$5/$8/$12 al mese; $0.00005/page overage |
| 4 | Determinismo | Byte-identical con la stessa versione del motore |
| 5 | Font | NotoSans CJK + fallback latino integrati |
| 6 | Compliance | PDF/A-1b/2b/3b/4 + Factur-X / ZUGFeRD |
| 7 | Stateless | Sì, nessuno storage documenti |
| 8 | Failure | Status page pubblica, errori strutturati, idempotente |
Se il tuo input è davvero HTML non rifattorizzabile, DocRaptor o Prince possono essere migliori.
Sintesi
Non chiedere “qual è la migliore API PDF”. Fai queste otto domande e scegli in base al workload reale. Per fatture, ricevute e documenti strutturati, prova gPdf nel Playground.