Le vrai problème n’est pas de produire un fichier
Une API de génération PDF reçoit généralement des données, applique un template puis retourne un document. Cette description est exacte, mais incomplète. En production, il faut aussi savoir quelle version du template a été utilisée, pourquoi une génération a échoué, combien de temps le fichier reste accessible et comment éviter les doublons.
Le bon point de départ consiste donc à modéliser la génération comme un job traçable, pas comme une simple conversion synchrone.
Le flux recommandé
- Votre serveur sélectionne un template ou une version précise.
- Il construit un payload uniquement avec les données utiles au document.
- L’API valide la requête et crée un job.
- Un worker produit le document en arrière-plan.
- Votre application suit l’état du job ou reçoit un webhook.
- Le fichier est téléchargé via une URL à durée limitée.
{
"templateVersionId": "tv_01JDC12",
"data": {
"invoice": { "number": "INV-2048", "date": "2026-09-08" },
"customer": { "name": "Acme Labs" },
"total": 4850,
"currency": "EUR"
}
}
Cette séparation protège votre logique métier. Le template décide de la présentation ; votre application reste responsable des données et de leur vérité.
Pourquoi privilégier un job asynchrone
Un rendu PDF dépend du poids du template, des images, des polices et du moteur de rendu. Bloquer une requête HTTP jusqu’au résultat augmente le risque de timeout et rend les erreurs difficiles à rejouer.
Un job asynchrone peut exposer quatre états simples : pending, processing, completed et failed. Votre application conserve l’identifiant du job avec sa propre référence métier. En cas d’incident, vous pouvez relier un document à l’appel qui l’a produit.
Concevoir les reprises sans doublon
Une relance automatique aveugle peut générer deux factures identiques. Ajoutez une clé d’idempotence ou calculez une empreinte stable à partir de la référence métier, de la version du template et du payload normalisé.
Ne relancez que les erreurs transitoires : indisponibilité réseau, saturation temporaire ou timeout. Une donnée invalide ne deviendra pas valide après cinq essais.
Sécurité minimale
- Gardez la clé API côté serveur.
- Limitez chaque clé aux templates nécessaires.
- Évitez les URL publiques permanentes pour les documents sensibles.
- Définissez une durée de conservation.
- Vérifiez la signature des webhooks avant de leur faire confiance.
- Ne journalisez pas le contenu complet d’un contrat ou d’une facture.
Checklist avant production
- Le payload possède un schéma documenté.
- La version du template est identifiable.
- Chaque job est corrélé à une référence métier.
- Les erreurs définitives et transitoires sont séparées.
- Les webhooks sont idempotents.
- La rétention et la suppression des fichiers sont définies.
- Un retour vers une version stable est possible.
Questions fréquentes
Faut-il retourner directement le PDF ?
Pour un petit document non critique, c’est possible. Pour une chaîne métier, un job asynchrone offre généralement une meilleure observabilité et des reprises plus sûres.
Le template doit-il être envoyé à chaque appel ?
Pas nécessairement. Un template stocké et référencé par identifiant réduit le volume transféré et facilite la gestion des versions. Une version précise rend le résultat plus reproductible.
Où stocker le PDF final ?
Dans un stockage objet privé, avec une URL signée courte. Votre politique de rétention doit dépendre de la sensibilité du document et des obligations de votre activité.