Formfeed-Dokumentation

Formfeed macht aus einer HTML-Vorlage und JSON-Daten ein PDF oder ein Bild. Sie schreiben die Vorlage einmal, in HTML und CSS mit Jinja2, Liquid oder Handlebars. Ihr Code sendet nur noch die Daten und erhält eine signierte Download-URL zurück.

curl https://api-eu.formfeed.dev/v1/renders \
  -H "Authorization: Bearer $FORMFEED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "html": "<h1>Hallo {{ name }}</h1>", "engine": "liquid", "data": { "name": "Erika" } }'

{
  "id": "rnd_7f3c9a1e2b4d4c8f9e0a1b2c3d4e5f60",
  "status": "succeeded",
  "download_url": "https://cdn.formfeed.dev/o/eu/…?exp=…&sig=…",
  "page_count": 1,
  "units": 1
}

Die Antwort ist hier gekürzt; der Schnellstart zeigt eine vollständige. units ist, was das Rendering kostet: 1 mit einem Live-Schlüssel (ff_live_…), 0 mit einem Test-Schlüssel (ff_test_…).

Das ist die ganze Integration. Alles Weitere in dieser Dokumentation dreht sich darum, die Vorlage gut und die Integration robust zu machen.

Hier beginnen

Ich möchte …	Lesen
Mein erstes PDF in fünf Minuten rendern	Schnellstart
Vorlagen in Git halten, lokal ansehen, in der CI testen	Vorlagen als Code
Workspaces, Versionen, Schlüssel und Einheiten verstehen	Grundbegriffe
Eine gute Vorlage schreiben: Seiten, Kopfzeilen, Schriften, Bilder	Vorlagen schreiben
Die API aus meinem Backend aufrufen	API-Überblick · Rendern · TypeScript-SDK · Python-SDK
Tausende Dokumente rendern	Asynchron und Batch · Webhooks
Einen Endpunkt oder ein Feld nachschlagen	API-Referenz
Einen Fehler verstehen, den ich erhalten habe	Fehler
Einen KI-Agenten Dokumente rendern lassen	MCP-Server
Von apitemplate.io, PDFMonkey oder jsreport umziehen	Migration

So funktioniert es

1. Vorlage schreiben. HTML und CSS mit einer Vorlagensprache für die variablen Teile, im Web-Editor oder als Dateien in Ihrem Repository. Papierformat, Ränder, Kopf- und Fußzeilen stehen in den Einstellungen der Vorlage.
2. Veröffentlichen. Die API rendert standardmäßig die veröffentlichte Version. Das Bearbeiten eines Entwurfs ändert also nie, was Ihr Produktionscode erhält.
3. Daten senden. POST /v1/renders mit dem Slug der Vorlage und einem JSON-Objekt. Ein Rendering antwortet standardmäßig synchron, mit der fertigen Datei. Mit "mode": "async" erhalten Sie sofort 202 und einen Webhook, sobald es fertig ist; ein synchrones Rendering, das länger als 60 Sekunden dauert, wird von selbst asynchron. Batches mit bis zu 1.000 Dokumenten laufen immer asynchron.
4. Ergebnis herunterladen. Die Antwort enthält eine signierte download_url, die Seitenzahl, die berechneten Einheiten und die Versionen von Vorlage und Engine, die das Ergebnis erzeugt haben.

Was die Arbeit angenehm macht

• Eine Engine überall. Die Vorschau im Editor, die lokale Vorschau der CLI und der Render-Worker in der Produktion nutzen alle dasselbe Paket der Template-Engine. Ihre lokale Vorschau und Ihre CI-Prüfungen stimmen deshalb mit der Produktion überein.
• Drei Vorlagensprachen, ein Satz Helfer. Jinja2, Liquid und Handlebars teilen sich über 50 Helfer für Geldbeträge, Datumsangaben, QR-Codes, Barcodes, SEPA-Zahlungscodes, Diagramme und mehr.
• Fehler, die auf die Zeile zeigen. Ein Vorlagenfehler kommt als RFC-9457-Problem mit Zeile und Spalte zurück. Jeder type eines Fehlers verlinkt auf eine Seite, die die Lösung erklärt.
• Sichere Wiederholungen. Ist eine Anfrage mit einem Idempotency-Key beantwortet, erhält eine Wiederholung mit demselben Schlüssel innerhalb von 24 Stunden diese gespeicherte Antwort zurück (auch einen Fehler unter 500), statt erneut zu rendern und abzurechnen; die SDKs senden bei jedem Rendering einen Schlüssel mit. Eine Anfrage, die eintrifft, während die erste noch läuft, hält der Schlüssel nicht zurück: Beide rendern. Ein langsames synchrones Rendering wechselt zu asynchron, statt abzubrechen, und die Deduplizierung beantwortet ein identisches Live-Rendering einer Vorlage oder von HTML innerhalb von 24 Stunden mit der ersten Datei, für 0 Einheiten.
• Test-Schlüssel sind kostenlos. Mit ff_test_-Schlüsseln entwickeln und testen Sie: Ihre Renderings werden nicht abgerechnet, zählen nicht gegen Ihr Kontingent, und ihre Dateien werden 24 Stunden aufbewahrt. Siehe API-Schlüssel und Umgebungen.
• Gehostet in der EU. Rendern und Datenbank laufen in Frankfurt, gerenderte Dateien liegen in der EU. Siehe Datenresidenz.