/ 
PDF-FacturX-0.01
/ README.md

PDF::FacturX

CI CPAN License: Artistic 2.0

A Perl module to generate Factur-X / ZUGFeRD-compliant PDF/A-3 invoices (Franco-German hybrid PDF + XML standard, aligned with European Norm EN 16931).

Un module Perl pour générer des factures PDF/A-3 conformes Factur-X / ZUGFeRD (norme franco-allemande hybride PDF + XML, alignée sur la norme européenne EN 16931).

Table of contents / Sommaire

What is Factur-X / Qu'est-ce que Factur-X

English

Factur-X is the joint Franco-German standard for hybrid electronic invoicing, jointly published by:

A Factur-X document is a single PDF/A-3 file containing two payloads:

  1. A human-readable PDF rendering of the invoice (any visual layout)
  2. A structured XML payload following the UN/CEFACT Cross Industry Invoice (CII) syntax, attached to the PDF as an associated file (AFRelationship = /Data)

Factur-X is the reference format for the French B2B e-invoicing reform mandated by article 153 of the 2020 amended finance law (Loi de finances rectificative pour 2020), with mandatory rollout from 2026 to 2027. It is also widely deployed in Germany alongside XRechnung (the public-sector profile) for B2G and B2B exchanges.

Français

Factur-X est la norme franco-allemande de facturation électronique hybride, co-publiée par :

Un document Factur-X est un fichier PDF/A-3 unique contenant deux charges utiles :

  1. Un rendu PDF lisible par l'humain de la facture (toute mise en page)
  2. Une charge XML structurée conforme à la syntaxe UN/CEFACT Cross Industry Invoice (CII), attachée au PDF en tant que fichier associé (AFRelationship = /Data)

Factur-X est le format de référence pour la réforme française de la facturation électronique B2B prévue par l'article 153 de la loi de finances rectificative pour 2020, avec déploiement obligatoire entre 2026 et 2027. Il est également largement déployé en Allemagne aux côtés de XRechnung (profil secteur public) pour les échanges B2G et B2B.

Profiles / Profils

Factur-X 1.0.8 defines five conformance profiles. This module supports the first four (the most widely used). EXTENDED is on the roadmap.

| Profile | Lines | Tax breakdown | Payment | EN 16931 compliant | |-------------|:-----:|:-------------:|:-------:|:------------------:| | minimum | no | no | no | no | | basicwl | no | yes | yes | yes* | | basic | yes | yes | yes | yes | | en16931 | yes | yes | yes | yes | | extended | — | — | — | — |

* "WL" = Without Lines: header data only with VAT recap.

Installation

Prerequisites / Prérequis

# Ubuntu / Debian
sudo apt-get install ghostscript libxml2-dev

# macOS (Homebrew)
brew install ghostscript libxml2

From CPAN (when published)

cpanm PDF::FacturX

From source / Depuis les sources

git clone https://github.com/huguesmax/PDF-FacturX.git
cd PDF-FacturX
cpanm --installdeps .
perl Makefile.PL
make
make test
make install

Usage

English — minimal example

use PDF::FacturX qw(generate);

my ($ok, $msg) = generate(
    pdf_in  => 'invoice-source.pdf',   # any visual PDF
    pdf_out => 'invoice-facturx.pdf',  # PDF/A-3 with XML attached
    profile => 'en16931',
    invoice => {
        number   => 'FA-2026-0042',
        date     => '2026-04-19',
        due_date => '2026-05-19',
        currency => 'EUR',
        seller   => {
            name      => 'Acme SARL',
            siret     => '12345678901234',
            vat       => 'FR12345678901',
            address_1 => '1 rue de la Paix',
            postcode  => '75001',
            city      => 'Paris',
            country   => 'FR',
        },
        buyer => {
            name      => 'Kunde GmbH',
            address_1 => 'Hauptstrasse 1',
            postcode  => '10115',
            city      => 'Berlin',
            country   => 'DE',
        },
        lines => [
            { name => 'Consulting', qty => 8, unit_price => 125,
              vat_rate => 20, vat_cat => 'S' },
        ],
        payment => {
            terms => 'Net 30',
            iban  => 'FR7612345678901234567890123',
            bic   => 'BNPAFRPP',
        },
    },
    title  => 'Invoice FA-2026-0042',
    author => 'Acme SARL',
);
die "Factur-X generation failed: $msg" unless $ok;

Français — exemple minimal

Identique à l'exemple ci-dessus. Les messages d'erreur émis par la validation interne sont en français.

Lower-level API / API bas niveau

# Just build the XML (no PDF embedding)
use PDF::FacturX::XML qw(build_xml validate_xml);
my $xml = build_xml(\%invoice, 'basic');
my ($ok, $msg) = validate_xml($xml, 'basic');

# Just embed an existing XML into a PDF/A-3
use PDF::FacturX::Embed qw(embed_xml_pdfa3);
embed_xml_pdfa3(
    pdf_in  => 'src.pdf',
    xml     => $xml_string,
    pdf_out => 'out.pdf',
    profile => 'basic',
);

Invoice hash schema / Schéma du hash facture

| Field / Champ | Type | Required / Requis | Notes | |--------------------------|----------|-----------------------|---------------------------------------------------| | number | string | yes | invoice number | | date | string | yes | ISO YYYY-MM-DD | | due_date | string | no | ISO YYYY-MM-DD | | currency | string | no (default EUR) | ISO 4217, three uppercase letters | | type_code | int | no (default 380) | 380 = invoice, 381 = credit note | | notes | string | no | free text | | seller.name | string | yes | | | seller.siret | string | no | French SIRET (14 digits), schemeID 0002 | | seller.vat | string | no | EU VAT number (BTW/TVA/IVA/USt-IdNr.) | | seller.address_* | string | no | | | buyer.name | string | yes | | | buyer.address_* | string | no | | | lines[].name | string | yes (basic, en16931) | | | lines[].qty | number | yes (basic, en16931) | | | lines[].unit_price | number | yes (basic, en16931) | | | lines[].vat_rate | number | yes (basic, en16931) | percent, e.g. 20, 5.5 | | lines[].vat_cat | string | no (default S) | one of S Z E AE K G L M O | | lines[].vat_exemption_reason | string | no | per-line override | | vat_exemption_reason | string | no | global default reason | | allowances[] | array | no | global discounts/charges | | payment.terms | string | no | free text | | payment.iban | string | no | SEPA credit transfer (IBAN) | | payment.bic | string | no | SWIFT/BIC — en16931 only (BT-86) |

VAT categories (codes UNTDID 5305):

Validators / Validateurs

After generating a Factur-X PDF, validate it with one of the official validators:

Roadmap

License / Licence

This software is copyright (c) 2026 by huguesmax.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself: the Artistic License 2.0.

See LICENSE for the full text.

Ce logiciel est sous copyright (c) 2026 huguesmax. Il est distribué sous les mêmes termes que Perl 5 lui-même : licence Artistic 2.0. Voir le fichier LICENSE pour le texte complet.

Commercial support / Support commercial

English

PDF::FacturX is maintained by huguesmax at Softalys — a software studio based in USA/France specializing in invoicing, document automation, and Perl-based business systems.

If you need help integrating Factur-X / ZUGFeRD into your workflow, custom profile support (EXTENDED, XRechnung, sector-specific CIUS), end-to-end consulting on the French e-invoicing reform (2026-2027), or just a sanity-check on a tricky invoice, feel free to reach out:

The module is and will remain free and open source — paid support is for those who want a guaranteed turnaround or hands-on help.

Français

PDF::FacturX est maintenu par huguesmax au sein de Softalys — un studio logiciel basé aux USA/France spécialisé dans la facturation, l'automatisation documentaire et les systèmes de gestion en Perl.

Pour toute aide à l'intégration de Factur-X / ZUGFeRD dans votre flux de travail, un support sur les profils personnalisés (EXTENDED, XRechnung, CIUS sectoriels), du conseil de bout en bout sur la réforme française de la facturation électronique (2026-2027), ou simplement une relecture d'une facture qui pose problème, n'hésitez pas à nous contacter :

Le module est et restera libre et open source — le support payant est pour les besoins de garantie de délai ou d'accompagnement direct.

Credits / Crédits

See NOTICE for full attributions.