README

Français : README.fr.md

Factur-X / ZUGFeRD (EN 16931) electronic invoices for the Sylius 2 Invoicing Plugin.

The official Sylius Invoicing Plugin generates PDF invoices. Since September 2026, French businesses must be able to receive electronic invoices, and large and mid-sized companies must issue them (SMEs from September 2027); German businesses must accept them since 2025. A plain PDF is not an electronic invoice.

This plugin turns the invoice PDFs into Factur-X PDF/A-3 files with an embedded factur-x.xml (UN/CEFACT Cross Industry Invoice, EN 16931 profile), the hybrid format accepted in France and in Germany (where it is called ZUGFeRD), free and open source.

Features

Also included: translations in English, French, German, Spanish, Italian, Dutch and Polish; Twig Hooks everywhere; MySQL, MariaDB and PostgreSQL support.

Screenshots

Requirements

The PDF of the Invoicing Plugin must be readable by the free FPDI parser (no compressed cross-reference streams): this is the case of PDFs rendered by wkhtmltopdf, the default renderer. The plugin depends on horstoeko/zugferd (MIT), which itself requires smalot/pdfparser (LGPL-3.0, installed by Composer, not bundled).

Installation

1. Install and configure the Sylius Invoicing Plugin first (bundles, configuration, routes, migrations, wkhtmltopdf).

2. Require the package:

   composer require tmonier/sylius-facturx-plugin

3. Register the bundle in config/bundles.php, after the Invoicing Plugin:

   Sylius\InvoicingPlugin\SyliusInvoicingPlugin::class => ['all' => true],
   Tmonier\SyliusFacturXPlugin\TmonierSyliusFacturXPlugin::class => ['all' => true],

4. Import the configuration in config/packages/tmonier_sylius_facturx.yaml:

   imports:
       - { resource: "@TmonierSyliusFacturXPlugin/config/config.yaml" }

5. Import the admin routes in config/routes/tmonier_sylius_facturx.yaml:

   tmonier_sylius_facturx:
       resource: "@TmonierSyliusFacturXPlugin/config/routes.yaml"

6. Run the migrations:

   bin/console doctrine:migrations:migrate

7. In the admin, open Channels → (edit a channel) → Factur-X settings, enable Factur-X and fill in the seller data. The address of the seller comes from the shop billing data of the channel (company, tax ID, street, postcode, city, country): fill it in too.

8. Optionally, render the PDFs of the invoices issued before as Factur-X:

   bin/console tmonier:facturx:regenerate-pdfs --dry-run -v
   bin/console tmonier:facturx:regenerate-pdfs [--channel=WEB] [--invoice=2026/10/000001]

Configuration

# config/packages/tmonier_sylius_facturx.yaml
tmonier_sylius_facturx:
    enabled: true                         # global switch; each channel must be enabled too
    profile: en16931                      # the only supported profile
    attachment_relationship: Alternative  # AFRelationship of factur-x.xml: Alternative, Data or Source

Alternative is required in Germany for the EN 16931 profile and accepted in France.

The ChannelSettings and CustomerIdentifiers resources can be extended like any Sylius resource (tmonier_sylius_facturx.resources.channel_settings.classes.model, ...).

What ends up in the XML

The amounts are the ones of the invoice: Sylius rounds the VAT per unit, so a VAT amount may differ by a few cents from taxable amount × rate, which EN 16931 allows. The full mapping, the French rules and the sources are in SPEC.md.

Extension point: per-order payment terms

By default the due date (BT-9) is the issue date plus the channel's payment due days when an amount is due, and the payment terms (BT-20) are the channel's payment terms text. A plugin that knows better for some orders (e.g. trade credit: "45 days end of month", per-customer terms) provides them with an InvoicePaymentTermsProviderInterface:

use Sylius\InvoicingPlugin\Entity\InvoiceInterface;
use Symfony\Component\DependencyInjection\Attribute\AsTaggedItem;
use Tmonier\SyliusFacturXPlugin\Entity\ChannelSettingsInterface;
use Tmonier\SyliusFacturXPlugin\PaymentTerms\InvoicePaymentTerms;
use Tmonier\SyliusFacturXPlugin\PaymentTerms\InvoicePaymentTermsProviderInterface;

#[AsTaggedItem(priority: 10)]
final class TradeCreditPaymentTermsProvider implements InvoicePaymentTermsProviderInterface
{
    public function provide(InvoiceInterface $invoice, ChannelSettingsInterface $settings, int $duePayableAmount): ?InvoicePaymentTerms
    {
        $terms = $this->termsRepository->findOneByOrder($invoice->order());
        if (null === $terms) {
            // $duePayableAmount (cents) is 0 for a paid invoice: the due date is then dropped.
            return null; // next provider, then the channel settings
        }

        return new InvoicePaymentTerms($terms->getDueDate(), $terms->getLabel());
    }
}

Autoconfigured services get the tmonier_facturx.invoice_payment_terms_provider tag (set priority on the tag or with #[AsTaggedItem], highest first). The first provider returning terms wins; the channel settings apply when none does. When an amount is due, terms with neither due date nor text are skipped, so the XML always satisfies BR-CO-25. Paid invoices (nothing due) never get a due date (BT-9), whatever the provider returns; its text is kept. The aggregate is available as InvoicePaymentTermsProviderInterface (tmonier_facturx.payment_terms_provider).

Extension point: transmission to a platform

use Tmonier\SyliusFacturXPlugin\Event\FacturXInvoiceGenerated;

#[AsEventListener(event: FacturXInvoiceGenerated::NAME)]
final class SendToMyPlatform
{
    public function __invoke(FacturXInvoiceGenerated $event): void
    {
        $event->getInvoice();      // Sylius\InvoicingPlugin\Entity\InvoiceInterface
        $event->getXml();          // factur-x.xml
        $event->getPdfContent();   // Factur-X PDF/A-3
        $event->getPdfFilename();  // file name in the "sylius_invoicing" storage
    }
}

The event is dispatched every time the PDF is rendered, before it is stored, including when it is rendered again: listeners must be idempotent (use the invoice id). A failing listener is logged and does not prevent the invoice.

Customisation

Grid actions are added to sylius_admin_channel (tmonier_facturx) and sylius_invoicing_invoice (tmonier_facturx_xml). Services can be decorated: tmonier_facturx.mapper.invoice (invoice → data), tmonier_facturx.xml.writer (data → XML), tmonier_facturx.pdf.embedder (PDF + XML → PDF/A-3).

The XML download route (tmonier_facturx_admin_invoice_download_xml) checks InvoiceVoter::ACCESS (from sylius/invoicing-plugin) before serving the file, mirroring the access control applied to the core PDF download (DownloadInvoiceAction).

Limitations

• No transmission to a plateforme agréée (PA) and no e-reporting: in France, issuing an e-invoice means sending it through a PA. Use the event above to build a connector.
• EN 16931 profile only. No credit notes (the Invoicing Plugin has none), no down-payment invoices, no document-level allowances or charges (Sylius distributes promotions on the lines).
• Buyer identifiers are optional and entered by an administrator on the customer page; they are not captured at checkout. B2C invoices are valid Factur-X documents, but in France B2C sales are e-reported, not e-invoiced.
• Invoices issued before shipping carry no delivery date (BT-72): the delivery group of the XML is then empty, which validators report as the PEPPOL-EN16931-R008 warning (not an error).
• Every line with a positive VAT rate is category S; all lines without VAT share the one category configured on the channel.
• The PDF/A-3 conformance of the result depends on the PDF rendered by the Invoicing Plugin: the plugin adds the attachment, the XMP metadata and the output intent, and corrects the glyph widths of the embedded TrueType fonts (wkhtmltopdf writes them about 0.7 % too small, which veraPDF rejects), but it does not rewrite the pages. With the default template and wkhtmltopdf 0.12.6 the result passes veraPDF (PDF/A-3B); check a sample of your own template with a validator (see Development).
• Already stored PDFs are not changed until you run tmonier:facturx:regenerate-pdfs.
• If the Factur-X document cannot be built (missing seller data, unreadable PDF), the plain PDF is kept and the error is logged on the tmonier_facturx channel.

This plugin is not legal or tax advice. It produces a technically valid document from the data you enter and the taxes Sylius computes. The legal mentions, VAT rates, categories and exemption reasons, the buyer data and the choice of a PA remain the merchant's responsibility: check them with your accountant.

Development

docker compose up -d mysql mailhog   # or your own MySQL
composer install
(cd vendor/sylius/test-application && yarn install && yarn build)
vendor/bin/console doctrine:database:create
vendor/bin/console doctrine:migrations:migrate -n
vendor/bin/console sylius:fixtures:load -n

vendor/bin/phpunit --testsuite unit
APP_ENV=test vendor/bin/phpunit --testsuite non-unit   # needs a test database with fixtures
vendor/bin/phpstan analyse
vendor/bin/ecs check

Placeholder PDFs: when WKHTMLTOPDF_PATH does not point to an executable wkhtmltopdf, the test application (dev and test environments) renders every invoice as a one-page FPDF placeholder (Invoice 2026/10/000001), which still becomes a valid Factur-X PDF. To see the real invoices without installing wkhtmltopdf, use the Docker wrapper (wkhtmltopdf 0.12.6 with patched Qt), then clear the cache and render the stored PDFs again:

echo "WKHTMLTOPDF_PATH=$PWD/tests/TestApplication/bin/wkhtmltopdf-docker" >> tests/TestApplication/.env.local
rm -rf var/cache/dev var/cache/test
vendor/bin/console tmonier:facturx:regenerate-pdfs

The tests validate every generated XML against the Factur-X EN 16931 XSD and re-compute the EN 16931 calculation rules in PHP. The functional tests write etc/build/factur-x.pdf and etc/build/factur-x.xml (and, with a real wkhtmltopdf, etc/build/factur-x-wkhtmltopdf.pdf); the CI renders a real invoice and validates them with Mustang (EN 16931 schematron and veraPDF):

java -jar Mustang-CLI-2.26.0.jar --no-notices --action validate --source etc/build/factur-x.pdf

B2B demo

This plugin is used in the Sylius B2B demo: a Sylius 2.3 shop with fictitious sample data where the B2B plugins work together. The source code, setup and fixtures of the demo are in that repository.

The demo is an example, not a production setup.

License

MIT. See LICENSE.