Factur-X — Vollständige Anleitung (PrestaShop 8 & 9)

Diese Anleitung behandelt die Installation, Konfiguration und Nutzung des Moduls DataFirefly Factur-X (dffacturx) für PrestaShop 8 und 9. Das Modul verwandelt Ihre Bestellungen in hybride elektronische Rechnungen im Factur-X-Format: ein lesbares, druckbares PDF/A-3b, das die strukturierten Rechnungsdaten im CII-XML-Format (Norm EN 16931) eingebettet enthält.

Überblick

Eine Factur-X-Rechnung ist eine einzige Datei für zwei Zwecke. Ihr Kunde öffnet ein klassisches PDF, das er lesen, drucken und archivieren kann. Seine Buchhaltungssoftware oder die Plattform, die die Rechnung verarbeitet, liest das eingebettete XML direkt, ohne das Bild interpretieren zu müssen. Es gibt keine zwei Dateien mehr, die synchron gehalten werden müssen, und damit kein Risiko einer Abweichung zwischen Dargestelltem und Verarbeitetem.

Das Modul deckt die Erzeugung dieser Dateien ab: Es erzeugt das XML, rendert das PDF und bettet das eine in das andere ein, mit den erwarteten Metadaten. Die Übermittlung über eine zugelassene Plattform ist eine eigene Schicht, die im Abschnitt zum regulatorischen Umfang beschrieben wird.

Voraussetzungen

• PrestaShop 8.0 bis 9.x
• PHP 7.4 mindestens, 8.1 oder höher empfohlen
• TCPDF, standardmäßig in PrestaShop enthalten — keine zusätzliche Installation
• PHP-Erweiterungen: dom (XML-Aufbau), zlib (Lesen komprimierter XMP-Metadaten), zip (Massengenerierung)

Installation

1. Gehen Sie im Back Office zu Module → Modulmanager → Modul hochladen.
2. Laden Sie die Datei dffacturx.zip hoch. Sie können den Ordner dffacturx auch direkt in das Verzeichnis modules/ Ihres Shops kopieren.
3. Führen Sie die Installation aus. Das Modul registriert seine Hooks und legt einen Reiter Factur-X unter dem Menü Bestellungen an.
4. Öffnen Sie die Konfiguration und tragen Sie die Verkäuferidentität ein, bevor Sie Ihre erste Rechnung erzeugen.

Konfiguration

Verkäuferidentität

Dies ist der Pflichtschritt. Diese Angaben fließen sowohl in das sichtbare PDF als auch in das strukturierte XML ein. Ohne sie wird das XML von einem Validator abgelehnt.

• Firmenname — mit Ihrem Shop-Namen vorbelegt, zu korrigieren, falls Ihre Firmierung abweicht.
• SIREN — 9 Ziffern, ohne Leerzeichen. Unverzichtbar: Sie wird im XML mit der passenden Schemakennung übertragen.
• SIRET — 14 Ziffern, optional, aber empfohlen.
• Innergemeinschaftliche USt-IdNr. — unverzichtbar, wenn Sie umsatzsteuerpflichtig sind (z. B. FR12345678901).
• Rechtsform und Stammkapital — werden in den rechtlichen Hinweisen im Rechnungsfuß angezeigt.
• Adresse, Postleitzahl, Ort, Land — das Land wird als zweistelliger ISO-Code erwartet (z. B. FR).
• Kontakt, Telefon, E-Mail — werden im XML bei den Profilen EN 16931 und höher übernommen.

Factur-X-Profil

Das Profil bestimmt den Detailgrad des XML und die darin eingetragene Spezifikationskennung. Das Modul setzt sie automatisch entsprechend Ihrer Auswahl.

• EN 16931 — empfohlen. Entspricht dem vollständigen europäischen Kern, überall akzeptiert.
• BASIC — leichteres XML, behält die Positionsdetails.
• EXTENDED — erweitertes Profil, für Fälle mit zusätzlichem Datenbedarf.
• MINIMUM und BASIC WL — Profile ohne Positionsdetails, für spezielle Anwendungsfälle.

Optionen

• Kundendownload — aktiviert einen Link im Kundenkonto. Das Modul prüft, ob die Bestellung dem angemeldeten Kunden gehört, bevor die Datei ausgeliefert wird.
• Automatische Erzeugung — wenn Sie eine Bestellstatus-ID eintragen, wird eine Rechnung erzeugt und im Ordner generated des Moduls gespeichert, sobald eine Bestellung diesen Status erreicht. Etwaige Fehler werden in die PrestaShop-Logs geschrieben, ohne den Statuswechsel zu blockieren.

Eine Rechnung erzeugen

Von der Bestellseite aus

Öffnen Sie eine Bestellung im Back Office: Am unteren Rand der Hauptseite erscheint ein Panel Factur-X. Es zeigt das aktive Profil und bietet zwei Schaltflächen — Factur-X-PDF herunterladen für die vollständige Hybriddatei und XML herunterladen für das reine XML, nützlich in der Test- und Validierungsphase.

Massengenerierung

Das Menü Bestellungen → Factur-X listet Ihre Bestellungen mit direktem Zugriff auf PDF und XML in jeder Zeile. Um eine Charge zu verarbeiten, markieren Sie die betreffenden Bestellungen und wählen die Sammelaktion Factur-X-Rechnungen herunterladen (ZIP): Das Modul fasst alle Rechnungen in einem Archiv zusammen. Schlägt eine Bestellung fehl, wird sie übersprungen und der Fehler protokolliert — das Archiv bleibt nutzbar.

Kundenseite

Ist die Option aktiviert, erscheint im Kontobereich ein Link Meine Factur-X-Rechnungen. Der Front-Controller prüft, ob der Kunde angemeldet ist und die Bestellung ihm gehört; andernfalls leitet er zur Bestellhistorie weiter.

Was die erzeugte Datei enthält

Das erzeugte PDF ist ein PDF/A-3b, gerendert vom TCPDF aus PrestaShop. Das Modul fügt anschließend per inkrementellem Update die Elemente hinzu, die daraus eine Factur-X-Rechnung machen:

• ein eingebettetes Dateiobjekt mit dem XML, benannt factur-x.xml;
• einen Eintrag im Array der zugehörigen Dateien des Katalogs, mit der Beziehung Data;
• einen Eintrag im Verzeichnis der benannten eingebetteten Dateien;
• XMP-Metadaten mit Dokumenttyp, Dateiname, Version und Konformitätsstufe, zusammen mit dem entsprechenden PDF/A-Erweiterungsschema.

Das inkrementelle Update hängt diese Objekte an das Dateiende an, ohne ein einziges Byte des gerenderten Dokuments zu verändern. Die von TCPDF erzeugten Schriften, Inhaltsströme und das Farbprofil bleiben unangetastet — und das Modul hängt von keinem internen Detail von TCPDF ab, also von keiner bestimmten Version.

Das XML ist eine UN/CEFACT-CrossIndustryInvoice. Es enthält den Dokumentkontext mit der Spezifikationskennung des Profils, den Rechnungskopf, gegebenenfalls die Positionen, die Handelsvereinbarung (Verkäufer und Käufer), die Lieferung sowie die Abrechnung mit Umsatzsteueraufschlüsselung, Abschlägen, Zuschlägen und Betragsaufstellung.

Buchhalterische Modellierung

Factur-X-Validatoren vergleichen Ihre Summen nicht mit denen von PrestaShop: Sie prüfen, ob das Dokument in sich stimmig ist. Das Modul berechnet daher alle Beträge aus den Positionen und der Umsatzsteueraufschlüsselung neu, um die Bilanzregeln der Norm zu erfüllen.

• Positionen — der Nettoeinzelpreis ergibt sich aus der Positionssumme geteilt durch die Menge. Verwendet wird der generische Einheitencode.
• Versandkosten — als Zuschlag auf Dokumentebene modelliert, mit eigenem Steuersatz.
• Rabatte — als Abschlag auf Dokumentebene modelliert, proportional auf die verschiedenen Steuerbemessungsgrundlagen verteilt.
• Umsatzsteueraufschlüsselung — ein Eintrag je vorkommendem Satz, mit Bemessungsgrundlage, Betrag und Kategorie.
• Steuerkategorie — Standardkategorie, wenn der Satz über null liegt, andernfalls Nullkategorie.
• Anzahlung — der vorausbezahlte Betrag ist null und der Fälligkeitsbetrag entspricht der Bruttosumme: Die Rechnung ist ausgestellt, im Sinne des Dokuments bleibt der volle Betrag offen.

Besondere Steuerfälle — Befreiung, Reverse Charge, innergemeinschaftliche Lieferung — werden nicht automatisch abgeleitet. Betrifft Ihr Geschäft solche Fälle, lassen Sie einige repräsentative Rechnungen validieren und passen Sie die verwendete Kategorie an.

Vor dem Produktivstart validieren

Dieser Schritt ist nicht optional. Erzeugen Sie einige für Ihr Geschäft repräsentative Rechnungen — eine einfache Bestellung, eine Bestellung mit Rabatt, eine Bestellung mit mehreren Steuersätzen — und prüfen Sie sie mit:

• dem Validator der FNFE-MPE, der französischen Referenz für Factur-X;
• Mustangproject, einem Open-Source-Validator für die EN-16931-Konformität;
• veraPDF, für die Konformität des PDF/A-3-Containers.

Die Schaltfläche zum Herunterladen des reinen XML ist für diese Phase gedacht: Sie ersparen sich das manuelle Extrahieren des Anhangs aus dem PDF bei jedem Versuch.

Regulatorischer Umfang

Die französische E-Rechnungsreform folgt einem zweistufigen Zeitplan. Zum 1. September 2026 müssen alle umsatzsteuerpflichtigen Unternehmen elektronische Rechnungen empfangen können, und Großunternehmen sowie mittelgroße Unternehmen müssen sie ausstellen. Zum 1. September 2027 erstreckt sich die Ausstellungspflicht auf KMU, Kleinst- und Mikrounternehmen. Die meisten PrestaShop-Händler müssen also ab 2026 empfangen und ab 2027 ausstellen.

Drei Rollen sind zu unterscheiden:

• Erzeugen konformer Factur-X-Dateien — was dieses Modul tut. Es ist keine Zertifizierung oder Registrierung erforderlich.
• Übermitteln der Rechnungen über eine zugelassene Plattform (früher PDP). Der Händler wählt seine Plattform und übergibt ihr die Dateien.
• Sein einer zugelassenen Plattform — eine Tätigkeit, die einer staatlichen Registrierung unterliegt und außerhalb des Modulumfangs liegt.

Fehlerbehebung

Der Validator lehnt das XML ab

Prüfen Sie zuerst die Verkäuferidentität, insbesondere SIREN und USt-IdNr.: Das sind die häufigsten Ablehnungsgründe. Prüfen Sie anschließend die Rechnungsadresse des Kunden — ein fehlendes Land oder eine fehlende Postleitzahl kann die Validierung ebenfalls scheitern lassen.

Meldung, dass TCPDF nicht verfügbar ist

Das Modul nutzt die von PrestaShop bereitgestellte TCPDF-Klasse und versucht andernfalls, sie aus dem Tools-Verzeichnis zu laden. Bleibt der Fehler bestehen, wurde die Bibliothek aus Ihrer Installation entfernt: Stellen Sie sie aus einem PrestaShop-Archiv derselben Version wieder her.

Die ZIP-Sammelaktion ist nicht verfügbar

Die PHP-Erweiterung zip ist auf dem Server nicht aktiviert. Der Einzeldownload von jeder Bestellseite bleibt auch ohne sie verfügbar.

Die automatische Erzeugung liefert nichts

Prüfen Sie, ob die Bestellstatus-ID in der Konfiguration eingetragen ist, und ob der Ordner generated des Moduls beschreibbar ist. Erzeugungsfehler werden in den PrestaShop-Logs mit dem Präfix Factur-X festgehalten.

Das PDF öffnet sich, aber der Anhang erscheint nicht

Nicht alle Reader zeigen das Anhangs-Panel standardmäßig an. Öffnen Sie den entsprechenden Bereich Ihres PDF-Readers oder nutzen Sie den reinen XML-Download, um dessen Inhalt zu prüfen.

Architektur

Das Modul folgt einem klassischen Aufbau, mit einem manuellen PSR-4-Autoloader, dessen Namespace-Wurzel DataFirefly/FacturX auf den Ordner src verweist.

• src/Builder — Profildefinitionen und Aufbau des CII-XML.
• src/Pdf — PDF/A-3b-Rendering und XML-Einbettung.
• src/Service — Extraktion der Bestelldaten und Orchestrierung.
• src/Install — Installation, Admin-Reiter und Hooks.
• controllers/admin und controllers/front — Download-Controller für Back Office und Front Office.

Die Architektur stützt sich auf ModuleAdminController und Smarty, identisch zwischen PrestaShop 8 und 9, ohne separaten Code-Zweig und ohne spezifische Symfony-Abhängigkeit.

Changelog

1.0.0 — 4. Juni 2026

• Erzeugung hybrider Factur-X-Rechnungen: PDF/A-3b mit eingebettetem CII-XML.
• Auswählbare Profile BASIC, EN 16931 und EXTENDED.
• Aufbau des CII-XML nach UN/CEFACT mit Umsatzsteueraufschlüsselung je Satz.
• Eigenständige XML-Einbettung per inkrementellem PDF-Update.
• Factur-X-XMP-Metadaten und PDF/A-Erweiterungsschema injiziert.
• Vollständig konfigurierbare Verkäuferidentität.
• PDF- und XML-Download auf der Bestellseite, Massengenerierung als ZIP.
• Download-Link im Kundenkonto, umschaltbar.
• Optionale automatische Erzeugung bei einem Bestellstatuswechsel.
• Kompatibel mit PrestaShop 8.0 bis 9.0 ohne separaten Code-Zweig.