<!-- md-source: 69c93f861c26 FactoorSharpWeb/wwwroot/de/Home/GettingStarted.md -->

# Getting started with FactoorSharp

> Markdown version of <https://www.factoorsharp.de/en/Home/GettingStarted> for AI agents.
> Languages: [Deutsch](https://www.factoorsharp.de/de/Home/GettingStarted.md) ·
> [English](https://www.factoorsharp.de/en/Home/GettingStarted.md) ·
> [Français](https://www.factoorsharp.de/fr/Home/GettingStarted.md)

With FactoorSharp you can create, read and validate electronic invoices (ZUGFeRD,
XRechnung, EN 16931) in just a few minutes. This guide walks you step by step to your
first working invoice.

By the end of this quick start you'll be able to:

- create an invoice in C#
- export it as EN 16931 / ZUGFeRD XML
- optionally embed it in a PDF/A-3
- validate the result

## Installation

Install FactoorSharp via NuGet:

```powershell
dotnet add package FactoorSharp.FacturX
```

Or via the Package Manager:

```powershell
Install-Package FactoorSharp.FacturX
```

The library supports .NET 6+, .NET Framework 4.6 and .NET Framework 4.8 (depending on
your target platform).

## Get a license

To use FactoorSharp you need a license key.
[Sign up for free](https://www.factoorsharp.de/en/Account/SignUp) – right after that
you automatically get a 30-day trial license with the full feature set, no payment
details required.

You'll then find your license key in the customer area under "My license"
(<https://www.factoorsharp.de/support/License/Index>). Add it once at the start of your
application as shown in the example below – other options (environment variable,
`appsettings.json`) are available there too.

## Create your first invoice

The following example creates a minimal EN-16931-compliant invoice.

### Header data

First the header data with the seller and buyer identification. This also includes the
delivery details.

```csharp
FacturXInvoice.SetLicense("...");

var invoice = FacturXInvoice.CreateInvoice("Invoice-01",
    new DateTime(2025,09,03),
    CurrencyCodes.EUR)
        // BG-14
        .SetSeller(name: "BikeTech GmbH",
               postcode: "10115",
               city: "Berlin",
               street: "Radweg 12",
               country: CountryCodes.DE,
               id: String.Empty,
               globalID: new GlobalID(GlobalIDSchemeIdentifiers.GLN, "4000001123452"),
               legalOrganization: new LegalOrganization(GlobalIDSchemeIdentifiers.GLN, "4000001123452", "BikeTech GmbH"))
        // BG-7
        .SetBuyer(name: "CityRider AG",
              postcode: "20457",
              city: "Hamburg",
              street: "Hafenstraße 45",
              country: CountryCodes.DE,
              id: "DE987654321");

// BT-31
invoice.AddSellerTaxRegistration("201/113/40209", TaxRegistrationSchemeID.FC);

// BT-72 - ActualDeliverySupplyChainEvent
invoice.ActualDeliveryDate = DateTime.Today;
// alternatively: invoicing period (BG-14)
// invoice.SetBillingPeriod(
//     billingPeriodStart: DateTime.Today.AddDays(-7),
//     billingPeriodEnd: DateTime.Today);
```

```vbnet
FacturXInvoice.SetLicense("...")

Dim invoice = FacturXInvoice.CreateInvoice("Invoice-01",
    New DateTime(2025, 9, 3),
    CurrencyCodes.EUR) _
        .SetSeller(name:="BikeTech GmbH",
               postcode:="10115",
               city:="Berlin",
               street:="Radweg 12",
               country:=CountryCodes.DE,
               id:=String.Empty,
               globalID:=New GlobalID(GlobalIDSchemeIdentifiers.GLN, "4000001123452"),
               legalOrganization:=New LegalOrganization(GlobalIDSchemeIdentifiers.GLN, "4000001123452", "BikeTech GmbH")) _
        .SetBuyer(name:="CityRider AG",
              postcode:="20457",
              city:="Hamburg",
              street:="Hafenstraße 45",
              country:=CountryCodes.DE,
              id:="DE987654321")

' BT-31
invoice.AddSellerTaxRegistration("201/113/40209", TaxRegistrationSchemeID.FC)

' BT-72 - ActualDeliverySupplyChainEvent
invoice.ActualDeliveryDate = DateTime.Today
' alternatively: invoicing period (BG-14)
' invoice.SetBillingPeriod(
'     billingPeriodStart:=DateTime.Today.AddDays(-7),
'     billingPeriodEnd:=DateTime.Today)
```

### Line item

```csharp
invoice.AddTradeLineItem(name: "Trekking bike",
                         netUnitPrice: 799.0m,
                         unitCode: QuantityCodes.C62,
                         grossUnitPrice: 799.0m,
                         billedQuantity: 1,
                         taxType: TaxTypes.VAT,
                         categoryCode: TaxCategoryCodes.S,
                         taxPercent: 19,
                         sellerAssignedID: "BIKE-1");
```

```vbnet
invoice.AddTradeLineItem(name:="Trekking bike",
                         netUnitPrice:=799.0D,
                         unitCode:=QuantityCodes.C62,
                         grossUnitPrice:=799.0D,
                         billedQuantity:=1,
                         taxType:=TaxTypes.VAT,
                         categoryCode:=TaxCategoryCodes.S,
                         taxPercent:=19,
                         sellerAssignedID:="BIKE-1")
```

### Totals block and payment terms

```csharp
decimal taxTotalAmount = 799.0m / 100m * 19m;

invoice.AddApplicableTradeTax(basisAmount: 799.0m,
                              percent: 19m,
                              taxAmount: taxTotalAmount,
                              typeCode: TaxTypes.VAT,
                              categoryCode: TaxCategoryCodes.S);

invoice.PaymentTerms.Add(new PaymentTerms() // BT-20
{
    DueDate = DateTime.Today.AddDays(14)
});

invoice.SetTotals(lineTotalAmount: 799.0m,
                  taxBasisAmount: 799.0m,
                  taxTotalAmount: taxTotalAmount,
                  grandTotalAmount: 799.0m + taxTotalAmount,
                  duePayableAmount: 799.0m + taxTotalAmount);

invoice.Save("e:\\factur-x.xml",
             version: ZUGFeRDVersion.Version25,
             profile: Profile.Extended);
```

```vbnet
Dim taxTotalAmount As Decimal = 799.0D / 100D * 19D

invoice.AddApplicableTradeTax(basisAmount:=799.0D,
                              percent:=19D,
                              taxAmount:=taxTotalAmount,
                              typeCode:=TaxTypes.VAT,
                              categoryCode:=TaxCategoryCodes.S)

invoice.PaymentTerms.Add(New PaymentTerms() With ' BT-20
{
    .DueDate = DateTime.Today.AddDays(14)
})

invoice.SetTotals(lineTotalAmount:=799.0D,
                  taxBasisAmount:=799.0D,
                  taxTotalAmount:=taxTotalAmount,
                  grandTotalAmount:=799.0D + taxTotalAmount,
                  duePayableAmount:=799.0D + taxTotalAmount)

invoice.Save("e:\factur-x.xml",
             version:=ZUGFeRDVersion.Version25,
             profile:=Profile.Extended)
```

## Export as XML (EN 16931 / XRechnung / ZUGFeRD)

Once your invoice is built, you can export it as XML:

```csharp
invoice.Save("factur-x.xml",
    version: ZUGFeRDVersion.Version25,
    profile: Profile.Extended);
```

```vbnet
invoice.Save("factur-x.xml",
    version:=ZUGFeRDVersion.Version25,
    profile:=Profile.Extended)
```

Typical profiles used for ZUGFeRD:

| Profile | Meaning |
|---|---|
| Comfort / EN16931 | Standard for the EU |
| Extended | The most detailed and widely used profile in Germany |

## Validate an invoice

To make sure all required fields are present, you can validate your invoice using the
validation tool in the customer area at factoorsharp.de. This helps your invoice
recipients process it smoothly.

## Create a PDF/A-3 with embedded invoice data (ZUGFeRD)

If you already have a PDF file, for example from a report generator or your ERP
system, you can embed the ZUGFeRD information directly into it:

```csharp
await FacturXInvoicePdfProcessor.SaveToPdfAsync(
    "FacturX-Invoice.pdf",
    ZUGFeRDVersion.Version25,
    Profile.Extended,
    ZUGFeRDFormats.CII,
    "Classic-PDF-Invoice.pdf",
    invoice);
```

```vbnet
Await FacturXInvoicePdfProcessor.SaveToPdfAsync(
    "FacturX-Invoice.pdf",
    ZUGFeRDVersion.Version25,
    Profile.Extended,
    ZUGFeRDFormats.CII,
    "Classic-PDF-Invoice.pdf",
    invoice)
```

Result: a visually readable PDF/A-3 file that also contains the machine-readable XML
data embedded in the PDF document.

## Read existing invoices

FactoorSharp can also analyze existing invoices – it doesn't matter whether you're
reading an XML file or extracting the XML from a PDF:

```csharp
// read XML
var fromXml = FacturXInvoice.Load("factur-x.xml");

// extract the XML from a PDF
var fromPdf = await FacturXInvoicePdfProcessor.LoadFromPdfAsync("FacturX-Invoice.pdf");
```

```vbnet
' read XML
Dim fromXml = FacturXInvoice.Load("factur-x.xml")

' extract the XML from a PDF
Dim fromPdf = Await FacturXInvoicePdfProcessor.LoadFromPdfAsync("FacturX-Invoice.pdf")
```

## Migrating from ZUGFeRD-csharp

FactoorSharp is the successor to ZUGFeRD-csharp. If you already work with it:

- The API is deliberately kept similar.
- Existing logic can usually be carried over as is.
- Replace `InvoiceDescriptor` with `FacturXInvoice` and `InvoicePdfProcessor` with
  `FacturXInvoicePdfProcessor`. That's it.
- New features: better validation, additional functionality.

## Related pages

- [Product overview](https://www.factoorsharp.de/en/Home/Index.md) – features, pricing, FAQ
- [ZUGFeRD .NET and ZUGFeRD C#](https://www.factoorsharp.de/en/Home/ZugferdDotNet.md)
- [ZUGFeRD documentation](https://www.factoorsharp.de/en/Service/Documentation) –
  reference of the XML elements, BT/BG numbers and C# classes
- [Versions and release notes](https://www.factoorsharp.de/en/Home/Versions)