API JSON vers PDF pour génération documentaire structurée
Transformez des payloads DocumentRequest JSON structurés en PDF avec pages, coordonnées, texte, tableaux, codes-barres, métadonnées et paramètres PDF/A.
/api/v1/pdf/render Convertir des données applicatives structurées en documents PDF déterministes sans exécuter de navigateur, livrer du HTML/CSS ou stocker des fichiers client. Votre système envoie pages, éléments, coordonnées, settings et contenu métier ; gPdf retourne une réponse application/pdf.
Quand utiliser cette API
- Votre backend possède déjà des données structurées et a besoin d'une réponse PDF.
- Vous voulez pages, coordonnées, éléments, codes-barres et settings explicites plutôt qu'une mise en page HTML.
- Vous avez besoin d'une sortie répétable pour factures, étiquettes, rapports, relevés ou dossiers générés.
- Vous voulez tester les payloads dans le Playground avant de mettre un token en production.
Ce qu'elle ne remplace pas
- Vous avez besoin d'une conversion HTML-to-PDF arbitraire. gPdf utilise du JSON DocumentRequest, pas un DOM de navigateur.
- Votre équipe veut un contrat template_id stable. Utilisez Template Render après publication de la mise en page.
- Vous avez besoin du packaging de facture électronique Factur-X ou ZUGFeRD. Utilisez l'endpoint E-Invoice Render.
Quel endpoint appeler
/api/v1/pdf/render
JSON Render est le chemin par défaut pour ce workflow.
/api/v1/template-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/pdf/render - DocumentRequest JSON d'une page.
{
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Hello from gPdf",
"style": {
"font_size": 18,
"font_family": "NotoSans-Regular"
}
}
]
}
]
}
Ce que gPdf prend en charge
- Rendu DocumentRequest depuis pages et éléments.
- Texte, tableaux, images, codes-barres vectoriels, lignes, formes, filigranes, métadonnées et paramètres PDF/A.
- Embedding et fallback de polices pour latin, CJK, scripts compatibles emoji et autres scripts pris en charge.
- Réponse PDF binaire avec enveloppe d'erreur gPdf partagée en cas d'échec.
Ce que votre système garde
- Données métier, mapping de champs et sémantique documentaire.
- Request IDs, stratégie de retry et d'idempotence, nommage de fichiers et stockage après réponse.
- Toute règle fiscale, de facture, transporteur, conformité ou client avant le rendu.
Checklist de production
- Générer et transmettre un X-Request-Id pour la traçabilité.
- Valider les payloads contre OpenAPI ou la documentation avant d'envoyer du trafic live.
- Garder l'URL de base API configurable et stocker le bearer token hors du code source.
- Décider si la sortie doit être en mode inline ou attachment.
- Ajouter des tests golden-PDF pour les mises en page critiques afin de rendre visibles les changements de template ou de données.
Limites de la promesse
- Ce n'est pas du HTML-to-PDF et Chromium n'est pas exécuté.
- L'API génère le document que vous décrivez ; elle n'infère pas de sens légal ou métier depuis vos données.
- Pour les mises en page répétées, Template Render est généralement le meilleur contrat public.
Où s’insère le workflow JSON Render
JSON Render est le chemin public de rendu le plus bas niveau. Votre application envoie directement la structure du document : taille de page, éléments, coordonnées, styles, métadonnées, mode de sortie et paramètres PDF/A optionnels. C’est la bonne couche quand la mise en page du document est générée par code ou quand votre équipe veut un contrôle précis du PDF.
Le contrat API est explicite. Si votre système envoie un élément texte, gPdf génère un élément texte. S’il envoie un élément code-barres, gPdf dessine le code-barres en contenu PDF vectoriel. gPdf ne lit pas l’intention métier dans le payload et ne décide pas si un numéro de facture, une valeur de tracking transporteur ou un champ fiscal est correct.
Quand passer à Template Render
Si la même mise en page est utilisée régulièrement par plusieurs systèmes,
publiez-la comme template et appelez POST /api/v1/template-render avec
template_id plus data[]. Cela sort la responsabilité de mise en page de
chaque appelant et donne à votre ERP, OMS, WMS ou backend SaaS un contrat de
champs stable.
Utilisez JSON Render pour la création de mise en page, les documents ponctuels et les documents programmatiques. Utilisez Template Render quand la mise en page est figée et que seules les données métier changent à chaque requête.
Forme de production
En production, traitez une requête PDF comme tout autre appel API important : incluez un request ID, définissez un timeout, rendez les retries idempotents, journalisez les métadonnées de réponse et stockez le PDF retourné seulement dans votre propre système si une rétention est requise. Le chemin de rendu gPdf est stateless après une réponse de rendu standard.
FAQ
- Est-ce une API HTML-to-PDF ?
- Non. gPdf accepte un DocumentRequest JSON structuré avec pages, éléments, coordonnées et settings. Il n'exécute pas de navigateur ni de HTML/CSS arbitraire.
- Quel endpoint dois-je appeler en premier ?
- Commencez par POST /api/v1/pdf/render quand vous voulez contrôler directement la mise en page. Passez à POST /api/v1/template-render quand la mise en page doit devenir un contrat template_id stable.
- L'API retourne-t-elle directement un PDF ?
- Oui. Un rendu réussi retourne application/pdf. Les erreurs utilisent l'enveloppe JSON partagée avec un code API-XXX et req_id.
- Puis-je tester sans construire une intégration ?
- Utilisez le Playground gPdf pour tester les payloads JSON de façon interactive, puis déplacez la même forme DocumentRequest dans votre client backend.