gPdf
Use cases · E-invoicing EU e finance

Fatture elettroniche EU: PDF/A-3 con Factur-X / ZUGFeRD incorporato

Genera e-invoice EN 16931 da JSON: wrapper PDF/A-3 con allegato CII XML incorporato, conforme Factur-X o ZUGFeRD. Verifica gratis entrambi i livelli su gpdf.com/validator/.

Job to be done

Emettere fatture elettroniche conformi EU da un DocumentRequest JSON: un wrapper PDF/A-3 leggibile da un team AP, con allegato CII XML incorporato conforme a EN 16931 che un'autorità fiscale può elaborare automaticamente. Una singola chiamata API deve produrre entrambi, ed entrambi devono validare contro motori di riferimento, non solo contro il checker del vendor.

Why gPdf for this

  • POST /api/v1/e-invoice/render: endpoint unico, restituisce un PDF/A-3 Factur-X o ZUGFeRD in un solo round trip.
  • Wrapper PDF/A-3b emesso automaticamente con namespace XMP corretto, AFRelationship='Alternative' e metadati del file incorporato secondo la baseline Factur-X / ZUGFeRD.
  • EN 16931 CII XML allegato come contenuto strutturato canonico, leggibile dagli strumenti di automazione AP nell'EU.
  • La modalità strict-validation esegue controlli Schematron completi in modo asincrono e restituisce un artifact di report accanto al PDF.
  • Profili di data residency (`eu` / `global` / `auto`) per consentire ai team AP/AR soggetti a GDPR di mantenere gli artifact e-invoice dentro regioni EU.
  • Validator pubblico gratuito su gpdf.com/validator/ esegue veraPDF (lato PDF/A) E Mustang (lato CII XML / EN 16931) in parallelo: verifica indipendente prima del collegamento alla produzione.

Sample request

POST /api/v1/e-invoice/render — richiesta Factur-X minima con CII XML incorporato.

{
  "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 and conformance

  • Factur-X 1.0: specifica congiunta franco-tedesca, obbligatoria per le fatture B2B francesi dal 2026 in modo progressivo.
  • ZUGFeRD 2.x: specifica tedesca, conforme EN 16931; obbligatoria per la ricezione di fatture B2B tedesche dal 2025.
  • EN 16931: modello semantico pan-EU per e-invoice usato come base sia da Factur-X sia da ZUGFeRD.
  • PDF/A-3: formato wrapper di archiviazione richiesto per contenere legalmente un allegato XML incorporato (ISO 19005-3).
  • Verifica: non fidatevi dell'auto-check di un singolo vendor. La verifica indipendente con veraPDF (PDF/A) + Mustang (CII XML) è il pattern di livello audit.

La forma di una e-invoice EU, e perché sono due formati sovrapposti

Una e-invoice EU moderna è due documenti avvolti in un solo file:

  1. Un PDF/A-3 leggibile da persone: numero fattura, righe, totali, branding del fornitore. La specifica PDF/A-3 (ISO 19005-3) è l’unica variante PDF/A che consente allegati file arbitrari dentro il wrapper di archiviazione.
  2. Un allegato EN 16931 CII XML dentro quel PDF: la stessa fattura espressa come dati strutturati che automazione AP, import ERP e sistemi delle autorità fiscali possono elaborare senza OCR.

Factur-X (Francia) e ZUGFeRD (Germania) sono la stessa idea con etichette nazionali diverse. Entrambi allegano un XML EN 16931 Cross-Industry Invoice (CII) a un wrapper PDF/A-3. ZUGFeRD è obbligatorio per la ricezione di fatture B2B tedesche dal 2025; Factur-X entra progressivamente nell’obbligo di emissione B2B in Francia nel 2026-2027.

Se inviate fatture a clienti francesi o tedeschi nel 2026, uno di questi due formati non è più opzionale.

Perché generarlo da zero è doloroso, e perché gPdf è un endpoint unico

Assemblare tutto da zero significa:

  1. Generare i byte PDF (composizione tipografica, font, layout).
  2. Generare separatamente il CII XML, allineato a EN 16931.
  3. Impostare correttamente il namespace XMP PDF/A-3 (urn:factur-x:pdfa:CrossIndustryDocument:invoice:1p0# per Factur-X; il namespace ZUGFeRD 2.x è diverso).
  4. Incorporare l’XML con AFRelationship="Alternative" secondo specifica.
  5. Marcare correttamente il file incorporato nell’array /AF di PDF/A-3.
  6. Verificare il risultato con veraPDF (lato PDF/A) E Mustang (lato CII XML): entrambi devono passare.

Un team tipico sbaglia due volte prima di passare entrambi i motori. La gPdf API riduce tutti e sei i passaggi a una singola chiamata POST /api/v1/e-invoice/render. Voi fornite:

  • settings.e_invoice.standard: factur_x o zugferd
  • settings.e_invoice.xml.content: il vostro CII XML
  • pages[]: il layout visibile della fattura
  • tutto il resto viene emesso automaticamente con i metadati PDF/A-3 corretti.

Consultate il §5 del riferimento E-Invoice API per lo schema completo della richiesta, le modalità di verifica (basic vs strict) e il ciclo di vita asincrono dei job per le esecuzioni strict-validation.

Verificare l’output: il pattern di audit

Un vendor che dice “sì, il nostro PDF passa PDF/A-3” non vale nulla se l’auditor usa i motori di riferimento. Il pattern di livello audit è:

  1. Generare la e-invoice tramite POST /api/v1/e-invoice/render.
  2. Trascinare il PDF risultante nel validator, che esegue:
    • veraPDF: l’implementazione ufficiale di riferimento mantenuta dalla PDF Association. Conformità PDF/A-3.
    • Mustang: progetto open-source tedesco (mustangproject.org) che è il checker di riferimento de-facto per Factur-X / ZUGFeRD: estrae il CII XML incorporato, valida contro Schematron EN 16931 e riporta campo per campo.
  3. Entrambi i report tornano affiancati nella stessa UI. Entrambi devono mostrare “Pass” prima di inviare in produzione all’automazione AP.

Questo pattern conta perché:

  • Un PDF che passa veraPDF ma fallisce Mustang significa che il wrapper è conforme ma l’XML interno è malformato: il sistema AP rifiuta la fattura alla ricezione.
  • Un PDF che passa Mustang ma fallisce veraPDF significa che l’XML è corretto, ma il wrapper di archiviazione non soddisfa PDF/A-3: l’archiviazione di lungo periodo viene rifiutata.
  • Qualsiasi fallimento rompe il flusso end-to-end. Entrambi devono passare.

Il validator è gratuito, non richiede login e produce report JSON che potete associare alle evidenze QA. È lo stesso pattern dual-engine che le società di audit Big Four usano internamente: gPdf lo ospita solo pubblicamente.

Oltre Factur-X / ZUGFeRD

Se state lavorando anche con:

  • FatturaPA (Italia, obbligatoria dal 2019): già nella roadmap del validator.
  • Peppol BIS 3.0 UBL (Nordic / Benelux / sempre più cross-border): roadmap.
  • KSeF (Polonia, obbligatorio 2026): roadmap.

L’endpoint e-invoice di gPdf estenderà la copertura man mano che ciascun formato passa da “early roadmap” a “live nel validator e nel motore di rendering”. La forma resta la stessa: una richiesta JSON, namespace XMP e AFRelationship corretti gestiti internamente, entrambi i motori verificano prima della messa in produzione.

TL;DR

  • Una chiamata API -> PDF/A-3 + CII XML EN 16931 incorporato.
  • Scegliete Factur-X o ZUGFeRD tramite settings.e_invoice.standard.
  • Verificate con validator: veraPDF + Mustang in parallelo, gratis.
  • Entrambi i motori devono passare. La gPdf API è costruita perché passino; il validator è la ricevuta pubblica.

Keep reading