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 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

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.

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.

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.

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 für XRechnung, Mustang 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).