ZUGFeRD-E-Rechnung erstellen mit C# (.NET)

Was Sie brauchen

• Einen API-Key. Legen Sie ihn in der App unter API-Schlüssel an und exportieren Sie ihn als FORMFEED_API_KEY. Zum Ausprobieren ist ein Test-Key (ff_test_…) richtig. Siehe Quickstart.
• C# (.NET). Sie brauchen das .NET 8 SDK; das Programm nutzt System.Net.Http.Json und System.Text.Json, die dazugehören.
• Die Vorlage. e-rechnung aus dem E-Rechnungs-Beispiel: Kopieren Sie es von der Seite des Beispiels in Ihren Workspace, oder pushen Sie den Ordner mit der CLI (formfeed templates push --publish). Jede Rechnungsvorlage funktioniert genauso, sobald ihre Daten einen _invoice-Block haben.
• Die Daten. Die data.json des Beispiels neben dem Programm: ein _invoice-Block mit Verkäufer, Käufer, Positionen, der Aufschlüsselung der Umsatzsteuer und den Summen, benannt wie in der europäischen Norm EN 16931.
• Ein Plan mit E-Rechnungen. Live-E-Rechnungen setzen den Starter-Plan oder höher voraus. Mit einem Test-Schlüssel (ff_test_…) erzeugt jeder Plan Test-E-Rechnungen mit Testmarkierung auf der Seite, der Free-Plan bis zu 20 pro Tag.

dotnet new console -o render && cd render   # danach Program.cs ersetzen

Das Programm

Das Programm liest data.json, sendet sie mit dem Namen der Vorlage und post.einvoice, wartet auf das Ergebnis, wenn die API mit 202 antwortet, bricht mit der Meldung der API ab, wenn etwas nicht stimmt, und speichert die E-Rechnung.

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

var data = JsonDocument.Parse(File.ReadAllText("data.json")).RootElement;
var body = new
{
    template = "e-rechnung",
    data,
    post = new {
        einvoice = new { profile = "en16931" },
    },
};

using var http = new HttpClient();

// one call to the API: the key goes on each request, never on the client, so no other address sees it
async Task<HttpResponseMessage> Send(HttpMethod method, string url, object? content = null)
{
    using var request = new HttpRequestMessage(method, url) { Content = content is null ? null : JsonContent.Create(content) };
    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("FORMFEED_API_KEY"));
    return await http.SendAsync(request);
}

var response = await Send(HttpMethod.Post, "https://api-eu.formfeed.dev/v1/renders", body);
var render = await response.Content.ReadFromJsonAsync<JsonElement>();

// not done within 60 seconds: the answer is 202 and the render goes on in the background;
// its result answers the same way until the render has finished
while ((int)response.StatusCode == 202)
{
    await Task.Delay(2000);
    response = await Send(HttpMethod.Get, $"https://api-eu.formfeed.dev/v1/renders/{render.GetProperty("id")}/result");
    render = await response.Content.ReadFromJsonAsync<JsonElement>();
}

// every error is a problem document (RFC 9457) with a title and a detail
if (!response.IsSuccessStatusCode)
{
    Console.Error.WriteLine($"{render.GetProperty("title")}: {(render.TryGetProperty("detail", out var detail) ? detail : "")}");
    return 1;
}

await File.WriteAllBytesAsync("e-invoice.pdf", await http.GetByteArrayAsync(render.GetProperty("download_url").GetString()));
Console.WriteLine($"{render.GetProperty("id")} {render.GetProperty("page_count")} page(s), {render.GetProperty("units")} unit(s)");
return 0;

Ausführen

Es gibt die ID des Renderings, die Seitenzahl und die verbrauchten Einheiten aus (mit einem Live-Schlüssel eine mehr als dasselbe PDF ohne XML), und e-invoice.pdf liegt neben dem Programm. Ein PDF-Viewer zeigt die Rechnung, seine Anhänge zeigen die factur-x.xml darin. Mit einem Test-Schlüssel wird das Rendering nicht gezählt, und jede Test-E-Rechnung trägt eine Testmarkierung, in jedem Plan.

export FORMFEED_API_KEY=ff_test_...
dotnet run

Was an C# (.NET) besonders ist

• Anonyme Objekte. Die Feldnamen der API sind snake_case und werden so geschrieben, wie sie sind (webhook_url = …); eine Naming Policy ist also nicht nötig.
• Daten ohne Klassen. JsonDocument.Parse(…).RootElement bettet die Beispieldaten unverändert ein; in Ihrer Anwendung ist das Ihr eigener Record oder DTO.
• Schlüssel an der Anfrage, nicht am Client. Der Authorization-Header sitzt an jeder Anfrage an die API, nie am HttpClient: Der Download geht an eine signierte CDN-URL und darf Ihren API-Key nicht mitschicken.

Was das PDF zur E-Rechnung macht

• post.einvoice. macht aus dem PDF ein PDF/A-3, das die Rechnung als factur-x.xml trägt. Die Beispielvorlage erklärt dasselbe in ihrer settings.json, für sie ist die Zeile also optional; für Ihre eigene Rechnungsvorlage ist sie der eine Schalter.
• Der _invoice-Block. Verkäufer, Käufer, Positionen, Aufschlüsselung der Umsatzsteuer und Summen, benannt wie in der Norm; Einheiten und Steuerkategorien sind Codes (HUR, S). Die Vorlage druckt die Seite aus demselben Block, Seite und XML können also nichts Verschiedenes sagen.
• Die Prüfung. Bevor die Datei ausgeliefert wird, wird das XML gegen die Regeln der EN 16931 und das PDF gegen PDF/A-3b geprüft. Der Bericht steht in einvoice.validation des Renderings, und ein Wert, den die Seite nicht zeigt, steht in einvoice.display.missing.
• ZUGFeRD oder Factur-X. Eine Spezifikation unter zwei Namen, und dieselbe Datei. flavour entscheidet nur, welchen Namen und welches Release das Rendering meldet: ZUGFeRD 2.5 oder Factur-X 1.09.

Wenn die Daten nicht stimmen

Ein Block, der eine Regel verletzt, lässt die Anfrage mit 422 einvoice_data_invalid scheitern, bevor etwas gerendert oder gezählt wird. Das Problem nennt jeden Befund mit seiner Stelle in den Daten und der verletzten Regel (BR-CO-15, …), und das Programm gibt Titel und Detail aus. Eine Datei, die die Prüfung nicht besteht, wird nie ausgeliefert und nie durch ein einfaches PDF ersetzt.

Was bei Ihnen bleibt

Formfeed erzeugt und prüft die Datei. Den Versand an Ihren Kunden, die Archivierung und die umsatzsteuerliche Behandlung der Rechnung übernehmen Sie. Wann eine E-Rechnung Pflicht ist, mit den amtlichen Quellen, steht auf der Seite zur E-Rechnung; Felder und Regeln stehen in der Dokumentation zur E-Rechnung.

Wenn die API nein sagt

• Eine Form für jeden Fehler. Fehler sind Problem-Dokumente (RFC 9457) mit type, title, status, detail, einem stabilen code und der request_id, die Sie dem Support nennen; die type-URL führt zu einer Seite über diesen Fehler. Die Liste steht in der Fehlerreferenz.
• Die üblichen. 401 unauthorized bei fehlendem oder widerrufenem Schlüssel, 404 template_not_found bei falschem Vorlagennamen, 422 template_runtime_error, wenn die Vorlage an den Daten scheitert, 429 rate_limited über den Anfragen pro Sekunde des Tarifs, 402 quota_exceeded, wenn die Einheiten des Free-Tarifs verbraucht sind (ein bezahlter Tarif rechnet weitere Einheiten ab, bis zu seiner Obergrenze).
• Sicher wiederholen. Senden Sie beim POST einen Idempotency-Key-Header und wiederholen Sie die Anfrage mit demselben Schlüssel, wenn Sie nicht wissen, ob der erste Versuch ankam: 24 Stunden lang liefert der Schlüssel die erste Antwort, statt erneut zu rendern und zu berechnen. Gespeichert wird die Antwort, sobald der erste Versuch beantwortet ist; wiederholen Sie also nicht, solange er noch laufen kann. Auch Probleme unter 500 werden gespeichert, eine korrigierte Anfrage braucht deshalb einen neuen Schlüssel.

Die Aufgabe um dieses Programm

Dieser Guide ist ein Programm. Was die Aufgabe darum herum braucht, von der Vorlage bis zu Limits und Preis, steht auf der Seite Rechnungs-PDF-API.

Weitere Guides für C# (.NET)

• PDF-Rechnung aus JSON erzeugen mit C# (.NET)
• HTML in PDF umwandeln mit C# (.NET)
• Open-Graph-Bilder erzeugen mit C# (.NET)
• PDFs aus einer CSV erzeugen mit C# (.NET)
• PDFs zusammenfügen und mit Passwort schützen mit C# (.NET)
• PDF asynchron rendern und den Webhook prüfen mit C# (.NET)

FAQ

Welches Profil soll ich wählen?

en16931, die Voreinstellung, trägt jedes Feld der europäischen Norm; basic ist das kleinste Profil, das für sich allein eine Rechnung ist. Jedes andere Profil wird mit einvoice_profile_unsupported beantwortet.

Erzeugt Formfeed XRechnung?

Nein. Formfeed schreibt ZUGFeRD bzw. Factur-X: das XML in einem PDF/A-3. XRechnung und UBL gibt es nicht.

Was kostet eine E-Rechnung?

Eine Einheit zusätzlich zu ihrem Rendering, eine einseitige E-Rechnung kostet also zwei Einheiten. Live-E-Rechnungen setzen den Starter-Plan oder höher voraus; im Free-Plan erzeugen Test-Renderings bis zu 20 pro Tag. Siehe Preise.

Bekomme ich das XML als eigene Datei?

xml: "both" in post.einvoice speichert das XML zusätzlich neben dem PDF, und das Rendering verlinkt es als einvoice.xml_url. Im PDF steckt es so oder so.

ZUGFeRD-E-Rechnung in anderen Sprachen

• Node.js (TypeScript)
• Python
• PHP
• Go
• Java
• Ruby
• curl