gPdf
Gebruiksscenario's · EU e-facturatie en finance

EU e-facturen: PDF/A-3 met ingesloten Factur-X / ZUGFeRD

Genereer EN 16931-e-facturen vanuit JSON: PDF/A-3-wrapper met ingesloten CII XML-bijlage, conform Factur-X of ZUGFeRD. Verifieer beide lagen gratis op gpdf.com/validator/.

Uit te voeren taak

Geef EU-conforme elektronische facturen uit vanuit een JSON DocumentRequest: een PDF/A-3-wrapper die een AP-team kan lezen, met een ingesloten CII XML-bijlage conform EN 16931 die een belastingautoriteit machinaal kan verwerken. Eén API-call moet beide produceren, en beide moeten valideren tegen referentie-engines, niet alleen tegen de controle van de leverancier zelf.

Waarom gPdf hiervoor past

  • POST /api/v1/e-invoice/render: één endpoint dat in één round trip een Factur-X- of ZUGFeRD-PDF/A-3 retourneert.
  • PDF/A-3b-wrapper automatisch uitgegeven met de juiste XMP namespace, AFRelationship='Alternative' en embedded-file metadata volgens de Factur-X / ZUGFeRD-baseline.
  • EN 16931 CII XML gekoppeld als canonieke gestructureerde bijlage, leesbaar voor AP-automatiseringstools in de EU.
  • Strikte validatiemodus draait volledige Schematron-controles asynchroon en retourneert naast de PDF een rapportartifact.
  • Dataresidentieprofielen (`eu` / `global` / `auto`) zodat AP/AR-teams die onder GDPR vallen e-factuurartifacts binnen EU-regio's kunnen houden.
  • Gratis publieke validator op gpdf.com/validator/ draait veraPDF (PDF/A-kant) en Mustang (CII XML / EN 16931-kant) parallel: onafhankelijke verificatie voordat u productie aansluit.

Voorbeeldrequest

POST /api/v1/e-invoice/render - minimale Factur-X-request met ingesloten CII XML.

{
  "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": [] }
  ]
}

Compliance en conformiteit

  • Factur-X 1.0: gezamenlijke Frans-Duitse specificatie, verplicht voor Franse B2B-facturen vanaf 2026 (gefaseerd).
  • ZUGFeRD 2.x: Duitse specificatie, conform EN 16931; verplicht voor Duitse B2B-ontvangst van facturen vanaf 2025.
  • EN 16931: het pan-Europese semantische model voor e-facturen dat zowel Factur-X als ZUGFeRD verpakt.
  • PDF/A-3: het bewaarwrapperformaat dat nodig is om legaal een ingesloten XML-bijlage te bevatten (ISO 19005-3).
  • Verificatie: vertrouw niet op één zelfcontrole van een leverancier. Onafhankelijke verificatie met veraPDF (PDF/A) plus Mustang (CII XML) is het auditwaardige patroon.

De vorm van een EU e-factuur en waarom twee formaten worden gestapeld

Een moderne EU e-factuur is twee documenten verpakt in één bestand:

  1. Een PDF/A-3 die een mens kan lezen: factuurnummer, regels, totalen en branding van de leverancier. De PDF/A-3-specificatie (ISO 19005-3) is de enige PDF/A-variant die willekeurige bestandsbijlagen binnen de bewaarwrapper toestaat.
  2. Een EN 16931 CII XML-bijlage binnen die PDF: dezelfde factuur uitgedrukt als gestructureerde data die AP-automatisering, ERP-imports en systemen van belastingautoriteiten zonder OCR kunnen parseren.

Factur-X (Frankrijk) en ZUGFeRD (Duitsland) zijn hetzelfde idee met verschillende nationale labels. Beide koppelen EN 16931 Cross-Industry Invoice (CII) XML aan een PDF/A-3-wrapper. ZUGFeRD is sinds 2025 verplicht voor Duitse B2B-ontvangst van facturen; Factur-X wordt in 2026-2027 gefaseerd verplicht voor B2B-uitgifte in Frankrijk.

Als u in 2026 facturen naar Franse of Duitse klanten stuurt, is een van deze twee formaten niet langer optioneel.

Waarom zelf genereren pijnlijk is en waarom gPdf één endpoint is

Dit vanaf nul samenstellen betekent:

  1. PDF-bytes genereren: typografie, fonts en layout.
  2. De CII XML apart genereren en afstemmen op EN 16931.
  3. De PDF/A-3 XMP namespace correct zetten (urn:factur-x:pdfa:CrossIndustryDocument:invoice:1p0# voor Factur-X; de ZUGFeRD 2.x namespace verschilt).
  4. De XML insluiten met AFRelationship="Alternative" volgens de specificatie.
  5. Het ingesloten bestand correct markeren in de /AF array van PDF/A-3.
  6. Het resultaat verifiëren met veraPDF (PDF/A-kant) en Mustang (CII XML-kant): beide moeten slagen.

Een gemiddeld team maakt dit twee keer verkeerd voordat het door beide engines komt. De gPdf API brengt alle zes stappen terug tot één POST /api/v1/e-invoice/render call. U levert:

  • settings.e_invoice.standard: factur_x of zugferd
  • settings.e_invoice.xml.content: uw CII XML
  • pages[]: de zichtbare factuurlayout
  • de rest wordt automatisch uitgegeven met de juiste PDF/A-3-metadata.

Zie §5 van de E-Invoice API-referentie voor het volledige requestschema, validatiemodi (basic vs strict) en de asynchrone joblevenscyclus voor strikte validatieruns.

De output verifiëren: het auditpatroon

Een leverancier die zegt “ja, onze PDF voldoet aan PDF/A-3” is niets waard als de auditor de referentie-engines gebruikt. Het auditwaardige patroon is:

  1. Genereer de e-factuur via POST /api/v1/e-invoice/render.
  2. Plaats de resulterende PDF in validator. Die draait:
    • veraPDF: de officiële referentie-implementatie die wordt onderhouden door de PDF Association. PDF/A-3-conformiteit.
    • Mustang: open-source Duits project (mustangproject.org) dat de de-facto Factur-X / ZUGFeRD-referentiechecker is; extraheert de ingesloten CII XML, valideert tegen EN 16931 Schematron en rapporteert veld voor veld.
  3. Beide rapporten verschijnen naast elkaar in dezelfde UI. Beide moeten “Pass” tonen voordat u naar productie-AP-automatisering gaat.

Dit patroon telt omdat:

  • Een PDF die door veraPDF komt maar faalt in Mustang heeft een conforme wrapper maar misvormde XML binnenin; het AP-systeem weigert de factuur bij ontvangst.
  • Een PDF die door Mustang komt maar faalt in veraPDF heeft correcte XML, maar de bewaarwrapper voldoet niet aan PDF/A-3; langetermijnbewaring wordt geweigerd.
  • Elke fout breekt de end-to-end stroom. Beide moeten slagen.

De validator is gratis, vereist geen login en produceert JSON-rapporten die u aan uw QA-bewijs kunt koppelen. Het is hetzelfde dual-engine patroon dat Big Four-auditkantoren intern gebruiken; gPdf host het alleen publiek.

Verder dan Factur-X / ZUGFeRD

Als u ook werkt met:

  • FatturaPA (Italië, verplicht sinds 2019): staat al op de validator-roadmap.
  • Peppol BIS 3.0 UBL (Noordse landen / Benelux / steeds vaker grensoverschrijdend): roadmap.
  • KSeF (Polen, verplicht in 2026): roadmap.

Het e-factuurendpoint van gPdf breidt de dekking uit naarmate elk formaat van “vroege roadmap” naar “live in de validator en de PDF-generator” gaat. De vorm blijft gelijk: één JSON-request, de juiste XMP namespace en AFRelationship intern afgehandeld, beide engines verifiëren voordat u live gaat.

TL;DR

  • Eén API-call -> PDF/A-3 plus ingesloten EN 16931 CII XML.
  • Kies Factur-X of ZUGFeRD via settings.e_invoice.standard.
  • Verifieer met validator: veraPDF plus Mustang parallel, gratis.
  • Beide engines moeten slagen. De gPdf API is gebouwd zodat ze dat doen; de validator is het publieke bewijsstuk.

Verder lezen