# DataFirefly Factur-X SW — E-Rechnung für Shopware 6: vollständige Anleitung > Überblick DfFacturX SW erzeugt EN 16931 konforme elektronische Rechnungen für Shopware 6.5, 6.6 und 6.7. Bei jeder Erstellung eines Rechnungsdokuments baut das Plugin ein UN/CEFACT CII-XML und bettet es je… - Seite: - Sprache: de - Aktualisiert am: 2026-08-06 - Weitere Sprachen: [fr](https://www.datafirefly.com/documentation/dffacturx-shopware/index.md), [en](https://www.datafirefly.com/en/documentation/dffacturx-shopware/index.md), [es](https://www.datafirefly.com/es/documentation/dffacturx-shopware/index.md), [it](https://www.datafirefly.com/it/documentation/dffacturx-shopware/index.md), [pl](https://www.datafirefly.com/pl/documentation/dffacturx-shopware/index.md), [nl](https://www.datafirefly.com/nl/documentation/dffacturx-shopware/index.md), [pt](https://www.datafirefly.com/pt/documentation/dffacturx-shopware/index.md) - Index: ## Überblick DfFacturX SW erzeugt **EN 16931** konforme elektronische Rechnungen für Shopware 6.5, 6.6 und 6.7. Bei jeder Erstellung eines Rechnungsdokuments baut das Plugin ein UN/CEFACT CII-XML und bettet es je nach gewähltem Profil in das Rechnungs-PDF ein (Factur-X / ZUGFeRD) oder liefert es als eigenständige Datei (XRechnung 3.0 für den B2G-Bereich). - **Factur-X / ZUGFeRD EN 16931** — empfohlenes Profil für B2B: das PDF, das Ihr Kunde herunterlädt, ist die hybride E-Rechnung. - **Factur-X BASIC** — schlankeres Profil für Empfänger, die nicht den vollen EN 16931 Datensatz verlangen. - **XRechnung 3.0** — eigenständiges XML in CII-Syntax für Rechnungen an deutsche Behörden, mit verpflichtender Leitweg-ID. ## Installation 1. Kopieren Sie den Plugin-Ordner nach `custom/plugins/DfFacturX` (oder laden Sie das ZIP im Admin unter Erweiterungen, Meine Erweiterungen hoch). 2. Führen Sie aus: ``` bin/console plugin:refresh bin/console plugin:install --activate DfFacturX bin/console cache:clear ``` Die Aktivierung installiert das Zusatzfeld-Set **E-Rechnung (DfFacturX)** mit dem Feld `df_facturx_buyer_reference` an Kunde und Bestellung. Hier wird die Leitweg-ID (BT-10) eingetragen. ## Konfiguration Admin, Erweiterungen, DfFacturX, Konfiguration. Alle Einstellungen gelten je Verkaufskanal. ### Allgemein - **Erzeugung aktivieren** — startet die XML-Erstellung bei jedem neuen Rechnungsdokument. - **Profil** — Factur-X EN 16931, Factur-X BASIC oder XRechnung 3.0. - **XML in das PDF einbetten** — für Factur-X Profile; das Dokumentmedium wird durch das Hybrid-PDF ersetzt. - **XML an E-Mails anhängen** — fügt `factur-x.xml` (oder `nummer-xrechnung.xml`) an Bestell-E-Mails an. - **Nur B2B** — erzeugt nur, wenn die Bestellung einen Firmennamen oder eine USt-IdNr. trägt. ### Verkäufer Firmenname, Straße, Postleitzahl, Stadt, Land (ISO-2), USt-IdNr. (BT-31), Steuernummer (BT-32), E-Mail (BT-34), Telefon und Ansprechpartner (BG-6). E-Mail und Ansprechpartner sind bei XRechnung Pflicht. Mindestangaben Verkäufer: Name, Straße, PLZ, Stadt, Land, dazu die USt-IdNr. _oder_ die Steuernummer (Regel BR-CO-26). Ohne sie schlägt die Erzeugung mit einem klaren Fehler in den Logs fehl. ### Zahlung IBAN und BIC (SEPA-Überweisung, Code 58), Zahlungsbedingungen (BT-20) und Fälligkeit in Tagen (BT-9). Ohne IBAN wird das Zahlungsmittel als Code 1 (nicht definiert) deklariert. ### Steuerbehandlung Für 0%-Sätze wendet der Modus **Automatisch** an: **K** innergemeinschaftliche Lieferung (Käufer mit USt-IdNr. in einem anderen EU-Land), **G** Ausfuhr in Drittländer, sonst **Z**. Sie können eine feste Kategorie erzwingen (Z, E, K, G) und den Befreiungsgrund (BT-120) anpassen. ### XRechnung Technischer Name des Zusatzfelds mit der Käuferreferenz (Standard `df_facturx_buyer_reference`) und Fallback-Wert, falls kein Feld gefüllt ist. ## Leitweg-ID und Käuferreferenz (BT-10) Hinterlegen Sie die Leitweg-ID einmal am Kunden (Reiter Zusatzfelder): sie wird auf allen seinen Rechnungen verwendet. Für einen Einzelfall tragen Sie sie direkt an der Bestellung ein — der Bestellwert übersteuert den Kundenwert, dieser übersteuert den Fallback. Beim XRechnung-Profil **verweigert** das Plugin die Erzeugung eines ungültigen XML, wenn keine Käuferreferenz gefunden wird, und protokolliert einen Fehler. Korrigieren Sie die Daten und starten Sie erneut mit `df:facturx:generate --force`. ## Funktionsweise 1. Bei der Erstellung des Rechnungsdokuments (Admin, Flow Builder oder API) lädt das Plugin die Bestellung in ihrer exakten Bestellversion. 2. Das CII-XML wird gebaut und in den Zusatzfeldern des Dokuments gespeichert (`df_facturx_xml`, `df_facturx_profile`, `df_facturx_generated_at`). 3. Bei einem Factur-X Profil wird das XML per inkrementellem Update in das PDF eingebettet: angehängte Datei `factur-x.xml`, PDF A-3 XMP-Metadaten und Factur-X Extension Schema. Das Dokumentmedium wird an Ort und Stelle ersetzt. 4. Ist die Option aktiv, wird das XML an Bestell-E-Mails angehängt. Fügen Sie im Flow Builder die Aktion zur Rechnungserstellung in Ihren Bestell-Flow ein: die E-Rechnung folgt automatisch, ohne weiteren Schritt. Per Design blockiert ein E-Rechnungsfehler niemals die Dokumenterstellung: der Vorfall wird protokolliert und die klassische PDF-Rechnung bleibt verfügbar. ## EN 16931 Rechnungsmodell - **Nettomodell** — Brutto-Bestellungen werden über die kalkulierten Steuern von Shopware umgerechnet. - **Promotions** — werden zu Nachlässen auf Dokumentebene (BG-20), ein Eintrag je Steuersatz, da die Norm negative Positionen verbietet (BR-27). - **Versandkosten** — als Zuschläge auf Dokumentebene (BG-21) ausgewiesen, ein Eintrag je Satz. - **RoundingAmount (BT-114)** — fängt jede Rundungsdifferenz ab: die Endsumme im XML entspricht exakt dem Shopware-Bestellwert. - **SEPA-Zahlung** — Überweisung Code 58 mit IBAN/BIC, Fälligkeit berechnet ab Rechnungsdatum. ## Konsolenbefehl ``` # E-Rechnung der letzten Rechnung einer Bestellung neu erzeugen bin/console df:facturx:generate 10042 --force # XML in eine Datei exportieren (für einen Validator) bin/console df:facturx:generate 10042 --output=/tmp/10042.xml # Profil einmalig erzwingen (impliziert die Neuerzeugung) bin/console df:facturx:generate 10042 --profile=xrechnung-30 ``` ## Validierungs-Checkliste vor dem Livegang 1. Legen Sie Testbestellungen für Ihre realen Fälle an: Brutto- und Netto-Verkaufskanal, Rabatt, Versandkosten, innergemeinschaftliche Lieferung mit USt-IdNr., Ausfuhr in Drittländer. 2. Erzeugen Sie jeweils die Rechnung und exportieren Sie das XML mit `--output`. 3. Validieren Sie: [KOSIT-Validator](https://github.com/itplr-kosit/validator) für XRechnung, [Mustang](https://www.mustangproject.org) für Factur-X / ZUGFeRD. 4. Öffnen Sie das Hybrid-PDF in Adobe Acrobat und prüfen Sie den Anhang `factur-x.xml`. ## Fehlerbehebung - **Kein XML erzeugt** — prüfen Sie, ob das Plugin für den Verkaufskanal aktiv ist, der Dokumenttyp _Rechnung_ ist und der Nur-B2B-Modus die Bestellung nicht filtert. Sehen Sie in die Logs (`var/log`). - **Fehler „Missing seller configuration"** — vervollständigen Sie die Verkäufer-Karte (Mindestangaben oben). - **Warnung „PDF embedding skipped"** — die PDF-Struktur erlaubte keine Einbettung; das XML bleibt als E-Mail-Anhang und per Konsole verfügbar. Typischer Fall: PDF aus einem Dritt-Renderer. - **XRechnung verweigert** — fehlende Käuferreferenz: füllen Sie das Zusatzfeld oder den Fallback-Wert, dann `--force`. - **Neuerzeugung nach Konfigurationsänderung** — bereits verarbeitete Dokumente werden nicht automatisch neu verarbeitet; nutzen Sie `df:facturx:generate --force`. ## Bekannte Einschränkungen und Roadmap - Version 1.0: nur Rechnungen (Code 380). Gutschriften (381) und Rechnungskorrekturen (384) für 1.1 geplant. - Strikte PDF/A-3B Konformität hängt auch von Eigenschaften des von Shopwares dompdf-Engine erzeugten Quell-PDF ab (eingebettete Schriften, Output Intent). Empfänger und Buchhaltungssysteme verarbeiten in allen Fällen das eingebettete XML; bei strikter PDF/A-3B Anforderung nutzen Sie das XRechnung-Profil oder den XML-E-Mail-Anhang. - Eine Steuerzeile je Bestellposition (Shopware-Standardverhalten).