Factur-X — Complete guide (PrestaShop 8 & 9)

This guide covers the installation, configuration and use of the DataFirefly Factur-X module (dffacturx) for PrestaShop 8 and 9. The module turns your orders into hybrid Factur-X electronic invoices: a readable, printable PDF/A-3b that contains, embedded inside it, the structured invoice data in CII XML format (EN 16931 standard).

Overview

A Factur-X invoice is a single file serving two purposes. Your customer opens a classic PDF they can read, print and archive. Their accounting software, or the platform processing the invoice, reads the embedded XML directly without having to interpret the image. There are no longer two files to keep in sync, so no risk of mismatch between what is displayed and what is processed.

The module covers the generation of these files: it produces the XML, renders the PDF and embeds one inside the other with the expected metadata. Transmission through an Accredited Platform is a separate layer, detailed in the regulatory scope section.

Requirements

• PrestaShop 8.0 to 9.x
• PHP 7.4 minimum, 8.1 or above recommended
• TCPDF, shipped with PrestaShop — no additional installation
• PHP extensions: dom (XML building), zlib (reading compressed XMP metadata), zip (bulk generation)

Installation

1. In the back office, go to Modules → Module Manager → Upload a module.
2. Drop the dffacturx.zip file. You can also copy the dffacturx folder directly into your shop’s modules/ directory.
3. Run the installation. The module registers its hooks and creates a Factur-X tab under the Orders menu.
4. Open the configuration and fill in the seller identity before generating your first invoice.

Configuration

Seller identity

This step is mandatory. These details feed both the visible PDF and the structured XML. Without them, the XML will be rejected by a validator.

• Company name — pre-filled with your shop name, to be corrected if your legal name differs.
• SIREN — 9 digits, no spaces. Essential: it is carried in the XML with the appropriate scheme identifier.
• SIRET — 14 digits, optional but recommended.
• Intra-community VAT number — essential if you are VAT registered (e.g. FR12345678901).
• Legal form and share capital — displayed in the legal notices at the bottom of the invoice.
• Address, postcode, city, country — the country is expected as a two-letter ISO code (e.g. FR).
• Contact, phone, email — carried in the XML on EN 16931 and higher profiles.

Factur-X profile

The profile determines the level of detail in the XML and the specification identifier written into it. The module sets it automatically according to your choice.

• EN 16931 — recommended. Matches the complete European core standard, accepted everywhere.
• BASIC — lighter XML, still keeps line detail.
• EXTENDED — extended profile, for cases requiring additional data.
• MINIMUM and BASIC WL — profiles without line detail, reserved for specific uses.

Options

• Customer download — enables a link in the customer account area. The module checks that the order belongs to the logged-in customer before serving the file.
• Automatic generation — if you set an order status ID, an invoice is generated and saved to the module’s generated folder as soon as an order reaches that status. Any errors are written to the PrestaShop logs without blocking the status change.

Generating an invoice

From the order page

Open an order in the back office: a Factur-X panel appears at the bottom of the main page. It shows the active profile and offers two buttons — Download Factur-X PDF for the complete hybrid file, and Download XML for the XML alone, useful during testing and validation.

Bulk generation

The Orders → Factur-X menu lists your orders with direct access to the PDF and XML on each row. To process a batch, tick the relevant orders and choose the bulk action Download Factur-X invoices (ZIP): the module assembles every invoice into an archive. If an order fails, it is skipped and the error is logged — the archive remains usable.

Customer side

If the option is enabled, a My Factur-X invoices link appears in the account area. The front controller checks that the customer is logged in and that the order belongs to them, otherwise it redirects to the order history.

What the generated file contains

The PDF produced is a PDF/A-3b rendered by PrestaShop’s TCPDF. The module then adds, via incremental update, the elements that make it a Factur-X invoice:

• an embedded file object containing the XML, named factur-x.xml;
• an entry in the catalog’s associated files array, with the Data relationship;
• an entry in the named embedded files dictionary;
• XMP metadata describing the document type, file name, version and conformance level, together with the corresponding PDF/A extension schema.

The incremental update appends these objects to the end of the file without modifying a single byte of the rendered document. The fonts, content streams and colour profile produced by TCPDF stay intact — and the module depends on no internal detail of TCPDF, therefore on no particular version.

The XML is a UN/CEFACT CrossIndustryInvoice. It contains the document context with the profile’s specification identifier, the invoice header, the lines where applicable, the trade agreement (seller and buyer), the delivery, and the settlement with the VAT breakdown, allowances, charges and monetary summary.

Accounting modelling

Factur-X validators do not compare your totals against PrestaShop’s: they check that the document is consistent with itself. The module therefore recalculates all amounts from the lines and the VAT breakdown, in order to satisfy the standard’s balance rules.

• Lines — the net unit price is derived from the line total divided by the quantity. The unit used is the generic unit code.
• Shipping costs — modelled as a document-level charge, with their own VAT rate.
• Discounts — modelled as a document-level allowance, spread proportionally across the different VAT bases.
• VAT breakdown — one occurrence per rate encountered, with base, amount and category.
• VAT category — standard category if the rate is above zero, zero-rated category otherwise.
• Prepayment — the prepaid amount is zero and the amount due equals the gross total: the invoice is issued, the whole sum remains due as far as the document is concerned.

Special VAT cases — exemption, reverse charge, intra-community supply — are not derived automatically. If your business involves them, have a few representative invoices validated and adjust the category used.

Validate before going live

This step is not optional. Generate a few invoices representative of your business — a simple order, an order with a discount, an order with several VAT rates — then check them with:

• the FNFE-MPE validator, the French reference for Factur-X;
• Mustangproject, an open source validator for EN 16931 conformance;
• veraPDF, for the conformance of the PDF/A-3 container.

The XML-only download button exists for this phase: it saves you from manually extracting the attachment from the PDF at every attempt.

Regulatory scope

The French e-invoicing reform follows a two-stage schedule. On 1 September 2026, all VAT-registered businesses must be able to receive electronic invoices, and large enterprises and mid-caps must issue them. On 1 September 2027, the obligation to issue extends to SMEs, very small businesses and micro-enterprises. Most PrestaShop merchants must therefore receive from 2026 and issue from 2027.

Three roles must be distinguished:

• Generating compliant Factur-X files — what this module does. No certification or registration is required.
• Transmitting invoices through an Accredited Platform (formerly PDP). The merchant chooses their platform and hands the files over to it.
• Being an Accredited Platform — an activity subject to State registration, outside the module’s scope.

Troubleshooting

The validator rejects the XML

First check the seller identity, particularly the SIREN and the VAT number: these are the most frequent causes of rejection. Then check the customer’s invoice address — a missing country or postcode can also make validation fail.

Message stating that TCPDF is unavailable

The module uses the TCPDF class provided by PrestaShop and, failing that, tries to load it from the tools directory. If the error persists, the library has been removed from your installation: restore it from a PrestaShop archive of the same version.

The ZIP bulk action is unavailable

The PHP zip extension is not enabled on the server. Individual downloads from each order page remain available without it.

Automatic generation produces nothing

Check that the order status ID is set in the configuration, then that the module’s generated folder is writable. Generation errors are recorded in the PrestaShop logs with the Factur-X prefix.

The PDF opens but the attachment does not appear

Not all readers display the attachments panel by default. Open your PDF reader’s dedicated pane, or use the XML-only download to check its content.

Architecture

The module follows a classic layout, with a manual PSR-4 autoloader whose namespace root DataFirefly/FacturX points to the src folder.

• src/Builder — profile definitions and CII XML building.
• src/Pdf — PDF/A-3b rendering and XML embedding.
• src/Service — order data extraction and orchestration.
• src/Install — installation, admin tab and hooks.
• controllers/admin and controllers/front — back-office and front-office download controllers.

The architecture relies on ModuleAdminController and Smarty, identical between PrestaShop 8 and 9, with no separate code branch and no specific Symfony dependency.

Changelog

1.0.0 — 4 June 2026

• Generation of hybrid Factur-X invoices: PDF/A-3b with embedded CII XML.
• Selectable BASIC, EN 16931 and EXTENDED profiles.
• CII XML built to the UN/CEFACT standard with per-rate VAT breakdown.
• Self-contained XML embedding via PDF incremental update.
• Factur-X XMP metadata and PDF/A extension schema injected.
• Fully configurable seller identity.
• PDF and XML download from the order page, bulk generation to ZIP.
• Download link in the customer account, toggleable.
• Optional automatic generation on an order status change.
• Compatible with PrestaShop 8.0 to 9.0 with no separate code branch.