ZUGFeRD mit Java: Mustangproject im Einsatz

Letzte Aktualisierung: 1. Mai 2026

Mustangproject einbinden

Per Maven:

<dependency>
  <groupId>org.mustangproject</groupId>
  <artifactId>library</artifactId>
  <version>2.14.0</version>
</dependency>

Per Gradle:

implementation 'org.mustangproject:library:2.14.0'

Konzept: Wie Mustangproject aufgebaut ist

Mustangproject bietet zwei Wege, eine ZUGFeRD-Rechnung zu erzeugen:

• High-Level API (ZUGFeRDExporterFromPDFA): Du lieferst eine vorhandene PDF und ein befülltes Transaktions-Objekt — Mustangproject baut die PDF/A-3 mit eingebettetem XML zusammen.
• Low-Level XML-Zugriff: Direkter Zugriff auf die XML-Struktur, falls du volle Kontrolle über jedes Feld benötigst.

Einfaches Beispiel: Rechnung erzeugen

import org.mustangproject.ZUGFeRD.*;
import org.mustangproject.*;
import java.math.BigDecimal;
import java.util.Date;

// Transaktionsdaten befüllen
IZUGFeRDExportableTransaction transaction = new ZUGFeRDExportableTransaction() {

    @Override
    public IZUGFeRDTradeParty getSender() {
        return new TradeParty("Muster GmbH", "Musterstraße 1", "10115", "Berlin", "DE")
            .addTaxID("12/345/67890")
            .addVATID("DE123456789");
    }

    @Override
    public IZUGFeRDTradeParty getRecipient() {
        return new TradeParty("Kunde AG", "Kundenstraße 5", "20095", "Hamburg", "DE");
    }

    @Override
    public String getNumber() { return "RE-2025-001"; }

    @Override
    public Date getIssueDate() { return new Date(); }

    @Override
    public Date getDueDate() {
        // 30 Tage Zahlungsziel
        return new Date(System.currentTimeMillis() + 30L * 24 * 60 * 60 * 1000);
    }

    @Override
    public IZUGFeRDExportableItem[] getZFItems() {
        Product produkt = new Product("Webentwicklung", "Monat März 2025", "HUR", new BigDecimal("19"));
        return new IZUGFeRDExportableItem[]{
            new Item(produkt, new BigDecimal("500.00"), new BigDecimal("1"))
        };
    }
};

// PDF erzeugen und ZUGFeRD einbetten
ZUGFeRDExporterFromPDFA exporter = new ZUGFeRDExporterFromPDFA()
    .load("vorlage.pdf")              // Deine visuelle Rechnungs-PDF (PDF/A-1 oder besser)
    .setProducer("Meine Anwendung")
    .setCreator("Muster GmbH")
    .setZUGFeRDVersion(2)
    .setProfile(Profiles.getByName("EN16931"));

exporter.setTransaction(transaction);
exporter.export("rechnung_zugferd.pdf");

ZUGFeRD-Rechnung lesen und parsen

ZUGFeRDImporter importer = new ZUGFeRDImporter("rechnung_eingegangen.pdf");

if (importer.canParse()) {
    System.out.println("Rechnungsnummer: " + importer.getInvoiceID());
    System.out.println("Gesamtbetrag:    " + importer.getAmount());
    System.out.println("Fällig am:       " + importer.getDueDate());
    System.out.println("Aussteller:      " + importer.getHolder());
    System.out.println("IBAN:            " + importer.getIBAN());
    System.out.println("Profil:          " + importer.getVersion());
}

Validierung mit Mustangproject CLI

Mustangproject kommt auch als ausführbares JAR, das du als CLI-Validator einsetzen kannst:

# JAR herunterladen von mustangproject.org, dann:
java -jar Mustang-CLI.jar --action validate --source rechnung.pdf

Die Ausgabe enthält Fehler, Warnungen und das erkannte Profil. Ideal für automatisierte Tests in der CI/CD-Pipeline: Exit-Code 0 = valide, Exit-Code ≠ 0 = Fehler gefunden.

PDF-Voraussetzung: PDF/A-Kompatibilität

ZUGFeRD schreibt das PDF/A-3-Format vor. Deine Ausgangs-PDF muss kompatibel sein. Für die Erzeugung einer validen PDF/A-3-Basis:

• PDFBox: Apache-Projekt, weit verbreitet, kann PDF/A-1 erzeugen
• iText (AGPL): Leistungsstark, aber Lizenz beachten (AGPL für Open Source, kostenpflichtig kommerziell)
• OpenPDF: Fork von iText 4, LGPL-lizenziert
• Mustangproject selbst: Kann mit PDFBox im Hintergrund eine valide PDF/A-3 erstellen

XRechnung mit Mustangproject erzeugen

exporter.setProfile(Profiles.getByName("XRechnung"));

Das Profil-Objekt steuert alle profilspezifischen Pflichtfelder. Für XRechnung an Behörden muss zusätzlich die Leitwegsnummer (Buyer Reference) gesetzt werden:

// In der Transaktionsimplementierung:
@Override
public String getBuyerOrderReferencedDocumentID() {
    return "991-12345678-06"; // Leitwegsnummer des Auftraggebers
}

Häufige Fehler

• PDF ist kein PDF/A: Mustangproject gibt einen Fehler aus, wenn die Quell-PDF nicht PDF/A-kompatibel ist. Abhilfe: PDF zuvor mit PDFBox oder einem Konverter auf PDF/A-1b konvertieren.
• Betrag als double statt BigDecimal: Immer BigDecimal für Geldbeträge nutzen — Floating-Point-Rechnung erzeugt Rundungsfehler, die zur Validierungsabweichung führen.
• Falsche Profil-String-Schreibweise: Profiles.getByName("EN16931") — nicht "en16931" oder "En 16931". Schreibweise in der Mustangproject-Dokumentation nachschlagen.

Häufige Fragen

Gibt es eine Spring Boot-Integration für Mustangproject?
Eine offizielle Starter-Dependency gibt es nicht, aber die Bibliothek ist ein normales Maven-Artefakt und lässt sich problemlos als Spring Bean einbinden. GitHub-Beispiele zeigen typische Integrationspattern.

Unterstützt Mustangproject auch ZUGFeRD 1.x?
Lesen ja — ältere Dateien mit dem CrossIndustryDocument-Root-Element werden erkannt und geparst. Erzeugen: Ab Mustangproject 2.x liegt der Fokus auf ZUGFeRD 2.x. Neue Implementierungen sollten immer 2.x nutzen.

Weiterführend: X-Ray-Viewer — ZUGFeRD direkt im Browser prüfen · ZUGFeRD XML-Struktur für Entwickler