E-Invoice API für Factur-X und ZUGFeRD PDF/A-3b
Erzeugen Sie Factur-X- und ZUGFeRD-E-Rechnungen als PDF/A-3b mit eingebettetem EN 16931 CII XML über den öffentlichen gPdf E-Invoice-Endpunkt.
/api/v1/e-invoice/render Verpacken Sie ein menschenlesbares Rechnungs-PDF und vom Aufrufer bereitgestelltes EN 16931 CII XML in eine Factur-X- oder ZUGFeRD-E-Rechnung als PDF/A-3b, die durch externe PDF/A- und E-Rechnungs-Referenzengines validiert werden kann.
Wann diese API passt
- Sie benötigen Factur-X- oder ZUGFeRD-Ausgabe, nicht nur ein normales Rechnungs-PDF.
- Ihr System kann korrektes EN 16931 CII XML für die Rechnung bereitstellen.
- Sie benötigen PDF/A-3b-Paketierung, Metadaten für Anhänge und E-Invoice-XMP-Verknüpfung.
- Sie möchten über den öffentlichen Capabilities-Endpunkt prüfen, welche Standards und Profile unterstützt werden.
Was sie nicht ersetzt
- Sie benötigen nur ein normales Kundenrechnungs-PDF. Nutzen Sie JSON Render oder Template Render.
- Sie benötigen native Ausgabe für XRechnung, FatturaPA, KSeF, Peppol, ZATCA, NF-e oder GST, bevor OpenAPI diese unterstützt.
- Sie erwarten, dass gPdf aus unvollständigen Geschäftsdaten rechtlich korrektes Rechnungs-XML erzeugt.
Welchen Endpoint aufrufen
/api/v1/e-invoice/render
E-Invoice Render ist der Standardpfad für diesen Workflow.
/api/v1/e-invoice/capabilities
Nutzen Sie dies, wenn der Workflow den zugehörigen API-Pfad, einen Template-Vertrag oder eine Capability-Abfrage braucht.
Minimaler Request
POST /api/v1/e-invoice/render - minimaler Factur-X-PDF/A-3b-Request.
{
"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" }
}
]
}
]
}
Was gPdf übernimmt
- Factur-X- oder ZUGFeRD-PDF/A-3b-Paketierung über POST /api/v1/e-invoice/render.
- Einbettung des vom Aufrufer bereitgestellten EN 16931 CII XML als zugehörige Datei.
- PDF/A-3b-Wrapper-Metadaten und standardspezifische E-Invoice-XMP-Verknüpfung.
- Capabilities-Abfrage über GET /api/v1/e-invoice/capabilities.
Was Ihr System verantwortet
- Rechnungslogik, Steuerregeln, Käufer- und Verkäuferkennungen sowie die Korrektheit des EN 16931 XML.
- Die Entscheidung, ob Factur-X oder ZUGFeRD für den Empfänger-Workflow passend ist.
- Externe Abnahmetests mit Empfänger, AP-Automatisierungssystem oder lokalem Compliance-Prozess.
Produktions-Checkliste
- Rufen Sie /api/v1/e-invoice/capabilities auf, bevor Sie einen Standard oder ein Profil voraussetzen.
- Validieren Sie das EN 16931 CII XML, bevor Sie es einbetten.
- Prüfen Sie die Ausgabe über /validator/ oder Ihre eigene Referenzengine-Pipeline.
- Trennen Sie normales Rechnungs-PDF-Rendering und rechtliche E-Rechnungs-Paketierung im Code.
- Protokollieren Sie Request IDs, Standard, Profil, XML-Quellversion und Validierungsnachweise.
Aussagegrenzen
- Native öffentliche E-Invoice-Ausgabe ist Factur-X / ZUGFeRD mit EN 16931 CII XML.
- Andere nationale E-Rechnungsnamen sind Marktkontext, solange sie im OpenAPI-Vertrag nicht als unterstützte Standards aufgeführt sind.
- gPdf paketiert vom Aufrufer bereitgestelltes XML; Ihr System bleibt für die geschäftliche Korrektheit des XML verantwortlich.
Ein Endpunkt für das E-Invoice-Paket
Der E-Invoice-Endpunkt existiert, weil dieser Workflow nicht nur „ein Rechnungs-PDF rendern“ ist. Er muss einen PDF/A-3b-Wrapper mit den korrekten Metadaten für die zugehörige Datei und standardspezifischem XMP erzeugen, während das vom Aufrufer bereitgestellte EN 16931 CII XML eingebettet wird.
Rufen Sie POST /api/v1/e-invoice/render auf, wenn die benötigte Ausgabe
Factur-X oder ZUGFeRD ist. Nutzen Sie GET /api/v1/e-invoice/capabilities,
wenn Ihre Integration vor dem Senden von Arbeit unterstützte Standards, Profile,
Dokumenttypen und XML-Formate bestätigen soll.
Was außerhalb von gPdf bleibt
Die XML-Semantik bleibt Ihre Verantwortung. gPdf kann nicht wissen, ob eine Rechnungsnummer rechtlich zulässig ist, ein Steuerbetrag stimmt, eine Käuferkennung zum Geschäftspartner passt oder ein bestimmter Empfänger eine Prozessvariante akzeptiert. Erzeugen und validieren Sie das XML vorgelagert, und nutzen Sie gPdf anschließend für PDF/A-3b-Paketierung und Rendering.
Roadmap-Begriffe nicht als native Unterstützung darstellen
XRechnung, FatturaPA, KSeF, Peppol, ZATCA, NF-e oder GST können als Marktkontext sinnvoll sein. Stellen Sie diese Namen aber nicht als native öffentliche Renderer-Ausgabe dar, solange der OpenAPI-Capabilities-Vertrag sie nicht aufführt.
FAQ
- Welche E-Invoice-Standards sind heute native öffentliche Ausgabe?
- Die native öffentliche Ausgabe ist Factur-X und ZUGFeRD PDF/A-3b mit eingebettetem EN 16931 CII XML. Prüfen Sie /api/v1/e-invoice/capabilities für den aktuellen Vertrag.
- Erzeugt gPdf das EN 16931 XML für mich?
- Nein. Ihr System liefert den XML-Inhalt. gPdf paketiert ihn mit den erforderlichen Anhang-Metadaten in den PDF/A-3b-E-Invoice-Wrapper.
- Kann ich settings.e_invoice an JSON Render senden?
- Nein. E-Invoice-Paketierung gehört auf POST /api/v1/e-invoice/render. Die öffentlichen Docs beschreiben settings.e_invoice als routenspezifisch.
- Wie sollte ich die Ausgabe validieren?
- Nutzen Sie den gPdf Validator oder Ihren eigenen Referenzengine-Workflow, um sowohl die PDF/A-Schicht als auch die eingebettete E-Invoice-XML-Schicht zu prüfen.