DataFirefly Factur-X SW — E-Invoicing for Shopware 6: complete guide

Overview

DfFacturX SW generates EN 16931 compliant electronic invoices for Shopware 6.5, 6.6 and 6.7. Every time an invoice document is created, the plugin builds a UN/CEFACT CII XML and, depending on the selected profile, embeds it into the invoice PDF (Factur-X / ZUGFeRD) or provides it as a standalone file (XRechnung 3.0 for German B2G).

• Factur-X / ZUGFeRD EN 16931 — recommended profile for B2B: the PDF your customer downloads is the hybrid e-invoice.
• Factur-X BASIC — lighter profile, for recipients that do not require the full EN 16931 data set.
• XRechnung 3.0 — standalone XML in CII syntax to invoice German public authorities, with a mandatory Leitweg-ID.

Installation

1. Copy the plugin folder to custom/plugins/DfFacturX (or upload the ZIP from the admin, Extensions then My extensions).
2. Run:

bin/console plugin:refresh
bin/console plugin:install --activate DfFacturX
bin/console cache:clear

Configuration

Admin, Extensions, DfFacturX, Configuration. All settings are scoped per sales channel.

General

• Enable generation — triggers XML creation on every new invoice document.
• Profile — Factur-X EN 16931, Factur-X BASIC or XRechnung 3.0.
• Embed XML into the PDF — for Factur-X profiles; the document media is replaced by the hybrid PDF.
• Attach XML to e-mails — adds factur-x.xml (or number-xrechnung.xml) to order e-mails.
• B2B only — only generates when the order carries a company name or VAT number.

Seller

Company name, street, postal code, city, country (ISO-2), VAT ID (BT-31), tax number (BT-32), e-mail (BT-34), phone and contact person (BG-6). E-mail and contact are required by XRechnung.

Payment

IBAN and BIC (SEPA credit transfer, code 58), payment terms text (BT-20) and due days (BT-9). Without an IBAN, the payment means is declared as code 1 (not defined).

Tax handling

For 0% rates, the Automatic mode applies: K intra-community supply (buyer with a VAT number in another EU country), G export outside the EU, Z otherwise. You can force a fixed category (Z, E, K, G) and customise the exemption reason (BT-120).

XRechnung

Technical name of the custom field holding the buyer reference (default df_facturx_buyer_reference) and fallback value when no field is filled.

Leitweg-ID and buyer reference (BT-10)

Enter the Leitweg-ID once on the customer profile (custom fields tab): it is reused on all their invoices. For a one-off case, fill it directly on the order — the order value overrides the customer value, which overrides the fallback.

How it works

1. When the invoice document is created (admin, Flow Builder or API), the plugin loads the order in its exact order version.
2. The CII XML is built and stored in the document’s custom fields (df_facturx_xml, df_facturx_profile, df_facturx_generated_at).
3. With a Factur-X profile, the XML is embedded into the PDF via incremental update: attached factur-x.xml file, PDF A-3 XMP metadata and the Factur-X extension schema. The document media is replaced in place.
4. If the option is enabled, the XML is attached to order e-mails.

EN 16931 accounting model

• Net model — gross orders are converted using Shopware’s calculated taxes.
• Promotions — converted to document-level allowances (BG-20), one entry per VAT rate, because the standard forbids negative lines (BR-27).
• Shipping costs — declared as document-level charges (BG-21), one entry per rate.
• RoundingAmount (BT-114) — absorbs any rounding drift: the XML GrandTotal strictly equals the Shopware order total.
• SEPA payment — credit transfer code 58 with IBAN/BIC, due date computed from the invoice date.

Console command

# Regenerate the e-invoice for the latest invoice of an order
bin/console df:facturx:generate 10042 --force

# Export the XML to a file (for a validator)
bin/console df:facturx:generate 10042 --output=/tmp/10042.xml

# Force a profile for one run (implies regeneration)
bin/console df:facturx:generate 10042 --profile=xrechnung-30

Validation checklist before going live

1. Create test orders covering your real cases: gross and net sales channels, promotion, shipping, intra-community sale with VAT number, export outside the EU.
2. Generate the invoice for each one, then export the XML with --output.
3. Validate: KOSIT validator for XRechnung, Mustang for Factur-X / ZUGFeRD.
4. Open the hybrid PDF in Adobe Acrobat and check for the factur-x.xml attachment.

Troubleshooting

• No XML generated — check the plugin is enabled for the sales channel, the document type is invoice, and the B2B-only mode is not filtering the order. Check the logs (var/log).
• “Missing seller configuration” error — complete the Seller card (minimum fields above).
• “PDF embedding skipped” warning — the PDF structure did not allow embedding; the XML remains available as an e-mail attachment and via console. Typical case: PDF generated by a third-party engine.
• XRechnung refused — missing buyer reference: fill the custom field or the fallback value, then --force.
• Regeneration after configuration changes — already processed documents are not reprocessed automatically; use df:facturx:generate --force.

Known limitations and roadmap

• Version 1.0: invoices only (code 380). Credit notes (381) and corrective invoices (384) planned for 1.1.
• Strict PDF/A-3B conformance also depends on properties of the source PDF produced by Shopware’s dompdf engine (embedded fonts, output intent). Recipients and accounting tools consume the embedded XML in all cases; for a strict PDF/A-3B requirement, use the XRechnung profile or the XML e-mail attachment.
• One VAT line per order line (standard Shopware behaviour).