PDF/A und ZUGFeRD in TYPO3 mit Fluid-FPDF erstellen

Mit der TYPO3-Extension Fluid-FPDF (fluid_fpdf) erstellst Du PDF-Dokumente direkt aus Fluid-Templates. Dieses Beispiel zeigt die Ausgabe eines PDF/A-3b-Dokuments mit eingebetteter Rechnungs-XML als Grundlage für eine hybride E-Rechnung im Format ZUGFeRD / Factur-X.

Du lernst, wie Du FPDF-Schriften registrierst, eine XML-Datei einbindest und das erzeugte PDF anschließend auf Rechnungsdaten, Einbettung und PDF/A-Konformität prüfst.

Das Einbetten einer XML-Datei allein macht aus einem PDF noch keine valide ZUGFeRD-Rechnung. Rechnungsdaten, Profil, PDF-Metadaten und Dateieinbettung müssen zusammenpassen. Prüfe die tatsächlich erzeugte Datei vor dem produktiven Einsatz.

PDF, PDF/A-3b, ZUGFeRD und XRechnung: die Unterschiede

Die Grundlagen des hybriden Formats beschreibt FeRD in der ZUGFeRD-Dokumentation. Die Europäische Kommission erläutert das Datenmodell der EN 16931 und die XML-Syntaxen UBL und CII.

Voraussetzungen für die PDF-Erstellung

Für dieses Fluid-Template benötigst Du:

• Eine eingerichtete TYPO3-Installation mit Fluid-FPDF und dem Namespace fpdf.
• Schriftdefinitionen, die Fluid-FPDF laden und in das PDF einbetten kann.
• Eine bereits erzeugte Rechnungs-XML im gewünschten Format und Profil.
• Einen für den PHP-Prozess lesbaren Dateipfad zur XML-Datei.

Das Beispiel zeigt die PDF-Ausgabe und XML-Einbettung, nicht die Erzeugung der strukturierten Rechnungsdaten. Bereite diese in Deiner Anwendung vor, beispielsweise in einem PHP-Service Deiner TYPO3-Extension. Verwende für das sichtbare Rechnungs-PDF und die XML dieselbe Datenbasis, damit Positionen, Steuern und Summen übereinstimmen.

Fluid-Template: PDF/A-3b mit XML-Anhang

<html xmlns="http://www.w3.org/1999/xhtml" lang="en"
      xmlns:f="http://typo3.org/ns/fluid/ViewHelpers"
      xmlns:fpdf="http://typo3.org/ns/CodingMs/FluidFpdf/ViewHelpers"
      data-namespace-typo3-fluid="true">
<fpdf:pdfA>
    <fpdf:addPage>
        <fpdf:addFont family="Monospace" style="N" filename="ubuntumono_n.php" />
        <fpdf:addFont family="Monospace" style="B" filename="ubuntumono_b.php" />
        <fpdf:addFont family="Monospace" style="I" filename="ubuntumono_i.php" />
        <fpdf:addFont family="Monospace" style="BI" filename="ubuntumono_bi.php" />
        <fpdf:setFont family="Monospace" style="B" size="16" />
        <fpdf:cell width="40" height="10" text="Hello World!" />
        <fpdf:setXmlFile file="EXT:fluid_fpdf/Resources/Private/Php/zugferd/factur-x.xml" />
    </fpdf:addPage>
</fpdf:pdfA>
</html>

Was machen die ViewHelper?

Der Pfad EXT:fluid_fpdf/Resources/Private/Php/zugferd/factur-x.xml verweist auf eine Beispieldatei. Ersetze ihn für echte Rechnungen durch die jeweils passende Rechnungs-XML. Auch der sichtbare Beispieltext muss durch Dein vollständiges Rechnungslayout ersetzt werden.

Die mit fpdf:addFont registrierten Varianten stehen für normal (N), fett (B), kursiv (I) und fett-kursiv (BI). Binde jede Schriftvariante ein, die Dein PDF verwendet – auch in Kopfzeilen, Fußzeilen und ergänzenden Texten.

ZUGFeRD und Factur-X korrekt vorbereiten

Lege Formatversion und Profil vor der PDF-Erstellung fest. Profilnamen wie MINIMUM, BASIC WL, BASIC, EN 16931 und EXTENDED stehen für unterschiedliche Datenumfänge und Prüfregeln. Eine erfolgreiche Prüfung eines reduzierten Profils bestätigt nicht automatisch die Einhaltung der vollständigen EN 16931.

Achte insbesondere auf:

• Profilkennung BT-24: Die Spezifikationskennung im XML muss zum tatsächlich erzeugten Profil passen.
• XMP-Metadaten: PDF/A-Kennzeichnung und ZUGFeRD-/Factur-X-Angaben müssen zur Datei passen.
• XML-Einbettung: Dateiname, MIME-Typ, AFRelationship und die Zuordnung über /AF müssen den Anforderungen der verwendeten Version und des Profils entsprechen.
• Identische Rechnungsdaten: Rechnungsnummer, Datum, Währung, Positionen, Steuerbeträge und Gesamtsummen müssen in PDF und XML übereinstimmen.

Die XML-Datei einfach umzubenennen oder BT-24 auszutauschen konvertiert keine Rechnung in ein anderes Format. Für XRechnung und Peppol BIS gelten jeweils zusätzliche Anforderungen; ein EN-16931-Prüfergebnis bestätigt diese nicht automatisch.

PDF und E-Rechnung validieren: geeignete Prüfwerkzeuge

Für das hier gezeigte ZUGFeRD-PDF ist BillingEngine ein passender erster Prüfschritt, weil es laut Anbieter Rechnungs-XML und ausgewählte PDF-Containermerkmale gemeinsam prüft. Ergänze diese Prüfung durch veraPDF für die PDF/A-Konformität. Ein einziges grünes Ergebnis deckt nicht automatisch alle Ebenen ab.

1. BillingEngine: Rechnungs-XML und PDF-Container prüfen

Der E-Rechnungsvalidator von BillingEngine nimmt laut Anbieter UBL- und CII-XML sowie ZUGFeRD- und Factur-X-PDFs entgegen. Er prüft XML-Schemata und Geschäftsregeln per Schematron. Zusätzliche XRechnung-Regeln werden angewendet, wenn sich die Rechnung über BT-24 als XRechnung ausweist.

Bei PDFs prüft er außerdem unter anderem XMP-Metadaten, PDF/A-3-Kennzeichnung, Output Intent, XML-Dateinamen, MIME-Typ, AFRelationship und /AF. Er gleicht die Profilangaben in den PDF-Metadaten mit der XML-Kennung ab. Die Ergebnisseite nennt das erkannte Profil und die angewendeten Regelwerke.

Geeignet für: Die erste technische Prüfung einer mit Fluid-FPDF erzeugten ZUGFeRD-/Factur-X-Datei, insbesondere ihrer XML-Einbettung und Profilkonsistenz.

Grenzen laut Anbieter: Keine vollständige PDF/A-Validierung, kein ZUGFeRD 1.0, keine Peppol-eigenen Regeln, maximal 2 MB pro Datei und kein herunterladbarer Prüfbericht. Die Prüfung erfolgt ohne Anmeldung auf einem Server in Frankfurt; temporäre Dateien werden nach der Anfrage gelöscht, Inhalte und Dateinamen nicht protokolliert.

Diese Angaben beruhen auf der Anbieter-Auskunft vom September 2026 und sind keine unabhängige Zertifizierung. Beachte den auf der Ergebnisseite ausgewiesenen Prüfumfang.

2. veraPDF: PDF/A-Konformität prüfen

veraPDF ist ein Open-Source-Validator für PDF/A und PDF/UA. Verwende für dieses Beispiel die Prüfung auf PDF/A-3b. Sie deckt die PDF/A-Anforderungen ab, etwa an eingebettete Schriften, Farbräume und Dokumentstruktur, und ergänzt damit die Rechnungsprüfung.

Geeignet für: Die technische Kontrolle des erzeugten PDF/A-Dokuments und die Einbindung einer lokalen Dateiformatprüfung in Entwicklungs- oder CI-Prozesse.

Grenze: Ein bestandenes PDF/A-Ergebnis sagt nichts darüber aus, ob die eingebettete Rechnung die Geschäftsregeln der EN 16931, eines ZUGFeRD-Profils oder von XRechnung erfüllt.

3. E-Rechnungs-Checker: Rechnung prüfen und XML visualisieren

Der E-Rechnungs-Checker bietet die Prüfung und lesbare Darstellung von E-Rechnungen. Er akzeptiert PDF- und XML-Dateien und unterstützt unter anderem ZUGFeRD, Factur-X, XRechnung, CII und UBL. Die Darstellung der XML-Daten hilft Dir beim manuellen Abgleich mit dem sichtbaren Rechnungs-PDF.

Geeignet für: Eine ergänzende Prüfung und die Kontrolle der strukturierten Rechnungsinhalte ohne manuelles Lesen des XML.

Grenzen: Die Visualisierung ersetzt keinen automatischen Nachweis, dass PDF und XML inhaltlich identisch sind. Eine vollständige PDF/A-Prüfung solltest Du separat durchführen. Laut Website werden Datei und Ergebnisse nach 30 Minuten gelöscht; das Upload-Limit beträgt 10 MB (Stand September 2026).

4. service-bw: zusätzliche Prüfung für XRechnung-XML

Der E-Rechnungs-Validator von service-bw ist eine zusätzliche Anlaufstelle für die Prüfung von XRechnung-XML. Verwende ihn, wenn Du gezielt eine XRechnung erzeugst, und beachte die in der Anwendung unterstützten Versionen und ausgewiesenen Prüfregeln.

Geeignet für: Die ergänzende XML-Prüfung in einem XRechnung-Workflow.

Grenze: Betrachte ein XML-Prüfergebnis nicht als Nachweis für die PDF/A-Konformität oder die korrekte Einbettung der XML in ein ZUGFeRD-PDF.

Empfohlener Testablauf für TYPO3 und FPDF

1. Rechnungs-XML erzeugen: Verwende reale Datenstrukturen mit anonymisierten Testdaten und einem ausdrücklich gewählten Profil.
2. XML validieren: Prüfe XML-Schema (XSD), Pflichtfelder und Schematron-Geschäftsregeln. Korrigiere Fehler vor der Einbettung.
3. PDF aus Fluid erzeugen: Rendere das Rechnungslayout mit eingebetteten Schriften und der zugehörigen XML-Datei.
4. Fertige Datei prüfen: Kontrolliere XML, Profilmetadaten und Container gemeinsam, anschließend PDF/A-3b mit veraPDF.
5. PDF und XML vergleichen: Prüfe besonders Rundungen, Rabatte, mehrere Steuersätze, Steuerbefreiungen und Gutschriften, soweit Deine Anwendung sie unterstützt.
6. Regressionen erkennen: Wiederhole die Prüfungen nach Änderungen an TYPO3, Fluid-FPDF, Schriften oder Templates. Halte Datum, verwendete Versionen und Prüfergebnisse fest.

Verwende für Online-Validatoren bevorzugt anonymisierte Testrechnungen. Für automatisierte Tests in GitLab CI oder anderen CI/CD-Pipelines solltest Du geeignete lokal ausführbare Validatoren einsetzen und die verwendeten Regelwerksversionen nachvollziehbar verwalten.

Typische Fehler und Lösungen

„All fonts must be embedded in PDF/A“

Wenn Du diesen Fehler erhältst:

if($font['type']=='Core') $this->Error('All fonts must be embedded in PDF/A');

wird eine nicht eingebettete PDF-Standardschrift verwendet. Registriere die benötigten Schriften mit fpdf:addFont und wähle die registrierte Familie anschließend mit fpdf:setFont. Prüfe auch fett und kursiv formatierte Textstellen sowie Kopf- und Fußzeilen.

Die XML-Datei wird nicht gefunden

Prüfe den an fpdf:setXmlFile übergebenen Pfad, die Dateiberechtigungen und ob die XML vor dem Rendern tatsächlich erzeugt wurde. Bei parallelen Rechnungsprozessen benötigt jede Rechnung ihre eigene Datei, damit keine fremden Rechnungsdaten eingebettet werden.

Das PDF öffnet sich, besteht aber die Validierung nicht

Ein PDF-Viewer prüft keine vollständige PDF/A- oder E-Rechnungskonformität. Ordne die Fehlermeldung zunächst einer Ebene zu: PDF-Struktur, XML-Schema, Geschäftsregeln oder Profilmetadaten. Behebe dann die Ursache und validiere die neu erzeugte Datei erneut.

Häufige Fragen zu PDF/A und E-Rechnungen mit TYPO3

Erzeugt FPDF automatisch eine ZUGFeRD-Rechnung?

Nein. Eine gewöhnliche FPDF-Ausgabe genügt nicht. Dieses Fluid-FPDF-Beispiel verwendet die PDF/A-Ausgabe und eine vorhandene XML-Datei. Zusätzlich müssen das Rechnungslayout, die strukturierten Daten und die erforderlichen Metadaten zusammenpassen.

Erzeugt fpdf:setXmlFile das Rechnungs-XML?

Im gezeigten Ablauf übergibst Du eine bereits vorhandene XML-Datei. Die Aufbereitung Deiner Rechnungsdaten und die XML-Erzeugung gehören in die vorgelagerte Anwendungslogik.

Reicht ein gültiges PDF/A-3b für eine gültige E-Rechnung?

Nein. PDF/A betrifft das Dokumentformat. XML-Schema, Geschäftsregeln und Profilanforderungen müssen zusätzlich geprüft werden. Auch die Übereinstimmung der sichtbaren und strukturierten Rechnungsdaten gehört zur Qualitätssicherung.

Welcher Validator ist für dieses Beispiel am sinnvollsten?

Beginne für ein ZUGFeRD-/Factur-X-PDF mit der kombinierten XML- und Containerprüfung von BillingEngine und ergänze veraPDF für PDF/A-3b. Für die lesbare Darstellung der XML-Daten eignet sich der E-Rechnungs-Checker; für XRechnung-XML kannst Du service-bw zusätzlich heranziehen.