API de génération PDF par lots pour files et jobs
Générez de nombreux PDF avec des workflows JSON Render ou Template Render compatibles avec les files de jobs, pendant que votre système gère découpage, retries, idempotence et stockage.
/api/v1/template-render Générer de nombreux PDF depuis une file ou un job planifié en découpant le travail en requêtes sûres, en envoyant chaque document ou item de données de template à gPdf, puis en stockant ou livrant le PDF retourné dans votre propre système.
Quand utiliser cette API
- Vous devez générer factures, relevés, étiquettes ou rapports dans un batch planifié ou déclenché par événement.
- Vous avez un template stable et pouvez envoyer plusieurs items de données dans les limites de l'endpoint.
- Vous avez besoin d'un rendu adapté aux files de jobs sans exécuter de workers navigateur.
- Vous pouvez gérer déduplication, retries et stockage de sortie.
Ce qu'elle ne remplace pas
- Vous voulez que gPdf soit votre planificateur de batches, votre file, votre système de stockage ou votre registre d'idempotence.
- Vous avez besoin de headers de rate limit publiés ou d'un contrat serveur de clé d'idempotence.
- Vous voulez une seule requête sans borne pour générer tous les documents d'une campagne.
Quel endpoint appeler
/api/v1/template-render
Template Render est le chemin par défaut pour ce workflow.
/api/v1/pdf/render
À utiliser si le workflow a besoin d'un chemin API lié, d'un contrat de modèle ou d'une recherche de capacités.
Requête minimale
POST /api/v1/template-render - petit lot avec deux items de données de facture.
{
"template_id": "invoice",
"data": [
{
"invoice_number": "INV-2026-101",
"date_of_issue": "2026-05-29",
"bill_to_name": "Buyer A",
"subtotal": "$50.00",
"total": "$50.00",
"amount_due": "$50.00",
"items": []
},
{
"invoice_number": "INV-2026-102",
"date_of_issue": "2026-05-29",
"bill_to_name": "Buyer B",
"subtotal": "$75.00",
"total": "$75.00",
"amount_due": "$75.00",
"items": []
}
]
}
Ce que gPdf prend en charge
- Rendu PDF pour chaque requête JSON Render ou Template Render.
- Tableaux de données Template Render dans les limites publiques documentées.
- Réponses de rendu stateless et rapides, adaptées aux workers de file.
- Comportement partagé de request ID et d'enveloppe d'erreur.
Ce que votre système garde
- Conception de file, découpage, concurrence, retries, déduplication et stockage de sortie.
- Sélection des objets métier, choix du template et workflow de livraison.
- Politique de backoff, alerting et reprise après échec partiel.
Checklist de production
- Découper le travail pour que chaque requête reste dans les limites documentées d'items et de payload.
- Générer un X-Request-Id par requête et le mapper à votre ID de job.
- Réessayer uniquement les échecs réseau ou 5xx avec backoff exponentiel borné.
- Ne pas réessayer les échecs de validation 4xx sans modifier le payload.
- Stocker les PDF de sortie ou les données source selon votre politique de rétention.
Limites de la promesse
- gPdf est l'API de rendu, pas la couche de file ni de stockage.
- L'API publique ne publie pas aujourd'hui de headers de rate limit ni de clés d'idempotence côté serveur.
- Votre système doit rendre les retries sûrs.
La génération par lots est un pattern d’intégration
La génération PDF par lots n’est pas un endpoint séparé. C’est la façon dont votre file utilise les API publiques de rendu. Gardez les jobs petits, observables et sûrs à réessayer.
Pour les mises en page répétées, Template Render fournit généralement le contrat le plus net. Pour les documents programmatiques avec mises en page spécifiques, JSON Render reste disponible.
Choix de l’endpoint
L’appel par défaut utilise /api/v1/template-render. Utilisez JSON Render tant que le layout évolue ou que l’appelant décrit toute la page. Une fois le layout approuvé, publiez-le comme template et envoyez seulement les données métier via Template Render.
Réservez E-Invoice Render aux paquets Factur-X / ZUGFeRD PDF/A-3b avec XML EN 16931 CII embarqué. Les PDF opérationnels, étiquettes, reçus et rapports ordinaires ne doivent pas être traités comme un flux de facture électronique.
Validation avant production
Validez API de génération PDF par lots avec des données réelles et les systèmes qui consommeront le PDF. Conservez les request IDs, les sorties rendues et les preuves d’acceptation pour le support, l’audit et les réimpressions. gPdf rend le PDF ; les règles métier, le routage externe, la fiscalité, les transporteurs et la conformité marketplace restent dans votre système.
FAQ
- gPdf fournit-il une API de job batch ?
- Aucun planificateur batch séparé n'est exposé. Appelez JSON Render ou Template Render depuis votre propre file ou système de workers.
- Template Render peut-il accepter plusieurs items de données ?
- Oui, dans les limites de l'endpoint public. Découpez les jobs plus volumineux en plusieurs requêtes.
- Qui gère les retries ?
- Votre système gère retries, backoff, déduplication et idempotence. gPdf répercute les request IDs pour la traçabilité.
- Puis-je générer beaucoup de mises en page différentes dans une seule requête ?
- Utilisez des requêtes séparées quand les mises en page ou les template IDs diffèrent. Gardez chaque requête simple et traçable.