PDF-Rechnung aus JSON erzeugen 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. invoice-de aus dem Rechnungsbeispiel: Kopieren Sie es von der Seite des Beispiels in Ihren Workspace; die Kopie behält den Namen invoice-de und ist veröffentlicht. Oder pushen Sie den Ordner mit der CLI (formfeed templates push --publish). Ein Rendering nutzt die veröffentlichte Version.
• Die Daten. Die data.json des Beispiels neben dem Programm. Sie enthält Firma, Kunde und zwei Positionen, aber keine Summen.

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 einem Dateinamen aus der Rechnungsnummer, wartet auf das Ergebnis, wenn die API mit 202 antwortet, bricht mit der Meldung der API ab, wenn etwas nicht stimmt, und speichert das PDF.

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 = "invoice-de",
    data,
    filename = $"invoice-{data.GetProperty("invoice").GetProperty("number").GetString()}.pdf",
};

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("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, und invoice.pdf liegt neben dem Programm. Mit einem Schlüssel, der mit ff_test_ beginnt, wird das Rendering nicht gezählt; im Free-Tarif trägt es ein kleines Wasserzeichen.

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 die Vorlage mit dem JSON macht

Die Anfrage enthält keine abgeleiteten Zahlen, und genau das ist der Sinn des Renderns aus einer Vorlage:

• Summen. invoice.lines | sum('total') addiert die Positionen, Umsatzsteuer und Brutto ergeben sich aus invoice.vat_rate.
• Formate. Mit der Locale de-DE der Vorlage gibt money 3.760,40 € aus und date('dd.MM.yyyy') 10.09.2026; dateAdd(14, 'days') setzt die Fälligkeit.
• GiroCode. epcQr zeichnet den SEPA-Zahlungscode aus Name, IBAN, BIC, Betrag und Verwendungszweck.
• Dateiname. ist nicht Sache der Vorlage. Die API übernimmt filename, wie er ist, und füllt keine Vorlagen-Ausdrücke, deshalb baut das Programm invoice-2026-0042.pdf aus der Rechnungsnummer, und der Download trägt diesen Namen. Zeichen außer A–Z, a–z, 0–9, ., -, _, (, ) und dem Leerzeichen werden zu _, Umlaute also auch.

Von einer Rechnung zu vielen

Ein Rechnungslauf ist ein Batch: eine Anfrage mit bis zu 1.000 Dokumenten, am Ende ein Zip und ein Webhook, wenn alles fertig ist. Siehe Batches. Dokumente, die länger als ein paar Sekunden brauchen, rendern Sie asynchron und lassen sich per Webhook benachrichtigen.

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)

• ZUGFeRD-E-Rechnung erstellen 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

Kann ich das Rechnungs-HTML senden, statt eine gespeicherte Vorlage zu nutzen?

Ja, setzen Sie es in html und lassen Sie template weg; der HTML-zu-PDF-Guide dieser Sprache zeigt es. Eine gespeicherte Vorlage bringt Versionen, eine Vorschau mit Ihren Beispieldaten und Release Channels.

Wie lange gilt die Download-URL?

Ein signierter Link gilt höchstens sieben Tage und nie länger, als die Datei aufbewahrt wird; darüber entscheidet die Aufbewahrung Ihres Tarifs (eine Einstellung des Workspace oder expires_in kann sie nur verkürzen). GET /renders/{id} stellt jederzeit einen frischen Link aus, speichern Sie also die ID des Renderings, nicht die URL. Mit access: "public" gilt der Link so lange wie die Datei. Details in der Rendering-Doku.

Was kostet ein Rendering?

Eine Einheit je angefangene fünf Seiten eines PDFs, also eine für eine bis fünf Seiten und zwei für sechs bis zehn. Test-Renderings sind kostenlos. Siehe Preise.

PDF-Rechnung aus JSON in anderen Sprachen

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