ZUGFeRD-CSharp

https://github.com/stephanstapel/zugferd-csharp
Admin
A C# library for creating and processing ZUGFeRD electronic invoices, maintained as an open-source...
Tokens:66,290
Snippets:582
Trust Score:8.9
License:Apache-2.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Save invoice with various ZUGFeRD versions and profiles

Source: https://github.com/stephanstapel/zugferd-csharp/blob/master/docs/profiles-and-formats.md

Shows how to save an invoice descriptor with different ZUGFeRD versions and profiles using the Save method parameters. The examples cover version 1.x with Basic, version 2.0 with Basic, version 2.3 with Basic, and version 2.3 with XRechnung.

```csharp
descriptor.Save("zugferd-v1.xml", ZUGFeRDVersion.Version1, Profile.Basic); // save as version 1.x, profile Basic
descriptor.Save("zugferd-v20.xml", ZUGFeRDVersion.Version20, Profile.Basic); // save as version 2.0, profile Basic
descriptor.Save("zugferd-v23.xml", ZUGFeRDVersion.Version23, Profile.Basic); // save as version 2.3, profile Basic
descriptor.Save("zugferd-v23-xrechnung.xml", ZUGFeRDVersion.Version23, Profile.XRechnung); // save as version 2.3, profile XRechnung
```

--------------------------------

### Embed binary attachments in XRechnung

Source: https://github.com/stephanstapel/zugferd-csharp/blob/master/docs/profiles-and-formats.md

Demonstrates how to read a file as a byte array and add it as an additional referenced document to the invoice descriptor before saving.

```csharp
InvoiceDescriptor desc = _createInvoice();

byte[] data = System.IO.File.ReadAllBytes("my-calculation.xlsx");

desc.AddAdditionalReferencedDocument(
   id: "calculation-sheet",
   typeCode: AdditionalReferencedDocumentTypeCode.ReferenceDocument,
   name: "Calculation as the basis for the invoice",
   attachmentBinaryObject: data,
   filename: "my-calculation.xlsx");

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

--------------------------------

### Save invoice to ZUGFeRD PDF with InvoicePdfProcessor

Source: https://github.com/stephanstapel/zugferd-csharp/blob/master/docs/getting-started.md

Creates an invoice descriptor and saves it as a ZUGFeRD PDF/A. The async version is shown first, with the synchronous alternative commented below.

```csharp
InvoiceDescriptor descriptor = InvoiceDescriptor.CreateInvoice("471102", new DateTime(2018, 03, 05), CurrencyCodes.EUR);
// ... fill the descriptor

await InvoicePdfProcessor.SaveToPdfAsync("zugferd-invoice.pdf", ZUGFeRDVersion.Version23, Profile.Comfort, ZUGFeRDFormats.CII, "input-invoice.pdf", descriptor);

// alternatively, you can invoke the function in synchronous manner:
InvoicePdfProcessor.SaveToPdf("zugferd-invoice.pdf", ZUGFeRDVersion.Version23, Profile.Comfort, ZUGFeRDFormats.CII, "input-invoice.pdf", descriptor);
```

--------------------------------

### Enable XML comments in output

Source: https://github.com/stephanstapel/zugferd-csharp/blob/master/docs/zugferd-details.md

Builds InvoiceFormatOptions with EnableXmlComments(true) to add human-readable comments to the XML file (currently only in German). Pass the options to Save(). Works with all ZUGFeRD versions and XRechnung UBL files.

```csharp
InvoiceFormatOptions options = InvoiceOptionsBuilder
.Create()
.EnableXmlComments(true)
.Build();
desc.Save(ms, version, profile, format, options);
```

--------------------------------

### Create a ZUGFeRD invoice with InvoiceDescriptor

Source: https://github.com/stephanstapel/zugferd-csharp/blob/master/docs/getting-started.md

Creates a ZUGFeRD invoice with the central InvoiceDescriptor class, setting buyer/seller data, tax registrations, references, totals, taxes, charges, and payment terms. Use this as the base for building a complete invoice before saving.

```csharp
InvoiceDescriptor desc = InvoiceDescriptor.CreateInvoice("471102", new DateTime(2013, 6, 5), CurrencyCodes.EUR, "GE2020211-471102");

desc.Name = "WARENRECHNUNG";

desc.ReferenceOrderNo = "AB-312";

desc.AddNote("Rechnung gemäß Bestellung Nr. 2013-471331 vom 01.03.2013.");

desc.AddNote("Es bestehen Rabatt- und Bonusvereinbarungen.", SubjectCodes.AAK);

desc.SetBuyer("Kunden Mitte AG", "69876", "Frankfurt", "Kundenstraße 15", CountryCodes.DE, "88", new GlobalID(GlobalIDSchemeIdentifiers.GLN, "4000001123452"));

desc.AddBuyerTaxRegistration("DE234567890", TaxRegistrationSchemeID.VA);

desc.SetBuyerContact("Hans Muster");

desc.SetSeller("Lieferant GmbH", "80333", "München", "Lieferantenstraße 20", CountryCodes.DE, "88", new GlobalID(GlobalIDSchemeIdentifiers.GLN, "4000001123452"));

desc.AddSellerTaxRegistration("201/113/40209", TaxRegistrationSchemeID.FC);

desc.AddSellerTaxRegistration("DE123456789", TaxRegistrationSchemeID.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(129.37m, 7m, TaxTypes.VAT, TaxCategoryCodes.S);

desc.AddApplicableTradeTax(64.46m, 19m, TaxTypes.VAT, TaxCategoryCodes.S);

desc.AddLogisticsServiceCharge(5.80m, "Versandkosten", TaxTypes.VAT, TaxCategoryCodes.S, 7m);

desc.AddTradePaymentTerms("Zahlbar innerhalb 30 Tagen netto bis 04.04.2018", new DateTime(2018, 4, 4));

desc.AddTradePaymentTerms("3% Skonto innerhalb 10 Tagen bis 15.03.2018", new DateTime(2018, 3, 15), PaymentTermsType.Skonto, 30, 3m);
```

--------------------------------

### Load invoice from PDF with InvoicePdfProcessor

Source: https://github.com/stephanstapel/zugferd-csharp/blob/master/docs/getting-started.md

Loads an invoice descriptor from a PDF file. The async version is shown first, with the synchronous alternative commented below.

```csharp
InvoiceDescriptor desc = await InvoicePdfProcessor.LoadFromPdfAsync("invoice.pdf");

// alternatively, you can invoke the function in synchronous manner:
InvoiceDescriptor desc = InvoicePdfProcessor.LoadFromPdf("invoice.pdf");
```

--------------------------------

### Add document references at invoice level

Source: https://github.com/stephanstapel/zugferd-csharp/blob/master/docs/zugferd-details.md

Adds optional references for a procuring project, a contract, and an order confirmation (seller's order) to the invoice descriptor. Each reference is set as a property on the descriptor.

```csharp
// 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", IssueDateTime = new DateTime(2013,1,1)};



// you can optionally reference an order confirmation (seller's order) at invoice level

desc.SellerOrderReferencedDocument = new SellerOrderReferencedDocument {ID = "SO-2013-471331", IssueDateTime = new DateTime(2013, 3, 1)};
```

--------------------------------

### Load ZUGFeRD invoice from file path

Source: https://github.com/stephanstapel/zugferd-csharp/blob/master/docs/profiles-and-formats.md

Loads a ZUGFeRD invoice from a file path. The library automatically detects the ZUGFeRD version and parses accordingly.

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

--------------------------------

### Set Peppol electronic addresses for XRechnung

Source: https://github.com/stephanstapel/zugferd-csharp/blob/master/docs/getting-started.md

Optionally sets electronic addresses for seller and buyer to support Peppol. Required only when sending the XRechnung via the Peppol network.

```csharp
desc.SetSellerElectronicAddress("DE123456789", ElectronicAddressSchemeIdentifiers.GermanyVatNumber);

desc.SetBuyerElectronicAddress("LU987654321", ElectronicAddressSchemeIdentifiers.LuxemburgVatNumber);
```

--------------------------------

### Set BusinessProcess for XRechnung

Source: https://github.com/stephanstapel/zugferd-csharp/blob/master/docs/profiles-and-formats.md

Configures the business process identifier, which is mandatory for XRechnung 3.0.1 compliance.

```csharp
desc.BusinessProcess = "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0";
```

--------------------------------

### Set line status code and reason

Source: https://github.com/stephanstapel/zugferd-csharp/blob/master/docs/zugferd-details.md

Adds a trade line item and sets its line status to DocumentationClaim with reason INFORMATION. Use this to mark items as informational, subtotal, or fully processed.

```csharp
// Example: Adding a trade line item with a specific status and reason

TradeLineItem tradeLineItem3 = desc.AddTradeLineItem(
    name: "Abschlagsrechnung vom 01.01.2024",
    netUnitPrice: 500,
    unitCode: QuantityCodes.H87,
    billedQuantity: -1m,
    categoryCode: TaxCategoryCodes.S,
    taxPercent: 19.0m,
    taxType: TaxTypes.VAT
);



// Set a line status code and reason code to indicate that this line is for documentation only

tradeLineItem3.SetLineStatus(LineStatusCodes.DocumentationClaim, LineStatusReasonCodes.INFORMATION);
```

--------------------------------

### Save invoice to file with ZUGFeRDVersion.Version23 and Profile.XRechnung

Source: https://github.com/stephanstapel/zugferd-csharp/blob/master/docs/getting-started.md

Saves the invoice to a file stream using ZUGFeRD version 2.3 and the XRechnung profile. Remember to flush and close the stream after saving.

```csharp
FileStream stream = new FileStream(filename, FileMode.Create, FileAccess.Write);
desc.Save(stream, ZUGFeRDVersion.Version23, Profile.XRechnung);
stream.Flush();
stream.Close();    
```

--------------------------------

### Save invoice as XRechnung

Source: https://github.com/stephanstapel/zugferd-csharp/blob/master/docs/profiles-and-formats.md

Saves the invoice descriptor as an XRechnung 3.0.1 file using ZUGFeRD version 2.3.

```csharp
descriptor.Save("xrechnung.xml", ZUGFeRDVersion.Version23, Profile.XRechnung);
```

--------------------------------

### Load ZUGFeRD invoice from stream

Source: https://github.com/stephanstapel/zugferd-csharp/blob/master/docs/profiles-and-formats.md

Loads a ZUGFeRD invoice from an open stream. The library does not close the stream; the caller is responsible for its lifecycle.

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

--------------------------------

### Reference an order confirmation at line item level

Source: https://github.com/stephanstapel/zugferd-csharp/blob/master/docs/zugferd-details.md

Sets a SellerOrderReferencedDocument on a TradeLineItem to reference an order confirmation for that specific line item.

```csharp
// reference an order confirmation at line item level:
TradeLineItem item = desc.AddTradeLineItem(...);
item.SellerOrderReferencedDocument = new SellerOrderReferencedDocument {ID = "SO-2013-471331-001", IssueDateTime = new DateTime(2013, 3, 1)};
```

--------------------------------

### Save ZUGFeRD invoice with explicit version

Source: https://github.com/stephanstapel/zugferd-csharp/blob/master/docs/profiles-and-formats.md

Saves ZUGFeRD invoices with explicit version selection. The default version is 1.x if not specified.

```csharp
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-v20.xml", ZUGFeRDVersion.Version20, Profile.Basic); // save as version 2.0
descriptor.Save("zugferd-v23.xml", ZUGFeRDVersion.Version23, Profile.Basic); // save as version 2.3
```

--------------------------------

### Add product characteristics to a trade line item

Source: https://github.com/stephanstapel/zugferd-csharp/blob/master/docs/zugferd-details.md

Adds an ApplicableProductCharacteristic with Description and Value to a TradeLineItem. Use this to include additional product information in the 'ApplicableProductCharacteristic' section.

```csharp
// you can optionally add product characteristics:

desc.TradeLineItems.Add(new TradeLineItem("0003")
{
    ApplicableProductCharacteristics = new List<ApplicableProductCharacteristic>
    {
        new ApplicableProductCharacteristic()
        { 
            Description = "Description",
            Value = "Value"
        }
    }
});
```

--------------------------------

### Save invoice with E-Reporting profile

Source: https://github.com/stephanstapel/zugferd-csharp/blob/master/docs/profiles-and-formats.md

Saves an invoice descriptor as a Factur-X XML file using version 2.3 and the E-Reporting profile. This profile is used for French e-reporting transactions where the customer does not use VAT, such as B2C scenarios or sales to entities outside France.

```csharp
descriptor.Save("factur-x.xml", ZUGFeRDVersion.Version23, Profile.EReporting);
```

--------------------------------

### Save ZUGFeRD invoice to file path

Source: https://github.com/stephanstapel/zugferd-csharp/blob/master/docs/profiles-and-formats.md

Saves a ZUGFeRD invoice to a file path, specifying version 1 and Basic profile.

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

// fill attributes and structures

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

--------------------------------

### Add trade line items with pre-defined line IDs

Source: https://github.com/stephanstapel/zugferd-csharp/blob/master/docs/getting-started.md

Adds trade line items with pre-defined line IDs, useful when converting existing invoices from ERP systems. The resulting invoice will have two trade line items numbered '0001' and '0002'.

```csharp
InvoiceDescriptor desc = InvoiceDescriptor.CreateInvoice("471102", new DateTime(2013, 6, 5), CurrencyCodes.EUR, "GE2020211-471102");

desc.AddTradeLineItem(lineID: "0001", 23.99m, QuantityCodes.H87, "Item name", "Detail description", ....);

desc.AddTradeLineItem(lineID: "0002", 49.99m, QuantityCodes.H87, "Item name", "Detail description", ....);
```

--------------------------------

### Add trade line item with auto-generated line ID

Source: https://github.com/stephanstapel/zugferd-csharp/blob/master/docs/getting-started.md

Adds a trade line item without specifying a line ID, letting the library generate it automatically. The resulting invoice will have the trade line item numbered as '1'.

```csharp
InvoiceDescriptor desc = InvoiceDescriptor.CreateInvoice("471102", new DateTime(2013, 6, 5), CurrencyCodes.EUR, "GE2020211-471102");

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

--------------------------------

### Save ZUGFeRD invoice to stream

Source: https://github.com/stephanstapel/zugferd-csharp/blob/master/docs/profiles-and-formats.md

Saves a ZUGFeRD invoice to a stream. The library does not close the stream; the caller must flush and close it.

```csharp
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();            
```

--------------------------------

### Automatically clean invalid XML characters

Source: https://github.com/stephanstapel/zugferd-csharp/blob/master/docs/zugferd-details.md

Builds InvoiceFormatOptions with AutomaticallyCleanInvalidCharacters() to automatically clean invalid XML characters. Otherwise, an exception is thrown when an invalid character is written.

```csharp
InvoiceFormatOptions options = InvoiceOptionsBuilder
.Create()
.AutomaticallyCleanInvalidCharacters()
.Build();
desc.Save(ms, version, profile, format, options);
```
Tokens:
Raw