<!-- md-source: 3886cddc60d4 FactoorSharpWeb/Views/Home/GettingStarted.cshtml -->

# Los geht's mit FactoorSharp

> Markdown-Fassung von <https://www.factoorsharp.de/de/Home/GettingStarted> für KI-Agenten.
> Sprachen: [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)

Mit FactoorSharp erstellst, liest und validierst du elektronische Rechnungen
(ZUGFeRD, XRechnung, EN 16931) in wenigen Minuten. Diese Anleitung führt Schritt für
Schritt zur ersten funktionierenden Rechnung.

Nach diesem Schnellstart kannst du:

- eine Rechnung in C# erzeugen
- sie als EN 16931 / ZUGFeRD XML exportieren
- sie optional in ein PDF/A-3 einbetten
- das Ergebnis validieren

## Installation

Installation über NuGet:

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

Oder über den Package Manager:

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

Die Komponente unterstützt .NET 6+, .NET Framework 4.6 und .NET Framework 4.8
(je nach Zielplattform).

## Lizenz abrufen

Um FactoorSharp zu nutzen, brauchst du einen Lizenzschlüssel.
[Registriere dich kostenlos](https://www.factoorsharp.de/de/Account/SignUp) – direkt
danach erhältst du automatisch eine 30-tägige Testlizenz mit vollem Funktionsumfang,
ganz ohne Angabe von Zahlungsdaten.

Deinen Lizenzschlüssel findest du anschließend im Kunden-Bereich unter „Meine Lizenz"
(<https://www.factoorsharp.de/support/License/Index>). Trage ihn wie im folgenden
Beispiel einmalig beim Start deiner Anwendung ein – weitere Möglichkeiten
(Umgebungsvariable, `appsettings.json`) findest du dort ebenfalls.

## Erste Rechnung erzeugen

Im folgenden Beispiel entsteht eine minimale EN-16931-konforme Rechnung.

### Kopfdaten

Zunächst die Kopfdaten mit der Kennung von Verkäufer und Käufer. Dazu gehört auch die
Angabe zur Lieferung.

```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;
// alternativ: Rechnungszeitraum (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
' alternativ: Rechnungszeitraum (BG-14)
' invoice.SetBillingPeriod(
'     billingPeriodStart:=DateTime.Today.AddDays(-7),
'     billingPeriodEnd:=DateTime.Today)
```

### Position

```csharp
invoice.AddTradeLineItem(name: "Trekkingrad",
                         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:="Trekkingrad",
                         netUnitPrice:=799.0D,
                         unitCode:=QuantityCodes.C62,
                         grossUnitPrice:=799.0D,
                         billedQuantity:=1,
                         taxType:=TaxTypes.VAT,
                         categoryCode:=TaxCategoryCodes.S,
                         taxPercent:=19,
                         sellerAssignedID:="BIKE-1")
```

### Summenblock und Zahlungsbedingungen

```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 als XML (EN 16931 / XRechnung / ZUGFeRD)

Sobald die Rechnung aufgebaut ist, lässt sie sich als XML exportieren:

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

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

Typische Profile für ZUGFeRD:

| Profil | Bedeutung |
|---|---|
| Comfort / EN16931 | Standard für die EU |
| Extended | Ausführlichstes und gebräuchlichstes Profil in Deutschland |

## Rechnung validieren

Damit sichergestellt ist, dass alle notwendigen Angaben enthalten sind, kann die
Rechnung mit der Validierungsoberfläche im Kunden-Bereich von factoorsharp.de
validiert werden. Das ermöglicht den Empfängern der Rechnung eine reibungslose
Verarbeitung.

## PDF/A-3 mit eingebetteter Rechnung erzeugen (ZUGFeRD)

Liegt eine PDF-Datei vor, z. B. aus einem Report-Generator oder dem ERP-System, lassen
sich die ZUGFeRD-Informationen direkt in das PDF einbetten:

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

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

Ergebnis: ein visuell lesbares PDF im Format PDF/A-3 inklusive der maschinenlesbaren
XML-Datei, die in das PDF-Dokument eingebettet ist.

## Bestehende Rechnungen einlesen

FactoorSharp kann auch bestehende Rechnungen analysieren – sowohl aus einer XML-Datei
als auch aus einer PDF-Datei:

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

// XML aus einem PDF auslesen
var fromPdf = await FacturXInvoicePdfProcessor.LoadFromPdfAsync("FacturX-Rechnung.pdf");
```

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

' XML aus einem PDF auslesen
Dim fromPdf = Await FacturXInvoicePdfProcessor.LoadFromPdfAsync("FacturX-Rechnung.pdf")
```

## Migration von ZUGFeRD-csharp

FactoorSharp ist der Nachfolger von ZUGFeRD-csharp. Wenn du bereits damit arbeitest:

- Die API ist bewusst ähnlich gehalten.
- Bestehende Logik lässt sich meist direkt übernehmen.
- Tausche `InvoiceDescriptor` durch `FacturXInvoice` und `InvoicePdfProcessor` durch
  `FacturXInvoicePdfProcessor`. Fertig.
- Neue Features: bessere Validierung, neue Funktionen.

## Weiterführende Seiten

- [Produktübersicht](https://www.factoorsharp.de/de/Home/Index.md) – Funktionen,
  Preise, FAQ
- [ZUGFeRD .NET und ZUGFeRD C#](https://www.factoorsharp.de/de/Home/ZugferdDotNet.md)
- [ZUGFeRD-Dokumentation](https://www.factoorsharp.de/de/Service/Documentation) –
  Referenz der XML-Elemente, BT-/BG-Nummern und C#-Klassen
- [Versionen und Release Notes](https://www.factoorsharp.de/de/Home/Versions)