Dokumentation & erste Schritte

Schnellstart

In drei Schritten von der PDF zur Konformitätsaussage. Das folgende Beispiel entspricht dem tatsächlichen Ablauf, den auch die Live-Demo verwendet.

1. Paket Facturexa.ZugferdValidator per NuGet hinzufügen. Die amtlichen Regelwerke (XML-Schema und Schematron) werden mitgeliefert und automatisch gefunden.
2. Einmalig beim Programmstart den Lizenzschlüssel registrieren. Sie erhalten ihn per E-Mail und finden ihn jederzeit im Kundenkonto.
3. Pro Rechnung die PDF (oder die XML) mit einem Aufruf validieren.

using Facturexa.ZugferdValidator;

// Einmalig beim Programmstart: Lizenzschlüssel registrieren.
ZugferdValidatorLicense.RegisterLicense("…");

// Rechnungs-PDF prüfen: PDF-Hülle, XML-Schema und offizielle Schematron in einem Aufruf.
var ergebnis = ZugferdValidator.Validate("rechnung.pdf", "RE-2026-0001");

Console.WriteLine(ergebnis.IsValid ? "Gültig" : "Nicht konform");

Der vollständige Ablauf mit Fehlerbehandlung folgt im Abschnitt Validator.

Installation & Voraussetzungen

Jede Bibliothek ist ein eigenständiges NuGet-Paket und kann einzeln eingebunden werden.

Bereitstellung der Regelwerke (Validator)

• Offline-Betrieb: Alle Regelwerke (XML-Schema, Schematron, Codelisten) sind im Paket enthalten. Zur Laufzeit ist keine Internetverbindung nötig, und der Validator ruft keinen externen Dienst auf – auch die Lizenzprüfung erfolgt lokal. Eine Firewall-Freigabe ist nicht erforderlich.
• Das Paket kopiert Official Schematron\ (Schematron-Regelwerke und unter XSD\ das XML-Schema) beim Build und beim Veröffentlichen automatisch neben Ihre Anwendung – auch bei klassischem ASP.NET (unter bin\), Single-File, ClickOnce und wenn Sie den Validator über eine eigene Bibliothek oder ein eigenes NuGet-Paket einbinden.
• Nach einem Downgrade des Pakets die Lösung einmal bereinigen bzw. neu erstellen, damit die älteren Regelwerksdateien die neueren im Ausgabeordner ersetzen.
• Ordner selbst bereitstellen: <FacturexaContentAutoCopy>false</FacturexaContentAutoCopy> im Projekt setzen, bei PackageReference zusätzlich ExcludeAssets="contentFiles" am Paketverweis, und SchematronChecker.SchematronDirectory auf den Ordner setzen.

Profile & Versionen

ZUGFeRD kennt mehrere Profile mit unterschiedlicher Informationsdichte. Welche der Validator prüft und der Creator erzeugt, zeigt die folgende Übersicht.

Version

Der Creator erzeugt immer nach dem aktuellen Stand: ZUGFeRD 2.5.2 / Factur-X 1.09.2 (gültig ab 01.09.2026), inklusive der EXTENDED-Sub-Positionen für Kits und Bündel. Eine Version wählen Sie beim Save(…) nicht aus – neue Spezifikationen kommen mit einer neuen Paketversion.

Welchen Stand die eingebundene DLL umsetzt, lässt sich zur Laufzeit abfragen: ZugferdCreatorInfo.SupportedSpecification.

Validator: eine PDF prüfen

Den Lizenzschlüssel registrieren Sie einmal beim Programmstart. Die amtlichen Regelwerke findet der Validator automatisch neben der DLL (bei klassischem ASP.NET unter bin\); danach genügt ein Aufruf pro Prüfung. Übergeben Sie die komplette PDF: Der Validator liest die eingebettete XML selbst, prüft die PDF-Hülle (PDF/A-3, Factur-X-Metadaten) und danach die XML gegen das XML-Schema und die offizielle Schematron. Eine reine XML-Datei geht genauso – erkannt wird am Inhalt, nicht an der Endung. IsValid ist true, wenn keine Stufe einen Fehler meldet; IsPdfValid und IsSchemaValid liefern die Teilurteile.

using Facturexa.ZugferdValidator;

// Einmalig beim Programmstart.
ZugferdValidatorLicense.RegisterLicense("…");

// PDF oder XML: PDF-Hülle, XML-Schema und offizielle Schematron in einem Aufruf.
var ergebnis = ZugferdValidator.Validate("rechnung.pdf", "RE-2026-0001");

Console.WriteLine(ergebnis.IsValid ? "Gültig" : "Nicht konform");
Console.WriteLine($"PDF-Hülle: {ergebnis.IsPdfValid}"); // null bei reiner XML
Console.WriteLine($"Regelwerk: {ergebnis.SchematronRuleSet}");

foreach (var fehler in ergebnis.Errors)
    Console.WriteLine($"{fehler.Stage}: {fehler}"); // z.B. "Schematron: BR-CO-15 (BT-112): ..."

Weiterführend: Produktseite Validator · Live-Demo testen

Creator: eine Rechnung erzeugen

Lizenzschlüssel einmal beim Programmstart registrieren, dann Rechnungskopf, Parteien, Positionen und Summen setzen, Version und Profil wählen, speichern. Aktuell wird CII ausgegeben (UBL ist auf der Roadmap).

using Facturexa.ZugferdCreator;

// Einmalig beim Programmstart.
ZugferdCreatorLicense.RegisterLicense("…");

var rechnung = new EInvoice
{
    InvoiceNumber = "RE-2026-0001",
    InvoiceDate = DateTime.Today
};

rechnung.SetSellerTradeParty("Muster GmbH", "12345", "Berlin", "Musterstraße 1", CountryID.DE);
rechnung.AddSellerSpecifiedTaxRegistration("DE123456789", TaxRegistrationSchemeID.VA);
rechnung.SetBuyerTradeParty("Kunde AG", "54321", "Hamburg", "Kundenweg 2", CountryID.DE);

rechnung.AddIncludedSupplyChainTradeLineItem(
    name: "Beratungsleistung", netUnitPrice: 100.00m, unitCode: UnitCode.C62,
    billedQuantity: 3m, lineTotalAmount: 300.00m, taxPercent: 19m);

rechnung.AddApplicableTradeTax(300.00m, 19m, 57.00m, TaxTypeCode.VAT, TaxCategoryCode.S);

rechnung.LineTotalAmount = 300.00m;
rechnung.TaxBasisAmount = 300.00m;
rechnung.TaxTotalAmount = 57.00m;
rechnung.GrandTotalAmount = 357.00m;
rechnung.DuePayableAmount = 357.00m;

using var xmlStream = new MemoryStream();
rechnung.Save(xmlStream, InvoiceProfile.Comfort);

Weiterführend: Produktseite Creator · Live-Demo testen

Reader: eine Rechnung auslesen

Der Reader liest eine Rechnung – als blanke XML (CII oder UBL) oder als PDF mit eingebetteter XML; das Format wird automatisch erkannt – und gibt die Felder als Objekt zurück. Optional rendert er daraus eine lesbare PDF-Ansicht.

using Facturexa.ZugferdReader;

// PDF oder XML einlesen – der Dateiname hilft bei der Formaterkennung.
using var stream = File.OpenRead("rechnung.pdf");
var rechnung = ZugferdReader.Read(stream, "rechnung.pdf");

Console.WriteLine(rechnung.InvoiceNumber);
Console.WriteLine(rechnung.InvoiceDate?.ToString("dd.MM.yyyy"));
Console.WriteLine(rechnung.Seller?.Name);
Console.WriteLine($"{rechnung.LineItems.Count} Position(en), {rechnung.GrandTotalAmount:N2} {rechnung.CurrencyCode}");

// Optional: lesbare PDF-Ansicht der Rechnung erzeugen.
byte[] ansichtPdf = ZugferdReader.CreatePdf(rechnung);
File.WriteAllBytes("rechnung-ansicht.pdf", ansichtPdf);

Weiterführend: Produktseite Reader · Live-Demo testen

Rückgabewerte

Die wichtigsten Felder der Ergebnisobjekte im Überblick.

ZugferdValidationResult – Validator.Validate(…)

ZugferdPdfCheckResult – ZugferdValidationResult.PdfCheck

Bisherige API: ZugferdPdfReader.ReadZugferdXml(…) und ZugferdPdfValidator.Validate(…) funktionieren bis Version 8.0 weiter, sind seit 7.4.0 aber als veraltet markiert. Übergeben Sie stattdessen die PDF direkt an ZugferdValidator.Validate(…).

InvoiceViewModel – ZugferdReader.Read(…)

Fehlerbehandlung & Troubleshooting

Die häufigsten Stolpersteine bei der Integration und ihre Ursache.

Nächste Schritte