Documentation & getting started

Quick start

From PDF to compliance verdict in three steps. The example below mirrors the actual flow used by the live demo.

1. Add the Facturexa.ZugferdValidator package via NuGet. The official rule sets (XML schema and Schematron) are included and found automatically.
2. Register the license key once at application startup. You receive it by email and can always find it in your customer account.
3. For each invoice, validate the PDF (or the XML) with a single call.

using Facturexa.ZugferdValidator;

// Once at application startup: register the license key.
ZugferdValidatorLicense.RegisterLicense("…");

// Validate the invoice PDF: PDF container, XML schema and official Schematron in one call.
var result = ZugferdValidator.Validate("invoice.pdf", "INV-2026-0001");

Console.WriteLine(result.IsValid ? "Valid" : "Not compliant");

The complete flow with error handling follows in the Validator section.

Installation & requirements

Each library is a separate NuGet package and can be referenced on its own.

Deploying the rule sets (Validator)

• Offline operation: all rule sets (XML schema, Schematron, code lists) ship with the package. No internet connection is needed at runtime and the Validator calls no external service – the license check is local as well. No firewall rule is required.
• The package copies Official Schematron\ (the Schematron rule sets and, under XSD\, the XML schema) next to your application automatically on build and publish – also for classic ASP.NET (under bin\), single-file, ClickOnce, and when you reference the Validator through your own library or your own NuGet package.
• After downgrading the package, clean or rebuild the solution once so the older rule set files replace the newer ones in the output folder.
• Providing the folder yourself: set <FacturexaContentAutoCopy>false</FacturexaContentAutoCopy> in the project, with PackageReference additionally ExcludeAssets="contentFiles" on the package reference, and set SchematronChecker.SchematronDirectory to the folder.

Profiles & versions

ZUGFeRD defines several profiles with different levels of detail. The overview below shows which ones the Validator checks and the Creator generates.

Version

The Creator always writes the current specification: ZUGFeRD 2.5.2 / Factur-X 1.09.2 (effective from 1 September 2026), including the EXTENDED sub-lines for kits and bundles. You do not choose a version in Save(…) – new specifications arrive with a new package version.

Which specification the referenced DLL implements can be queried at runtime: ZugferdCreatorInfo.SupportedSpecification.

Validator: validate a PDF

Register the license key once at application startup. The Validator finds the official rule sets automatically next to the DLL (under bin\ for classic ASP.NET); after that, one call per validation is enough. Pass the complete PDF: the Validator extracts the embedded XML itself, checks the PDF container (PDF/A-3, Factur-X metadata) and then the XML against the XML schema and the official Schematron. A plain XML file works the same way – detected from the content, not the extension. IsValid is true if no stage reports an error; IsPdfValid and IsSchemaValid give the partial verdicts.

using Facturexa.ZugferdValidator;

// Once at application startup.
ZugferdValidatorLicense.RegisterLicense("…");

// PDF or XML: PDF container, XML schema and official Schematron in one call.
var result = ZugferdValidator.Validate("invoice.pdf", "INV-2026-0001");

Console.WriteLine(result.IsValid ? "Valid" : "Not compliant");
Console.WriteLine($"PDF container: {result.IsPdfValid}"); // null for a plain XML
Console.WriteLine($"Rule set: {result.SchematronRuleSet}");

foreach (var error in result.Errors)
    Console.WriteLine($"{error.Stage}: {error}"); // e.g. "Schematron: BR-CO-15 (BT-112): ..."

Further reading: Validator product page · Try the live demo

Creator: create an invoice

Register the license key once at application startup, then set the invoice header, parties, lines and totals, choose a profile and save. Output is currently CII (UBL is on the roadmap).

using Facturexa.ZugferdCreator;

// Once at application startup.
ZugferdCreatorLicense.RegisterLicense("…");

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

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

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

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

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

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

Further reading: Creator product page · Try the live demo

Reader: read an invoice

The Reader reads an invoice – as plain XML (CII or UBL) or as a PDF with embedded XML; the format is detected automatically – and returns the fields as an object. Optionally it renders a readable PDF view from it.

using Facturexa.ZugferdReader;

// Read a PDF or XML – the file name helps with format detection.
using var stream = File.OpenRead("invoice.pdf");
var invoice = ZugferdReader.Read(stream, "invoice.pdf");

Console.WriteLine(invoice.InvoiceNumber);
Console.WriteLine(invoice.InvoiceDate?.ToString("yyyy-MM-dd"));
Console.WriteLine(invoice.Seller?.Name);
Console.WriteLine($"{invoice.LineItems.Count} line(s), {invoice.GrandTotalAmount:N2} {invoice.CurrencyCode}");

// Optional: render a readable PDF view of the invoice.
byte[] viewPdf = ZugferdReader.CreatePdf(invoice);
File.WriteAllBytes("invoice-view.pdf", viewPdf);

Further reading: Reader product page · Try the live demo

Return values

The most important fields of the result objects at a glance.

ZugferdValidationResult – Validator.Validate(…)

ZugferdPdfCheckResult – ZugferdValidationResult.PdfCheck

Previous API: ZugferdPdfReader.ReadZugferdXml(…) and ZugferdPdfValidator.Validate(…) keep working until version 8.0 but are marked obsolete since 7.4.0. Pass the PDF directly to ZugferdValidator.Validate(…) instead.

InvoiceViewModel – ZugferdReader.Read(…)

Error handling & troubleshooting

The most common pitfalls during integration and their cause.

Next steps