ZUGFeRD-csharp 11.1.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package ZUGFeRD-csharp --version 11.1.0
NuGet\Install-Package ZUGFeRD-csharp -Version 11.1.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="ZUGFeRD-csharp" Version="11.1.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add ZUGFeRD-csharp --version 11.1.0
#r "nuget: ZUGFeRD-csharp, 11.1.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install ZUGFeRD-csharp as a Cake Addin
#addin nuget:?package=ZUGFeRD-csharp&version=11.1.0

// Install ZUGFeRD-csharp as a Cake Tool
#tool nuget:?package=ZUGFeRD-csharp&version=11.1.0

NuGet

Part of the ZUGFeRD community: https://github.com/zugferd

Introduction

The ZUGFeRD library allows to create XML files as required by German electronic invoice initiative ZUGFeRD as well invoices in the successor Factur-X. One special profile of Factur-X is the German XRechnung format. The library is meant to be as simple as possible, however it is not straight forward to use as the resulting XML file contains a complete invoice in XML format. Please take a look at the ZUGFeRD-Test project to find sample creation code. This code creates the same XML file as shipped with the ZUGFeRD information package.

A description of the library can be found here:

http://www.s2-industries.com/wordpress/2013/11/creating-zugferd-descriptors-with-c/

Sponsoring

Implementing and maintaining this library is a lot of hard work. I'm doing this in my spare time, there is no company behind developing ZUGFeRD-chsarp. Support me in this work and help making this library better:

:heart: Sponsor me on github

Relationship between the different standards

Since there are a lot terms and standards around electronic invoices, I'd like to layout my understanding:

  • ZUGFeRD was developed by a German initiative as a standard for electronic invoices (https://www.ferd-net.de/).
  • ZUGFeRD 2.1 is identical to the German/ French cooperation Factur-X (ZUGFeRD 2.1 = Factur-X 1.0) (https://www.ferd-net.de/standards/what-is-factur-x/index.html).
  • The standard Factur-X 1.0 (respectively ZUGFeRD 2.1) is conform with the European norm EN 16931.
  • EN 16931 in turn is based on worldwide UN/CEFACT standard 'Cross Industry Invoice' (CII).
  • XRechnung as another German standard is a subset of EN 16931. It is defined by another party called KoSIT (https://www.xoev.de/). It comes with its own validation rules (https://www.ferd-net.de/standards/what-is-xrechnung/index.html).
  • This means that both Factur-X 1.0 (respectively ZUGFeRD 2.1) and XRechnung are conform with EN 16931. This does not automatically result that those invoices are per se identical
  • To achieve compatibility, ZUGFeRD 2.1.1 introduced a XRechnung reference profile to guarantee compatibility between the two sister formats

License

Subject to the Apache license http://www.apache.org/licenses/LICENSE-2.0.html

Installation

Just use nuget or Visual Studio Package Manager and download 'ZUGFeRD-chsarp'.

You can find more information about the nuget package here:

NuGet

https://www.nuget.org/packages/ZUGFeRD-csharp/

Building on your own

Prerequisites:

  • Visual Studio >= 2017
  • .net Framework >= 4.6.1 (for .net Standard 2.0 support)

Open ZUGFeRD/ZUGFeRD.sln solution file. Choose Release or Debug mode and hit 'Build'. That's it.

For running the tests, open ZUGFeRD-Test/ZUGFeRD-Test.sln and run the unit tests. The tests show good cases on how to use the library.

Creating invoices

Central class for users is class InvoiceDescriptor. This class does not only allow to read and set all ZUGFeRD attributes and structures but also allows to load and save ZUGFeRD files.

Using InvoiceDescriptor to create invoices is straight forward:

InvoiceDescriptor desc = InvoiceDescriptor.CreateInvoice("471102", new DateTime(2013, 6, 5), CurrencyCodes.EUR, "GE2020211-471102");
desc.ReferenceOrderNo = "AB-312";
desc.AddNote("Rechnung gemäß Bestellung Nr. 2013-471331 vom 01.03.2013.");
desc.AddNote("Es bestehen Rabatt- und Bonusvereinbarungen.", "AAK");
desc.SetBuyer("Kunden Mitte AG", "69876", "Frankfurt", "Kundenstraße", "15", "DE", "88", "4000001987658");
desc.AddBuyerTaxRegistration("DE234567890", "VA");
desc.SetBuyerContact("Hans Muster");
desc.SetSeller("Lieferant GmbH", "80333", "München", "Lieferantenstraße", "20", "DE", "88", "4000001123452");
desc.AddSellerTaxRegistration("201/113/40209", "FC");
desc.AddSellerTaxRegistration("DE123456789", "VA");
desc.SetBuyerOrderReferenceDocument("2013-471331", new DateTime(2013, 03, 01));
desc.SetDeliveryNoteReferenceDocument("2013-51111", new DateTime(2013, 6, 3));
desc.ActualDeliveryDate = new DateTime(2013, 6, 3);
desc.SetTotals(202.76m, 5.80m, 14.73m, 193.83m, 21.31m, 215.14m, 50.0m, 165.14m);
desc.AddApplicableTradeTax(9.06m, 129.37m, 7m, "VAT", "S");
desc.AddApplicableTradeTax(12.25m, 64.46m, 19m, "VAT", "S");
desc.SetLogisticsServiceCharge(5.80m, "Versandkosten", "VAT", "S", 7m);
desc.SetTradePaymentTerms("Zahlbar innerhalb 30 Tagen netto bis 04.07.2013, 3% Skonto innerhalb 10 Tagen bis 15.06.2013", new DateTime(2013, 07, 04));
descriptor.Save("zugferd.xml", ZUGFeRDVersion.Version1, Profile.Basic);

Using ZUGFeRD 1.x, ZUGFeRD 2.x

In order to load ZUGFeRD files, you call InvoiceDescriptor.Load(), passing a file path like this:

InvoiceDescriptor descriptor = InvoiceDescriptor.Load("zugferd.xml");

alternatively, you can pass an open stream object:

Stream stream = new FileStream("zugferd.xml", FileMode.Open, FileAccess.Read);
InvoiceDescriptor descriptor = InvoiceDescriptor.Load(stream);

The library will automatically detect the ZUGFeRD version of the file and parse accordingly. As of today (2020-07-05), parsing ZUGFeRD 2.x is not yet finished. The lifecycle of the stream is not influenced by the ZUGFeRD library, i.e. the library expects an open stream and will not close if after reading from it.

For saving ZUGFeRD files, use InvoiceDescriptor.Save(). Here, you can also pass a stream object:

InvoiceDescriptor descriptor = InvoiceDescriptor.CreateInvoice(......);

// fill attributes and structures

FileStream stream = new FileStream(filename, FileMode.Create, FileAccess.Write);
descriptor.Save(stream, ZUGFeRDVersion.Version1, Profile.Basic);
stream.Flush();
stream.Close();            

As you see, the libary does not influence the lifecycle of the stream, i.e. it is not automatically closed by the library. Just as opening the stream, flushing and closing is the duty of the calling function.

Alternatively, you can pass a file path:

InvoiceDescriptor descriptor = InvoiceDescriptor.CreateInvoice(......);

// fill attributes and structures

descriptor.Save("zugferd.xml", ZUGFeRDVersion.Version1, Profile.Basic);          

Optionally, you can pass the ZUGFeRD version to use, default currently is version 1.x, e.g.:

InvoiceDescriptor descriptor = InvoiceDescriptor.CreateInvoice(......);

// fill attributes and structures


descriptor.Save("zugferd-v1.xml", ZUGFeRDVersion.Version1, Profile.Basic); // save as version 1.x
descriptor.Save("zugferd-v2.xml", ZUGFeRDVersion.Version2, Profile.Basic); // save as version 2.0
descriptor.Save("zugferd-v2.xml", ZUGFeRDVersion.Version21, Profile.Basic); // save as version 2.1

For reading and writing XRechnung invoices, please see below.

Support for XRechnung

In general, creating XRechnung files is straight forward and just like creating any other ZUGFeRD version and profile:

descriptor.Save("xrechnung.xml", ZUGFeRDVersion.Version21, Profile.XRechnung); // save as XRechnung 2.0

This will save the invoice as XRechnung 2.0 as valid from 2021/01/01.

If you want to store invoices which are validated successfully by the KoSIT validator before 2021/01/01, you can still write invoices in the old format:

descriptor.Save("xrechnung.xml", ZUGFeRDVersion.Version21, Profile.XRechnung1); // save as XRechnung 1.2

The content is 100% identical to XRechnung 2.0, just the headers will be different.

Furthermore, XRechnung comes with some special features. One of these features is the ability to embed binary files as attachments to the xrechnung.xml document:

InvoiceDescriptor desc = _createInvoice();
byte[] data = System.IO.File.ReadAllBytes("my-calculation.xlsx");
desc.AddAdditionalReferencedDocument(
    issuerAssignedID: "calculation-sheet",
    typeCode: AdditionalReferencedDocumentTypeCode.ReferenceDocument,
    name: "Calculation as the basis for the invoice",
    attachmentBinaryObject: data,
    filename: "my-calculation.xlsx");

desc.Save("xrechnung.xml", ZUGFeRDVersion.Version21, Profile.XRechnung);            

The resulting xrechnung.xml file will then contain the calculation file content. As this is not standardized, the decision was to encode the attachments in base64. Please note that there are only few mime types supported by the XRechnung standard. The supported mime types are defined in BG-24 and BT-125. At the time of writing this tutorial, those are also listed in the discussion you find over here: https://projekte.kosit.org/xrechnung/xrechnung/-/issues/59

  • application/pdf
  • image/png
  • image/jpeg
  • text/csv
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.oasis.opendocument.spreadsheet
  • application/xml

Support for profiles

The library contains support for all profiles that are supported by the ZUGFeRD formats:

Profile Version1 Version2 Version21
MINIMUM X X
BASIC WL X X
BASIC X X X
COMFORT/EN16391 X X X
XRECHNUNG X
EXTENDED X X X

please note that version 1 implementation of the library is not strict, i.e. it will output all information available into the invoice xml, regardless of the profiles that is used. Reading various files with different profiles will generate the correct output.

Beginning with version 2.1, the output is corresponding exactly to the profile that is used.

If you want to write the invoice xml with a certain ZUGFeRD version and a certain profile, make sure to use the parameters of the Save method:

descriptor.Save("zugferd-v1.xml", ZUGFeRDVersion.Version1, Profile.Basic); // save as version 1.x, profile Basic
descriptor.Save("zugferd-v2.xml", ZUGFeRDVersion.Version2, Profile.Basic); // save as version 2.0, profile Basic
descriptor.Save("zugferd-v2.xml", ZUGFeRDVersion.Version21, Profile.Basic); // save as version 2.1, profile Basic
descriptor.Save("zugferd-v2.xml", ZUGFeRDVersion.Version21, Profile.XRechnung); // save as version 2.1, profile XRechnung

Handling of line ids

The library allows to operate in two modes: you can either let the library generate the line ids automatically or you can alternatively pass distinct line ids. This is helpful if you want to convert existing invoices, e.g. from ERP systems, to ZUGFeRD/ Factur-X.

To let the library create line ids, you can use:

InvoiceDescriptor desc = InvoiceDescriptor.CreateInvoice("471102", new DateTime(2013, 6, 5), CurrencyCodes.EUR, "GE2020211-471102");
desc.AddTradeLineItem("Item name", "Detail description", QuantityCodes.PCE, ....);

This will generate an invoice with trade line item numbered as '1'.

To pass pre-defined line ids, this is the way to go:

InvoiceDescriptor desc = InvoiceDescriptor.CreateInvoice("471102", new DateTime(2013, 6, 5), CurrencyCodes.EUR, "GE2020211-471102");
desc.AddTradeLineItem(lineId: "0001", "Item name", "Detail description", QuantityCodes.PCE, ....);
desc.AddTradeLineItem(lineId: "0002", "Item name", "Detail description", QuantityCodes.PCE, ....);

which will generate an invoice with two trade line items, with the first one as number '0001' and the second one as number '0002'.

Special references

The library allows to add special references to an invoice which are pretty rare but nevertheless supported:

// you can optionally add a reference to a procuring project:
desc.SpecifiedProcuringProject = new SpecifiedProcuringProject {Name = "Projekt AB-312", ID = "AB-312"};

// you can optionally reference a contract:
desc.ContractReferencedDocument = new ContractReferencedDocument {ID = "AB-312-1", Date = new DateTime(2013,1,1)};

Working with product characteristics

Product characteristics are used to add information for the specified trade product in the 'ApplicableProductCharacteristic' section. One trade product can have one or more product characteristics, which can contain description, value, typecode and value measurand elements.

// you can optionally add product characteristics:
desc.TradeLineItems.Add(new TradeLineItem()
{
   ApplicableProductCharacteristics = new List<ApplicableProductCharacteristic>
   {
       new ApplicableProductCharacteristic()
       {
           Description = "Description",
           Value = "Value"
       }
   }
});

Extracting xml attachments from pdf files

I am frequently asked how to extract the ZUGFeRD/ Factur-X/ XRechnung attachment from existing PDF files.

There is a nice article on stackoverflow on how this can be achieved using itextsharp:

https://stackoverflow.com/a/6334252

and this one covers the same with itext7 which is the successor of itextsharp:

https://stackoverflow.com/a/37804285

Writing xml attachments to pdf files

It is also possible to add the xml ZUGFeRD or XRechnung attachment to pdf files using itextsharp. You find information about this here:

https://stackoverflow.com/questions/70597318/af-reference-to-file-embedded-into-a-pdf-with-itextsharp

(thanks @floace2000ace)

Thanks

You can find more information about ZUGFeRD here: http://www.ferd-net.de/

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 is compatible.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 is compatible.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • .NETFramework 4.6.1

    • No dependencies.
  • .NETFramework 4.8

    • No dependencies.
  • .NETStandard 2.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
12.8.0 1,815 3/13/2024
12.7.0 1,253 3/4/2024
12.6.0 1,095 2/27/2024
12.5.0 3,418 1/25/2024
12.4.0 4,655 12/11/2023
12.3.1 3,877 11/23/2023
12.3.0 428 11/23/2023
12.2.0 2,211 10/27/2023
12.1.2 3,119 10/5/2023
12.1.1 1,733 9/24/2023
12.1.0 494 9/24/2023
12.0.1 5,969 8/3/2023
12.0.0 1,518 7/30/2023
11.3.0 2,418 7/11/2023
11.2.0 11,458 7/3/2023
11.1.0 12,020 5/21/2023
11.0.0 1,148 5/1/2023
10.0.0 19,126 1/10/2023
9.0.0 16,086 6/29/2022
8.0.0 1,302 6/16/2022
7.0.1 9,871 2/7/2022
7.0.0 1,518 12/28/2021
6.2.0 2,567 10/31/2021
6.1.0 56,505 7/29/2021
6.0.0 4,031 3/8/2021
5.0.1 9,982 1/7/2021
5.0.0 1,763 11/10/2020
4.0.0 2,515 9/15/2020
4.0.0-beta 875 9/7/2020
3.2.1 1,960 8/11/2020
3.2.0 1,179 8/5/2020
3.1.0 1,077 7/30/2020
3.0.1 1,157 7/28/2020
3.0.0 2,154 7/9/2020
2.11.0 7,055 3/29/2020
2.10.0 10,041 2/17/2020
2.9.0 1,908 7/29/2019
2.8.0 1,150 7/3/2019
2.7.1 1,721 11/9/2018
2.7.0 1,354 10/29/2018
2.6.0 1,564 9/6/2018
2.5.1 2,022 2/15/2018
2.5.0 1,513 9/19/2017
2.4.1 1,627 7/18/2017
2.4.0 1,466 7/18/2017
2.3.0 1,638 4/12/2017
2.2.0 1,554 4/7/2017
2.1.0 1,729 12/29/2016
2.0.0 1,624 10/27/2016
1.21.0 1,523 10/20/2016
1.20.0 1,495 10/12/2016
1.19.0 1,576 10/12/2016
1.18.0 1,530 8/29/2016
1.17.0 1,521 8/18/2016
1.16.0 1,885 7/28/2016
1.15.0 1,867 7/28/2016
1.14.0 1,564 7/25/2016
1.13.0 1,584 7/19/2016
1.12.0 1,528 6/20/2016
1.11.0 1,573 6/19/2016
1.10.0 1,516 6/17/2016
1.9.0 1,919 5/30/2016
1.8.9 1,662 5/30/2016
1.8.8 1,635 4/7/2016
1.8.7 1,563 3/24/2016
1.8.6 1,677 10/13/2015
1.8.5 1,656 5/16/2015
1.8.4 1,591 5/16/2015
1.8.3 1,735 10/18/2014
1.8.2 1,750 8/24/2014
1.8.1 1,671 8/22/2014
1.8.0 1,749 2/10/2014
1.7.4 1,659 1/25/2014
1.7.3 1,691 1/24/2014
1.7.2 1,650 1/22/2014
1.7.1 1,649 1/21/2014
1.7.0 1,638 1/20/2014
1.6.1 1,642 1/18/2014
1.6.0 1,669 1/18/2014
1.5.0 1,694 1/17/2014
1.4.0 1,640 1/15/2014
1.3.0 1,725 1/14/2014
1.2.0 1,913 11/24/2013
1.1.0 1,734 11/22/2013
1.0.0 3,326 11/17/2013