Vorlagen, Rollen & Felder

Eine Vorlage ist ein wiederverwendbarer Vertrag. Sie hat einen Namen, genau einen Entwurf und beliebig viele veröffentlichte Versionen. Umschläge werden immer aus einer veröffentlichten Version erstellt, und diese ist unveränderlich: Eine Vorlage zu bearbeiten bedeutet, einen neuen Entwurf zu speichern und ihn als nächste Version zu veröffentlichen. Bereits gesendete Umschläge behalten die Version, die sie festgelegt haben.

{
  "id": "tpl_3kQ9xV2mLp",
  "organization": "org_…",
  "name": "Mutual NDA",
  "description": "Two-party NDA, US law",
  "latestVersion": 3,
  "draftVersion": 4,
  "createdAt": "2026-10-01T09:12:44.120Z",
  "updatedAt": "2026-10-12T16:03:10.981Z"
}

IDs sind Strings mit Präfix (tpl_, tplv_, tfl_, env_, rcp_, ses_, lnk_, evt_, whk_, whd_, …); Zeitstempel sind RFC 3339 in UTC.

Zwei Arten der Erstellung

Der Overlay-Modus (source: "pdf") beginnt mit einem hochgeladenen Dokument. Felder sind Rechtecke, die in PDF-Punkten (1/72 Zoll) auf dessen Seiten platziert werden, mit dem Ursprung oben links auf der Seite und einem Seitenindex ab 0. Ein hochgeladenes .docx wird einmalig in ein PDF umgewandelt (mit LibreOffice, wobei das Word-Layout erhalten bleibt; Schriften, die die Datei nicht einbettet, können ersetzt werden) und ist von da an ein PDF wie jedes andere: Die Datei meldet convertedFrom: "docx". Overlay-Versionen können außerdem Inhaltsänderungen enthalten (direkt bearbeiteter Text, Abdeckungen, Textfelder, Bilder, Seitenoperationen), die beim Veröffentlichen der Version angewendet werden.

Der Dokumentmodus (source: "document") speichert den Vertrag selbst als Rich Text (ProseMirror-JSON) mit Variablen-Chips wie {{client.name}}, eingebetteten Feldblöcken, bedingten Abschnitten (die nur erhalten bleiben, wenn ein showIf-Ausdruck wahr ist) sowie wiederholten Abschnitten und Tabellenzeilen (eine pro Element einer Array-Variable). Jeder Umschlag rendert sein eigenes PDF, und die Feldpositionen werden aus diesem Rendering gelesen. Im Dashboard heißt der Dokumentmodus „Mit leerem Dokument beginnen“. Über die API lässt sich eine Word-Datei auch mit POST /v1/templates/{id}/import in den Dokumentmodus importieren: {{tags}} werden zu Variablen oder Feldern, und Unterschriftszeilen („Signature: ____“, „By: ____“, „Date: ____“) werden zu Feldblöcken.

Im Dashboard

Neue Vorlage bietet zwei Einstiege:

Dokument hochladen: ein Ablagebereich für .pdf- und .docx-Dateien bis 25 MB. Word-Dateien werden in PDF umgewandelt und im Designer geöffnet, mit dem Hinweis, das umgewandelte Layout zu prüfen, bevor Sie Felder platzieren. Kleine Korrekturen nehmen Sie direkt im PDF vor („Inhalt bearbeiten“); für eine größere Überarbeitung ändern Sie die Word-Datei und laden sie erneut hoch.
Mit leerem Dokument beginnen: den Vertrag im Dokumentmodus schreiben.

Inhaltsänderungen

Der Modus Inhalt bearbeiten im Designer ändert, was Unterzeichner sehen, ohne die hochgeladene Datei anzutasten. Sein Standardwerkzeug, Text bearbeiten, hebt die Textblöcke der Seite hervor (Zeilen und Absätze, gruppiert aus der Textebene des PDFs); klicken Sie auf einen Block, oder springen Sie mit Tab dorthin und drücken Sie Enter, um ihn direkt an derselben Position, in derselben Größe, Farbe, Ausrichtung und Schrift zu bearbeiten. Strg/Cmd+Enter speichert, Esc bricht ab, und jede Änderung lässt sich in der Änderungsliste zurücknehmen. Änderungen lassen sich wie jede andere Änderung rückgängig machen. Die übrigen Werkzeuge fügen Abdeckungen, Textfelder und Bilder hinzu und fügen Seiten ein, löschen, ordnen oder drehen sie.

Eine direkte Textänderung wird als zwei Elemente mit gemeinsamer group gespeichert: eine Abdeckung über dem ursprünglichen Block (in der Hintergrundfarbe der Seite) und ein Textelement, das im Block gesetzt wird, mit der Zeilenhöhe und der ersten Grundlinie des Blocks:

[
  { "id": "whiteout_k2", "kind": "whiteout", "group": "blk_k1", "page": 0, "color": "#FFFFFF",
    "rect": { "x": 71, "y": 209.9, "width": 452, "height": 26.9 } },
  { "id": "text_k3", "kind": "text", "group": "blk_k1", "page": 0, "rect": { "x": 72, "y": 210.9, "width": 451, "height": 24.9 },
    "text": "1. Purpose. The Parties wish to evaluate a joint venture…", "original": "1. Purpose. The Parties wish to evaluate a possible business relationship…",
    "size": 10.5, "lineHeight": 15.23, "baseline": 7.54, "padding": 0, "align": "left", "color": "#0B0F1A",
    "face": { "source": "pdf", "name": "ABCDEF+Calibri", "fallback": "carlito" }, "font": "helvetica" }
]

face wählt die Schrift: die im PDF eingebettete Schrift, wenn sie jedes Zeichen des neuen Textes darstellen kann, andernfalls eine mitgelieferte, metrisch kompatible Schrift (sans Arimo für Helvetica/Arial, serif Tinos für Times, mono Cousine für Courier, carlito Carlito für Calibri) im passenden Schriftschnitt. Der Text bricht innerhalb des Blocks um; braucht er mehr Zeilen als das Original, wächst die Änderung in den freien Platz darunter, und der Designer verweigert das Speichern, wenn keiner vorhanden ist („Text passt nicht – kürzen Sie ihn oder schaffen Sie Platz“). Designer und API teilen sich den Layout- und Schriftcode, sodass das veröffentlichte PDF Zeile für Zeile der Vorschau entspricht.

Änderungen sind nur an einem Entwurf möglich. Beim Veröffentlichen werden sie auf ein neues Basis-PDF angewendet, dessen SHA-256 der documentHash der Version ist (der Hash dessen, was Unterzeichner sehen); das hochgeladene Original bleibt als sourceFile der Version erhalten, und der nächste Entwurf beginnt damit, mit denselben Änderungen. Eine Abdeckung verdeckt Inhalte nur optisch; der ursprüngliche Text bleibt darunter in der Datei, daher ist sie keine sichere Schwärzung.

Rollen

Rollen sind die Vertragsparteien. Die Empfänger eines Umschlags werden den Rollen über key zugeordnet.

{ "key": "client", "label": "Client", "kind": "signer", "order": 1, "verification": "none" }

Eigenschaft	Bedeutung
`key`	Bezeichner in Kleinbuchstaben (`^[a-z][a-z0-9_]*$`), den Felder und Empfänger von Umschlägen verwenden
`kind`	`signer` (muss ein Unterschrifts- oder Initialenfeld haben), `approver`, `form_filler` oder `cc` (erhält das Dokument, unterschreibt nie)
`order`	Routing-Reihenfolge ab 1. Rollen mit derselben Reihenfolge unterschreiben parallel; die nächste Stufe beginnt, wenn sie fertig sind
`verification`	Wie der Empfänger der Rolle seine Identität nachweist: `none` (Standard: nur der eindeutige Signaturlink) oder `email_otp` (der Link plus ein per E-Mail gesendeter Code). Ein Empfänger kann dies überschreiben; siehe Verifizierung der Unterzeichner

passkey, id_check und sms_otp stehen im Schema, sind für das Unterschreiben aber noch nicht verfügbar: Eine Vorlage, die passkey oder id_check verwendet, kann nicht veröffentlicht werden, und SMS-Codes werden noch nicht zugestellt.

Felder

{
  "id": "client_signature",
  "type": "signature",
  "role": "client",
  "label": "Signature",
  "required": true,
  "rect": { "page": 1, "x": 72, "y": 610, "width": 220, "height": 48 }
}

Feldtypen: signature, initials, name, email, date_signed, text, number, date, checkbox, radio, dropdown, attachment, formula, stamp und variable_text (vom Absender aus einer Variable befüllt, nicht von einem Unterzeichner). Felder können außerdem Folgendes haben:

variable: einen JSON Pointer in die Variablen (/client/name), um das Feld zu binden oder vorzubelegen;
options für radio und dropdown;
validation: pattern, min, max, maxLength oder ein format (email, phone, date, number, currency);
showIf: eine Bedingung über Variablen und andere Felder, etwa plan != "free";
formula: einen berechneten, schreibgeschützten Wert;
overflow: was geschehen soll, wenn ein Wert nicht ins Feld passt: shrink (Standard), wrap oder reject.

Variablen

Die variables einer Version sind ein JSON Schema (Draft 2020-12) für die Daten, die Sie mit jedem Umschlag senden; sampleVariables der Version ist ein Beispiel. POST /v1/envelopes validiert Ihre variables dagegen und meldet jedes Problem mit einem JSON Pointer:

{
  "type": "https://bonafidesign.com/problems/validation-error",
  "title": "Validation failed",
  "status": 422,
  "detail": "The request is invalid.",
  "errors": [
    { "pointer": "/variables/client/name", "message": "is required", "hint": "Provide a value for 'name'." }
  ]
}

Um das Ergebnis vor dem Senden zu sehen, rendern Sie mit POST /v1/templates/{id}/versions/{version}/render ({ "variables": { … } } → PDF) eine Vorschau mit Wasserzeichen von einer beliebigen Version, oder erstellen Sie den Umschlag mit ?dry_run=true.

Eine Vorlage mit der API erstellen

Die meisten Teams gestalten Vorlagen im Designer des Dashboards. Alles, was er kann, ist auch über die API verfügbar:

POST /v1/templates mit { "name": "Mutual NDA" }.
POST /v1/templates/{id}/files mit dem PDF (oder .docx) als Body (Content-Type: application/pdf) oder als Multipart-Feld file. Bis 25 MB. Die Antwort enthält die Datei-ID (tfl_…), die Seitenzahl und die Seitengrößen.
PUT /v1/templates/{id}/draft mit roles, fields, variables (und file oder source: "document" mit content). Entwürfe werden gespeichert, wie sie sind; noch wird nichts geprüft.
POST /v1/templates/{id}/publish. Beim Veröffentlichen wird der Entwurf geprüft: Die Rolle jedes Felds existiert, jede Unterzeichnerrolle hat ein Unterschriftsfeld, Felder passen auf ihre Seiten, Radio- und Dropdown-Felder haben Optionen, Ausdrücke lassen sich parsen. Probleme kommen als 422 mit Pointern wie /fields/3/rect zurück.

curl https://api.bonafidesign.com/v1/templates/tpl_3kQ9xV2mLp/files \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @nda.pdf

Versions-Endpunkte akzeptieren eine Zahl, latest oder draft: GET /v1/templates/{id}/versions/latest, GET /v1/templates/{id}/versions/2/document (das Basis-PDF). Eine Vorlage, die nie von einem Umschlag oder einem Signaturlink verwendet wurde, kann gelöscht werden; andernfalls antwortet DELETE mit 409 in-use.