Grundbegriffe

Eine Handvoll Begriffe deckt das ganze Produkt ab. Wenn sie sitzen, liest sich die API-Referenz wie eine Liste von Dingen, die Sie schon kennen.

Organisation und Workspace

Eine Organisation ist die Grenze für Abrechnung und Mitgliedschaft: ein Plan, eine Rechnung, eine Mitgliederliste. Sie hält auch, was alle Dokumente über Workspaces hinweg teilen: die Schriften, das Brand Kit und die geteilten Partials.

Jedes Mitglied hat in der Organisation eine von vier Rollen:

Rolle	Darf
Betrachter	Vorlagen, Renderings und Dateien lesen
Editor	alles, was ein Betrachter darf, dazu Vorlagen bearbeiten, speichern und veröffentlichen, rendern und Dateien hochladen
Admin	alles, was ein Editor darf, dazu API-Schlüssel anlegen und widerrufen, Webhooks verwalten, Mitglieder einladen, Vorlagen löschen
Inhaber	alles, was ein Admin darf, dazu Plan und Abrechnung

Ein Workspace ist der Ort, an dem die Arbeit liegt: Vorlagen, API-Schlüssel, Renderings, Webhook-Endpunkte und die Dateibibliothek. Jeder Workspace hat seine eigene Region und seine eigene Aufbewahrungsdauer für Ausgaben. Trennen Sie Produktion und Staging mit zwei Workspaces; Agenturen legen meist einen Workspace pro Kunde an. Wie viele Workspaces eine Organisation haben darf, hängt vom Plan ab (1 im Free-Plan, 3 im Starter-Plan, 10 im Pro-Plan).

Ein API-Schlüssel gehört zu genau einem Workspace und wirkt nur dort: Er rendert die Vorlagen dieses Workspace und listet dessen Renderings. Die einzige Ausnahme ist der Scope workspace:delete, der einen anderen Workspace derselben Organisation löschen darf.

Vorlage und Version

Eine Vorlage ist eine benannte Dokumentdefinition mit einem slug (invoice, certificate-en), auf den sich Ihr Code bezieht. Die API gibt jeder Vorlage außerdem eine ID (tpl_ gefolgt von 32 Hexadezimalzeichen); ein Rendering nimmt beides an. Eine Vorlage hat eine Art (pdf, image oder docx und pptx für Word- und PowerPoint-Vorlagen), eine Vorlagensprache (jinja2, liquid oder handlebars, siehe Vorlagensprachen) und diese Bestandteile:

Bestandteil	Inhalt
Vorlage (html)	Der Hauptteil: HTML mit Vorlagen-Tags
CSS, Head	Stylesheet und zusätzlicher Inhalt für <head>, etwa Links auf Schriften
Kopfzeile, Fußzeile	Laufende Kopf- und Fußzeile für jede PDF-Seite
Einstellungen	Papier, Ränder, Bildgröße, Locale, Zeitzone, Währung, Tailwind
Beispieldaten	Benannte JSON-Datensätze für Vorschau, Autovervollständigung und Tests; nie von einem API-Rendering verwendet
Datenschema	Ein JSON Schema der erwarteten data, abgeleitet aus den Beispieldaten, sofern Sie keins angeben
Übersetzungen	Wörterbücher pro Locale für den Helfer t()
Partials	Fragmente, die die Vorlage per Namen einbindet, gespeichert mit der Version (aus dem Ordner partials/ des CLI-Projekts)

Eine Word- oder PowerPoint-Vorlage hält statt HTML, CSS, Head, Kopf- und Fußzeile ihre Dokumentdatei; Einstellungen, Beispieldaten, Schema und Übersetzungen funktionieren wie gewohnt.

Eine Version ist ein unveränderlicher Stand all dieser Bestandteile. Speichern im Editor oder formfeed templates push legt eine neue Entwurfsversion an. Veröffentlichen macht eine Version zu der, die die API rendert; die bisher veröffentlichte wird archiviert. Es ist immer genau eine Version veröffentlicht, Sie können also an Entwürfen weiterarbeiten, ohne die Produktion zu berühren. Eine alte Version wiederherzustellen speichert einen neuen Entwurf mit ihrem Inhalt. Neben published kann eine Vorlage benannte Release Channels wie staging haben, die auf andere Versionen zeigen; ein Rendering wählt einen mit version.

Das Feld version eines Renderings nimmt:

Wert	Rendert
published	Die veröffentlichte Version (Standard)
ein Channel-Name	Die Version, auf die der Release Channel zeigt
eine Zahl, z. B. 3	Diese Version
latest	Die neueste gespeicherte Version, veröffentlicht oder nicht; nur mit Test-Schlüsseln

hinweis

Die API rendert die veröffentlichte Version, sofern ein Rendering keine Version und keinen Channel nennt, und übernimmt eine neu veröffentlichte innerhalb einer Minute. Die Vorschau im Editor und sein Echtes Rendering arbeiten mit dem, was im Editor geöffnet ist, ungespeicherte Änderungen eingeschlossen, und mit dem gewählten Beispieldatensatz.

Rendering und Job

Ein Rendering ist eine Ausführung: eine Quelle (eine Vorlage, Ad-hoc-html oder eine url) plus data plus Optionen, die genau eine Ausgabedatei erzeugt. Jedes Rendering hat eine ID (rnd_ gefolgt von 32 Hexadezimalzeichen), einen Status (queued → rendering → succeeded oder failed), Zeiten, die Einheiten, die es gekostet hat, und Prüfsummen, die es reproduzierbar machen. Siehe Rendern.

Ein Job ist ein Batch von bis zu 1.000 Renderings, die in einer Anfrage eingereicht werden (POST /v1/renders/batch). Er wird immer asynchron verarbeitet und auf Wunsch gezippt. Ein Job hat eine eigene ID (job_…) und einen eigenen Status: queued, processing, dann completed, partially_failed oder failed. Siehe Asynchron und Batch.

API-Schlüssel und Umgebungen

API-Schlüssel gibt es in zwei Umgebungen, und das Präfix zeigt, welche es ist. Inhaber und Admins legen sie auf der Seite API-Schlüssel eines Workspace an.

	Live (ff_live_…)	Test (ff_test_…)
Abgerechnet	Ja, units in der Antwort	Nein, units ist 0
Zählt gegen das Kontingent	Ja	Nein
Aufbewahrung der Ausgabe	Die Aufbewahrung des Plans oder die kürzere des Workspace	Höchstens 24 Stunden
Testmarkierung auf der Datei	Nie	Im Free-Plan; in jedem Plan bei einer E-Rechnung
Dedupliziert	Ja	Nein
version: "latest"	Abgelehnt	Erlaubt
Rate-Limit	Die Anfragen pro Sekunde des Plans, für Renderings und PDF-Tools	Ebenso, plus 30 pro Minute im Free-Plan

Verwenden Sie Test-Schlüssel für Entwicklung, CI und das Dev-Kit, und wechseln Sie in der Produktion auf einen Live-Schlüssel. Jeder Schlüssel trägt außerdem Scopes, die festlegen, was er darf. Wie lange jeder Plan Ausgaben aufbewahrt und seine übrigen Limits stehen unter Limits und Verbrauch.

Einheiten

Formfeed rechnet in Einheiten ab:

• ein PDF mit bis zu 5 Seiten kostet 1 Einheit, und je weitere angefangene 5 Seiten kommt 1 dazu: 6–10 Seiten kosten 2 Einheiten, 11–15 Seiten kosten 3;
• ein Bild (PNG, JPG oder WebP) kostet 1 Einheit, ebenso eine gefüllte Word- oder PowerPoint-Datei; ein PDF aus einer Word- oder PowerPoint-Vorlage und eines aus /pdf/convert folgen der PDF-Regel;
• jeder Post-Processing-Schritt (PDFs zusammenführen, ein Passwort setzen, ein Wasserzeichen aufbringen) kostet 0,5 Einheiten, im post eines Renderings wie bei den PDF-Tools; die Informationen eines PDFs zu lesen ist kostenlos;
• eine E-Rechnung kostet 1 Einheit zusätzlich zu ihrem Rendering;
• Renderings mit einem Test-Schlüssel, Vorschauen im Editor und Offline-Validierung sind kostenlos;
• ein dedupliziertes Rendering kostet 0 Einheiten.

Jede Render-Antwort nennt die Einheiten im Body (units) und im Header X-Units-Charged, und X-Units-Remaining zeigt, was im Abrechnungszeitraum noch übrig ist. Pläne enthalten ein Kontingent je Abrechnungszeitraum. Bezahlte Pläne laufen mit Mehrverbrauch weiter, bis zu einer Obergrenze, sofern Sie nicht das automatische Aufladen einschalten; der Free-Plan stoppt mit 402 quota_exceeded. Details unter Limits und Verbrauch.

Region

Die Region ist der Ort, an dem gerendert und die Ausgabe gespeichert wird. Heute läuft jedes Rendering in eu: gerendert wird in Frankfurt, gespeichert in der EU. us und apac sind Namen, die der API-Vertrag für Regionen reserviert, für die es noch keinen Render-Worker gibt. Lassen Sie das Feld region eines Renderings deshalb weg; es folgt der Region des Workspace. Siehe Datenresidenz.

Webhook-Endpunkt

Ein Webhook-Endpunkt ist eine HTTPS-URL in Ihrer Anwendung, die signierte Ereignisse wie render.completed oder job.completed empfängt. Darüber meldet sich asynchrone Arbeit zurück. Siehe Webhooks.