API de facture électronique pour Factur-X et ZUGFeRD PDF/A-3b
Générez des factures électroniques Factur-X et ZUGFeRD PDF/A-3b avec XML CII EN 16931 intégré via l'endpoint public gPdf E-Invoice Render.
/api/v1/e-invoice/render Conditionner un PDF de facture lisible et un XML CII EN 16931 fourni par l'appelant dans une facture électronique Factur-X ou ZUGFeRD PDF/A-3b, validable par des moteurs de référence externes PDF/A et facture électronique.
Quand utiliser cette API
- Vous avez besoin d'une sortie Factur-X ou ZUGFeRD, pas seulement d'un PDF de facture ordinaire.
- Votre système peut fournir un XML CII EN 16931 correct pour la facture.
- Vous avez besoin du packaging PDF/A-3b, des métadonnées de pièce jointe et du câblage XMP de facture électronique.
- Vous voulez utiliser l'endpoint public de capacités pour confirmer les standards et profils pris en charge.
Ce qu'elle ne remplace pas
- Vous avez seulement besoin d'un PDF de facture client ordinaire. Utilisez JSON Render ou Template Render.
- Vous avez besoin d'une sortie native XRechnung, FatturaPA, KSeF, Peppol, ZATCA, NF-e ou GST avant qu'OpenAPI la liste.
- Vous attendez de gPdf qu'il crée un XML de facture juridiquement correct à partir de données métier incomplètes.
Quel endpoint appeler
/api/v1/e-invoice/render
E-Invoice Render est le chemin par défaut pour ce workflow.
/api/v1/e-invoice/capabilities
À 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/e-invoice/render - requête Factur-X PDF/A-3b minimale.
{
"settings": {
"profile": "pdfa-3b",
"e_invoice": {
"standard": "factur_x",
"profile": "en16931",
"document_type": "invoice",
"xml": {
"format": "cii",
"encoding": "utf8",
"content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>"
}
}
},
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Invoice INV-1007",
"style": { "font_size": 16, "font_family": "NotoSans-Regular" }
}
]
}
]
}
Ce que gPdf prend en charge
- Packaging Factur-X ou ZUGFeRD PDF/A-3b via POST /api/v1/e-invoice/render.
- Intégration du XML CII EN 16931 fourni par l'appelant comme fichier associé.
- Métadonnées d'enveloppe PDF/A-3b et câblage XMP propre au standard de facture électronique.
- Découverte des capacités via GET /api/v1/e-invoice/capabilities.
Ce que votre système garde
- Sémantique métier de la facture, règles fiscales, identifiants acheteur/vendeur et exactitude du XML EN 16931.
- Choix de Factur-X ou ZUGFeRD selon le workflow du destinataire.
- Tests d'acceptation externes avec le destinataire, le système AP automation ou le processus de conformité local.
Checklist de production
- Appeler /api/v1/e-invoice/capabilities avant de supposer un standard ou un profil.
- Valider le XML CII EN 16931 avant de l'intégrer.
- Passer la sortie dans /validator/ ou dans votre propre pipeline de moteurs de référence.
- Séparer dans le code la génération de PDF de facture ordinaire et le packaging légal de facture électronique.
- Journaliser request IDs, standard, profil, version source XML et preuves de validation.
Limites de la promesse
- La sortie native publique de facture électronique est Factur-X / ZUGFeRD avec XML CII EN 16931.
- Les autres noms nationaux de facture électronique sont du contexte marché sauf s'ils sont listés comme standards pris en charge par OpenAPI.
- gPdf conditionne le XML fourni par l'appelant ; votre système reste responsable de l'exactitude métier du XML.
Un endpoint pour le package de facture électronique
L’endpoint de facture électronique existe parce que ce workflow n’est pas simplement “générer un PDF de facture”. Il doit produire une enveloppe PDF/A-3b avec les bonnes métadonnées de fichier associé et le XMP propre au standard, tout en intégrant le XML CII EN 16931 fourni par l’appelant.
Appelez POST /api/v1/e-invoice/render quand la sortie requise est Factur-X ou
ZUGFeRD. Utilisez GET /api/v1/e-invoice/capabilities quand votre intégration
veut confirmer les standards, profils, types de documents et formats XML pris en
charge avant d’envoyer du travail.
Ce qui reste hors de gPdf
La sémantique du XML reste sous votre responsabilité. gPdf ne peut pas savoir si un numéro de facture est légal, si un montant de taxe est correct, si un identifiant acheteur correspond au partenaire commercial ou si un destinataire précis acceptera une variante de processus métier. Générez et validez le XML en amont, puis utilisez gPdf pour le packaging PDF/A-3b et le rendu.
Garder les termes roadmap hors des promesses de support natif
Il est valide de discuter XRechnung, FatturaPA, KSeF, Peppol, ZATCA, NF-e ou GST comme contexte marché. Ne présentez pas ces noms comme sorties natives du renderer public sauf si le contrat de capacités OpenAPI les liste.
FAQ
- Quels standards de facture électronique sont une sortie native publique aujourd'hui ?
- La sortie native publique est Factur-X et ZUGFeRD PDF/A-3b avec XML CII EN 16931 intégré. Vérifiez /api/v1/e-invoice/capabilities pour le contrat actuel.
- gPdf génère-t-il le XML EN 16931 pour moi ?
- Non. Votre système fournit le contenu XML. gPdf l'intègre dans l'enveloppe de facture électronique PDF/A-3b avec les métadonnées de pièce jointe requises.
- Puis-je envoyer settings.e_invoice à JSON Render ?
- Non. Le packaging de facture électronique appartient à POST /api/v1/e-invoice/render. La documentation publique précise que settings.e_invoice est spécifique à cette route.
- Comment valider la sortie ?
- Utilisez le validateur gPdf ou votre propre workflow de moteur de référence pour vérifier à la fois la couche PDF/A et la couche XML de facture électronique intégrée.