ZUGFeRD-CSharp Documentation

The XRechnung Bundle is an integrated collection of components designed to support the XRechnung standard. It includes the specification, syntax bindings, validation tools, and visualization resources required to work with XRechnung XML documents.

Bundle Components (Version 2.3.1):

The Validator is a domain-agnostic program that checks XML documents against specific validation rules (XML Schema and Schematron) based on their document types.

Key Behaviors:

• Aggregation: It aggregates results into a conformity report containing a status (valid or invalid) and a recommendation (accept or reject).
• Configuration-Driven: The tool itself does not know specific document contents or rules. It relies on a Validator Configuration to define which rules to apply.
• Rule Flexibility: Through configuration, you can specify which conformity rules a document is allowed to violate while still receiving an accept recommendation for further processing.

The project uses Semantic Versioning (MAJOR.MINOR.PATCH). Understanding these increments is critical for managing XML validation compatibility:

• MAJOR version: Incremented for incompatible changes. Rules are updated such that XML previously valid under a previous major version will DEFINITELY NOT validate against the new version.
• MINOR version: Incremented when adding functionality (e.g., adding new codelist terms or accepting new optional XML elements). CAUTION: A minor update might break your specific validation scenario or your ability to accept certain XML content.
• PATCH version: Incremented for backwards-compatible bug fixes.

When adding trade line items via AddTradeLineItem, you can choose between two modes:

1. Automatic ID Generation: If you do not provide a lineID, the library generates sequential IDs (e.g., '1', '2').
2. Manual ID Assignment: If you provide a lineID string, the library uses your specific identifier. This is useful when converting existing ERP system invoices to ZUGFeRD/Factur-X.

Use the lineID parameter in the AddTradeLineItem method to control this behavior.

// Automatic generation
desc.AddTradeLineItem("Item name", 23.99m, QuantityCodes.H87, "Detail description", ...);

// Manual assignment (e.g., for ERP migration)
desc.AddTradeLineItem(lineID: "0001", 23.99m, QuantityCodes.H87, "Item name", "Detail description", ...);

ZUGFeRD implementations often involve complex XML structures based on FacturX or UBL (Universal Business Language). If you need to understand the underlying schema and data models for these formats, refer to the official documentation links provided below.

• FacturX Documentation: http://doc.factoorsharp.com/
• UBL Invoice Syntax (Peppol): https://docs.peppol.eu/poacc/billing/3.0/syntax/ubl-invoice/

The xrechnung-schematron component provides the technical implementation of the XRechnung business rules using Schematron rules for XML validation.

Note on recent updates (v1.8.2):

• Includes merged UBL Invoice and CreditNote code.
• Introduces new rules: BR-DEX-13, BR-DEX-14, and BR-DEX-15.
• Warning: These new rules may trigger error messages if existing normative requirements are not met, as they are being integrated into the specification's informational tables.

To validate XRechnung documents using the generic Validator tool, you must provide an XRechnung Validator Configuration. This configuration contains all necessary resources for the EN16931 standard, including:

• XML Schemas
• Schematron rules (via xrechnung-schematron)
• Current versions of all required validation assets.

This configuration bridges the gap between the generic validator engine and the specific requirements of the XRechnung standard.

The XRechnung Testsuite provides a collection of valid test documents that adhere to the XRechnung standard.

Use cases:

• Software Development: Use these documents to test IT specialist processes (Fachverfahren) to ensure they correctly interpret the XRechnung specification.
• Integration Testing: Incorporate these documents into your own testing procedures to verify compliance with complex specification requirements.

To use the library in your project, install the ZUGFeRD-csharp package using NuGet or the Visual Studio Package Manager.

dotnet add package ZUGFeRD-csharp