E-Invoice API voor Factur-X en ZUGFeRD PDF/A-3b
Genereer Factur-X- en ZUGFeRD-PDF/A-3b-e-invoices met ingebedde EN 16931 CII XML via het publieke gPdf E-Invoice-endpoint.
/api/v1/e-invoice/render Verpak een leesbare factuur-PDF en door het aanroepende systeem aangeleverde EN 16931 CII XML tot een Factur-X- of ZUGFeRD-PDF/A-3b-e-invoice die door externe PDF/A- en E-Invoice-referentie-engines kan worden gecontroleerd.
Wanneer deze API past
- U hebt Factur-X- of ZUGFeRD-output nodig, niet alleen een gewone factuur-PDF.
- Uw systeem kan correcte EN 16931 CII XML voor de factuur aanleveren.
- U hebt PDF/A-3b-packaging, metadata voor het gekoppelde bestand en E-Invoice-XMP-koppeling nodig.
- U wilt via het publieke capabilities-endpoint bevestigen welke standaarden en profielen worden ondersteund.
Wat dit niet vervangt
- U hebt alleen een gewone factuur-PDF voor klanten nodig. Gebruik JSON Render of Template Render.
- U hebt native XRechnung-, FatturaPA-, KSeF-, Peppol-, ZATCA-, NF-e- of GST-output nodig voordat OpenAPI die vermeldt.
- U verwacht dat gPdf juridisch correcte factuur-XML maakt uit onvolledige bedrijfsdata.
Welk endpoint aanroepen
/api/v1/e-invoice/render
E-Invoice Render is het standaardpad voor deze workflow.
/api/v1/e-invoice/capabilities
Gebruik dit wanneer de workflow een verwant API-pad, templatecontract of capability lookup nodig heeft.
Minimale request
POST /api/v1/e-invoice/render - minimale 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" }
}
]
}
]
}
Wat gPdf afhandelt
- Factur-X- of ZUGFeRD-PDF/A-3b-packaging via POST /api/v1/e-invoice/render.
- Het inbedden van door het aanroepende systeem aangeleverde EN 16931 CII XML als gekoppeld bestand.
- PDF/A-3b-wrappermetadata en standaardspecifieke E-Invoice-XMP-koppeling.
- Capabilities-discovery via GET /api/v1/e-invoice/capabilities.
Wat uw systeem beheert
- Zakelijke betekenis van de factuur, belastingregels, koper- en verkoperidentificatoren en juistheid van de EN 16931 XML.
- De keuze of Factur-X of ZUGFeRD past bij het acceptatieproces van de ontvanger.
- Externe acceptatietests met de ontvanger, het AP-automatiseringssysteem of het lokale nalevingsproces.
Productiechecklist
- Roep /api/v1/e-invoice/capabilities aan voordat u een standaard of profiel aanneemt.
- Controleer de EN 16931 CII XML voordat u deze inbedt.
- Haal de output door /validator/ of uw eigen pipeline met referentie-engines.
- Houd gewone factuur-PDF-generatie en juridische E-Invoice-packaging gescheiden in code.
- Log request-ID's, standaard, profiel, XML-bronversie en controlegegevens.
Grenzen van de claim
- Native publieke E-Invoice-output is Factur-X / ZUGFeRD met EN 16931 CII XML.
- Andere nationale E-Invoice-namen zijn marktcontext tenzij OpenAPI ze als ondersteunde standaarden vermeldt.
- gPdf verpakt door het aanroepende systeem aangeleverde XML; uw systeem blijft verantwoordelijk voor de zakelijke juistheid van de XML.
Eén endpoint voor het E-Invoice-pakket
Het E-Invoice-endpoint bestaat omdat dit proces meer is dan alleen een factuur-PDF renderen. Het moet een PDF/A-3b-wrapper produceren met de juiste metadata voor het gekoppelde bestand en standaardspecifieke XMP, terwijl de door het aanroepende systeem aangeleverde EN 16931 CII XML wordt ingebed.
Roep POST /api/v1/e-invoice/render aan wanneer de vereiste output Factur-X of
ZUGFeRD is. Gebruik GET /api/v1/e-invoice/capabilities wanneer uw integratie
ondersteunde standaarden, profielen, documenttypen en XML-formaten wil
bevestigen voordat werk wordt verzonden.
Wat buiten gPdf blijft
De XML-semantiek blijft uw verantwoordelijkheid. gPdf kan niet weten of een factuurnummer juridisch correct is, een belastingbedrag klopt, een koperidentificator bij de handelspartner past of een specifieke ontvanger een variant van het bedrijfsproces accepteert. Genereer en controleer de XML upstream en gebruik gPdf daarna voor PDF/A-3b-packaging en rendering.
Houd roadmap-termen buiten claims over native ondersteuning
Het is geldig om XRechnung, FatturaPA, KSeF, Peppol, ZATCA, NF-e of GST als marktcontext te bespreken. Presenteer die namen niet als native publieke renderoutput tenzij het OpenAPI-capabilities-contract ze vermeldt.
FAQ
- Welke E-Invoice-standaarden zijn vandaag native publieke output?
- De publieke native output is Factur-X en ZUGFeRD PDF/A-3b met ingebedde EN 16931 CII XML. Controleer /api/v1/e-invoice/capabilities voor het actuele contract.
- Genereert gPdf de EN 16931 XML voor mij?
- Nee. Uw systeem levert de XML-inhoud aan. gPdf verpakt deze in de PDF/A-3b-E-Invoice-wrapper met de vereiste metadata voor het gekoppelde bestand.
- Kan ik settings.e_invoice naar JSON Render sturen?
- Nee. E-Invoice-packaging hoort thuis op POST /api/v1/e-invoice/render. De publieke documentatie vermeldt dat settings.e_invoice routespecifiek is.
- Hoe moet ik de output controleren?
- Gebruik de gPdf-validator of uw eigen proces met referentie-engines om zowel de PDF/A-laag als de ingebedde E-Invoice-XML-laag te controleren.