Choisir une API de génération PDF paraît simple jusqu’au moment de commencer. Les fournisseurs sont nombreux, leurs pages marketing se ressemblent, et les vrais compromis apparaissent après des milliers de documents en production.
Cette checklist sert à évaluer les vendeurs. Elle est neutre et issue d’incidents réels vus lors d’achats, d’exploitation et de post-mortems. Huit questions; sans réponses claires, vous n’avez pas encore assez d’information.
1. Quel format d’entrée : HTML, JSON ou DSL de templates ?
C’est la question centrale. Elle détermine ce que votre équipe écrira et déboguera.
- HTML/CSS (Puppeteer, DocRaptor, Prince) : familier, très flexible, coûteux à l’exécution, difficile à rendre déterministe.
- JSON / données structurées (gPdf) : peu coûteux à rendre, identique octet par octet, mais nécessite un mapper vers le modèle documentaire.
- DSL de templates (PDFKit, ReportLab, Apache PDFBox) : contrôle total, responsabilité totale sur pagination, layout et polices.
Il n’y a pas de bonne réponse universelle. Il y a une mauvaise réponse pour votre équipe. Demandez aux ingénieurs dans quel modèle ils préfèrent corriger un bug de pagination de trois heures.
2. Quelle est la latence de cold start et est-elle prévisible ?
WASM et les binaires natifs peuvent démarrer en microsecondes. Chromium peut prendre des secondes. La différence apparaît lors des pics de trafic.
Demandez le p99 du premier appel à un worker froid, le délai avant qu’il redevienne froid, et si ces données sont publiées sur la page de statut.
3. Comment le coût par rendu est-il calculé ?
Les modèles courants :
- Prix par page : prévisible, mais cher à grande échelle.
- Abonnement + dépassement : souvent bon marché, mais demande une estimation d’usage.
- Coût compute : vous payez Lambda, conteneurs, mémoire Chromium et cold starts.
Calculez votre facture en trafic actuel, 5x et 50x. La courbe compte plus que le prix d’appel.
4. La sortie est-elle déterministe ?
Même entrée, mêmes octets. C’est nécessaire pour diff en CI, rétention fiscale, hash d’archive ou revue juridique.
Les moteurs basés navigateur ne sont généralement pas déterministes entre versions de Chromium. Les moteurs natifs s’en sortent mieux. Demandez si une mise à jour du moteur changera vos octets.
5. Comment les polices, CJK et RTL sont-ils gérés ?
Les polices créent souvent des incidents tardifs. Tout marche sur le marché initial, puis un nouveau script produit des □□□□.
Demandez quels scripts sont inclus, le comportement face aux glyphes inconnus, la possibilité de fournir une police par requête, et le support du shaping RTL.
6. Quels profils de conformité sont supportés ?
Si vous risquez d’émettre des factures UE, d’archiver en PDF/A, d’attacher du XML ou de signer numériquement, exigez un support natif. “Convertir ensuite” signifie une pipeline à maintenir.
Les bonnes réponses ressemblent à { profile: "PDF/A-3b" } ou { einvoice: { format: "factur-x", xml: "..." } }.
7. Le rendu est-il stateless ? Où vont les documents ?
Le rendu stateless reçoit la requête, renvoie le PDF et ne stocke rien. Vous gérez la persistance. C’est préférable pour les charges réglementées.
Le rendu stateful stocke le PDF chez le fournisseur et renvoie une URL signée. C’est pratique, mais un tiers possède une copie de chaque document.
8. Que se passe-t-il en cas d’échec ?
Tout moteur échoue parfois. Vérifiez erreurs structurées, idempotence, facturation des échecs, page de statut, webhooks, métriques par région et sondes synthétiques.
Le score de gPdf
| # | Question | Réponse gPdf |
|---|---|---|
| 1 | Entrée | JSON DocumentRequest |
| 2 | Cold start | 5-20 ms, V8 isolate, sans navigateur |
| 3 | Coût | $0/$5/$8/$12 par mois; $0.00005/page en dépassement |
| 4 | Déterminisme | Octets identiques avec la même version moteur |
| 5 | Polices | NotoSans CJK + fallback latin intégrés |
| 6 | Conformité | PDF/A-1b/2b/3b/4 + Factur-X / ZUGFeRD |
| 7 | Stateless | Oui, aucun stockage de documents |
| 8 | Échecs | Page de statut publique, erreurs structurées, idempotent |
Si votre entrée est réellement du HTML impossible à refactorer, DocRaptor ou Prince peuvent être meilleurs.
En bref
Ne cherchez pas “la meilleure API PDF”. Posez ces huit questions et choisissez selon votre charge réelle. Pour factures, reçus et documents structurés, testez gPdf dans le Playground.