API PDF de facture pour systèmes de facturation et finance
Générez des PDF de facture ordinaires à partir de données de facturation avec JSON Render ou Template Render, tout en gardant la logique fiscale et comptable dans votre système.
/api/v1/pdf/render Transformer les données de facture d'un système de facturation, ERP ou SaaS en PDF de facture lisible, tout en gardant numérotation, taxes, état de paiement et sémantique comptable dans le système appelant.
Quand utiliser cette API
- Vous avez besoin de PDF de facture ordinaires pour clients, reçus, relevés ou exports comptables.
- Votre système détient déjà les numéros de facture, le calcul de taxe, les lignes et l'état de paiement.
- Vous voulez tableaux, totaux, métadonnées et paramètres PDF/A optionnels sans exécuter de navigateur.
- Vous voulez un contrat template_id pour des mises en page de facture répétées.
Ce qu'elle ne remplace pas
- Vous avez besoin d'un package légal de facture électronique comme Factur-X ou ZUGFeRD. Utilisez E-Invoice Render.
- Vous attendez de gPdf qu'il calcule les taxes, valide les règles comptables ou réconcilie les paiements.
- Vous voulez convertir des factures HTML arbitraires au lieu d'utiliser du JSON structuré ou des templates.
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.
/api/v1/e-invoice/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 - en-tête et total de facture minimaux.
{
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Invoice INV-1007",
"style": { "font_size": 18, "font_family": "NotoSans-Regular" }
},
{
"type": "text",
"x": 20,
"y": 42,
"content": "Bill to: Example Customer\nAmount due: USD 245.00",
"style": { "font_size": 11, "font_family": "NotoSans-Regular" }
},
{
"type": "line",
"x1": 20,
"y1": 62,
"x2": 190,
"y2": 62
}
]
}
]
}
Ce que gPdf prend en charge
- Rendu PDF de facture depuis des pages JSON ou des données de template.
- Texte, tableaux, blocs de totaux, pagination, métadonnées et sortie PDF/A optionnelle.
- Template Render pour les mises en page de facture stables utilisées par plusieurs systèmes.
- Réponse PDF binaire et enveloppe d'erreur API cohérente.
Ce que votre système garde
- Numéros de facture, état de paiement, calcul de taxe, remises, avoirs et sens comptable.
- Données client et émetteur, mapping des lignes, devises et règles d'arrondi.
- Rétention, livraison, email, liens de paiement et réconciliation avec le système comptable.
Checklist de production
- Confirmer que chaque champ visible de la facture correspond aux données source de facturation.
- Tester les débordements de lignes, noms client longs, factures multi-pages et totaux.
- Décider si la mise en page relève de JSON Render ou d'un template publié.
- Séparer la génération de PDF de facture ordinaire du packaging légal de facture électronique.
- Stocker les request IDs et noms de fichiers de sortie avec vos enregistrements de facture.
Limites de la promesse
- Les PDF de facture ordinaires ne sont pas équivalents aux obligations légales de facture électronique.
- gPdf génère le document de facture ; il ne calcule pas les taxes ni l'état comptable.
- La sortie Factur-X / ZUGFeRD appartient à POST /api/v1/e-invoice/render.
Factures ordinaires et factures électroniques
Un PDF de facture ordinaire est le document que votre client lit. Il peut être généré depuis JSON Render ou Template Render. Votre système décide le numéro de facture, les taxes, lignes, devise et état de paiement, puis gPdf génère le PDF visible.
Une facture électronique légale est différente. Factur-X et ZUGFeRD combinent
une facture PDF/A-3b lisible avec un XML CII EN 16931 intégré. Utilisez
POST /api/v1/e-invoice/render pour ce package.
Template Render est souvent l’endpoint de production
Les équipes finance veulent rarement que chaque service reconstruise les
coordonnées de facture. Le chemin courant consiste à concevoir la facture une
fois, la publier comme template, puis donner aux appelants un template_id
stable et un schema de données. JSON Render reste utile pour les mises en page
spécifiques, les outils internes et le prototypage de templates.
Garder la logique comptable en amont
gPdf doit recevoir les valeurs finales à afficher, pas des décisions comptables non résolues. Calculez taxes, remises, arrondis, statut de paiement et éligibilité de facture avant d’appeler l’API de rendu. Cela rend la sortie PDF déterministe et garde le système financier comme source de vérité.
FAQ
- Un PDF de facture est-il la même chose qu'une facture électronique ?
- Non. Un PDF de facture ordinaire est une sortie lisible par l'humain. Une facture électronique Factur-X ou ZUGFeRD intègre aussi un XML CII EN 16931 dans une enveloppe PDF/A-3b.
- Quel endpoint utiliser pour des factures répétées ?
- Utilisez Template Render quand la mise en page de facture est stable et que les appelants doivent seulement envoyer template_id plus data. Utilisez JSON Render quand le code possède la mise en page.
- gPdf calcule-t-il les taxes ?
- Non. Votre système de facturation ou de comptabilité calcule taxes, totaux, remises et état de paiement avant d'envoyer les données de rendu.
- Les PDF de facture peuvent-ils utiliser PDF/A ?
- Oui, JSON Render prend en charge les paramètres PDF/A. Utilisez E-Invoice Render spécifiquement quand la facture doit être conditionnée en Factur-X ou ZUGFeRD.