EInvoice.Sdk 0.1.0

EInvoice.Sdk

.NET client for the EInvoice API — extract structured data from ZUGFeRD / Factur-X PDFs and generate XRechnung XML or ZUGFeRD PDFs for the German (2025–2028) and French e-invoicing mandates.

• Targets .NET 10, .NET 8 and .NET Framework 4.7.2+ / netstandard2.0
• Invoices are processed statelessly on servers hosted in Germany and are never stored
• Errors surface as typed exceptions with field-level validation details

Install

dotnet add package EInvoice.Sdk

Quick start

using EInvoice.Sdk;

using var client = new EInvoiceClient("your-api-key");

// 1. Extract data from an existing ZUGFeRD / Factur-X PDF
await using var pdf = File.OpenRead("incoming-invoice.pdf");
InvoiceModel invoice = await client.ExtractAsync(pdf);
Console.WriteLine($"{invoice.InvoiceNumber}: {invoice.Tax.GrossTotal} {invoice.CurrencyCode}");

// 2. Generate XRechnung XML (BuyerReference is required — BR-DE-15)
var model = new InvoiceModel(
    InvoiceNumber: "2026-001",
    IssueDate: new DateOnly(2026, 6, 12),   // DateTime on .NET Framework
    CurrencyCode: "EUR",
    BusinessProcess: null,
    BuyerReference: "04011000-12345-67",    // Leitweg-ID (B2G) or agreed reference (B2B)
    Seller: new TradeParty("Seller GmbH", new Address("Musterstraße 1", "12345", "Berlin", "DE"), VatId: "DE123456789"),
    Buyer: new TradeParty("Buyer AG", new Address("Beispielweg 2", "54321", "Hamburg", "DE"), VatId: "DE987654321"),
    Lines: [new TradeLineItem("Consulting", Quantity: 8, QuantityUnit: "HUR", NetUnitPrice: 120m, TaxPercent: 19)],
    Tax: new TaxSummary(NetTotal: 960m, TaxTotal: 182.40m, GrossTotal: 1142.40m));

byte[] xml = await client.GenerateXRechnungAsync(model);
await File.WriteAllBytesAsync("xrechnung.xml", xml);

// 3. Embed the invoice into a PDF as ZUGFeRD (COMFORT / EN 16931 by default)
await using var source = File.OpenRead("invoice-visual.pdf");
byte[] zugferdPdf = await client.GenerateZugferdAsync(model, source);
await File.WriteAllBytesAsync("invoice-zugferd.pdf", zugferdPdf);

ASP.NET Core

Register the client once and inject IEInvoiceClient anywhere:

// Program.cs
builder.Services.AddEInvoiceClient(o => o.ApiKey = builder.Configuration["EInvoice:ApiKey"]);

// Endpoint or service
app.MapPost("/invoices/{id}/xrechnung", async (string id, IEInvoiceClient einvoice, MyInvoiceStore store) =>
{
    InvoiceModel model = store.ToInvoiceModel(id);
    byte[] xml = await einvoice.GenerateXRechnungAsync(model);
    return Results.File(xml, "application/xml", $"{id}.xml");
});

AddEInvoiceClient returns an IHttpClientBuilder, so the standard resilience extensions apply:

builder.Services
    .AddEInvoiceClient(o => o.ApiKey = builder.Configuration["EInvoice:ApiKey"])
    .AddStandardResilienceHandler(); // Microsoft.Extensions.Http.Resilience

Error handling

try
{
    byte[] xml = await client.GenerateXRechnungAsync(model);
}
catch (EInvoiceValidationException ex)        // 422 — invalid invoice model
{
    foreach (var error in ex.Errors)
        Console.WriteLine($"{error.Field}: {error.Message}");
}
catch (EInvoiceRateLimitException)            // 429 — monthly plan limit reached
{
    // back off / upgrade plan
}
catch (EInvoiceApiException ex)               // any other API error (401, 400, …)
{
    Console.WriteLine($"{ex.StatusCode}: {ex.Message}");
}

Notes

• BuyerReference (BT-10) is mandatory for XRechnung (rule BR-DE-15): use the Leitweg-ID for invoices to German public authorities, or any reference agreed with the buyer for B2B. It is optional for ZUGFeRD.
• Maximum upload size is 10 MB per request.
• On .NET Framework / netstandard2.0, date properties are DateTime instead of DateOnly; the wire format (yyyy-MM-dd) is identical.

Links

• API documentation: einvoice-api.de
• Source: github.com/K-S-K/EInvoiceAPI