Signatursitzungen & -links

Empfänger unterschreiben auf der Signaturseite von Bona Fide: entweder auf der gehosteten Seite unter https://sign.bonafidesign.com/s/… oder auf derselben Seite, eingebettet in Ihr Produkt mit <bf-signing>. Empfänger brauchen kein Konto. Zugang erhalten sie über eine Signatursitzung.

Signatursitzungen

Bei Zustellung per E-Mail werden Sitzungen für Sie erstellt (der Link in der E-Mail). Für eingebettetes oder selbst zugestelltes Unterschreiben erzeugen Sie eine Sitzung in Ihrem Backend:

curl https://api.bonafidesign.com/v1/envelopes/env_8Gm2kQ4rT1/sessions \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "recipient": "rcp_5Jw0pLs9Xe", "mode": "embedded", "allowedOrigins": ["https://app.example.com"], "ttlSeconds": 600 }'

{
  "id": "ses_2Hq8vNw3Kd",
  "token": "bfs_…",
  "url": "https://sign.bonafidesign.com/s/?embed=1#session=bfs_…",
  "expiresAt": "2026-10-13T14:08:04.512Z"
}

Feld	Hinweise
`recipient`	Ein Empfänger des Umschlags, der noch unterschreiben kann (kein CC, nicht fertig)
`mode`	`embedded` (Standard) oder `hosted`. Gehostete `url`s haben die Form `…/s/<token>`, zum Weiterleiten oder selbst Versenden
`allowedOrigins`	Bis zu 10 Origins, die die eingebettete Seite in einem Frame anzeigen dürfen
`returnUrl`	Wohin die gehostete Seite den Unterzeichner schickt, wenn er fertig ist
`ttlSeconds`	60 bis 3600, Standard 600

Sitzungen sind nur einmal verwendbar: Sobald der Empfänger absendet, ist die Sitzung verbraucht, und eine verwendete oder abgelaufene Sitzung antwortet mit 410 Gone. Erzeugen Sie bei jedem Rendern Ihrer Seite eine neue. Sitzungen lassen sich nur erstellen, solange der Umschlag sent ist, und das Stornieren des Umschlags beendet sie alle.

Was der Unterzeichner durchläuft

Die Signaturseite (und jede eigene Oberfläche, die Sie auf derselben API aufbauen) folgt diesen Schritten:

Eintauschen: POST /v1/signing/exchange { "token": "bfs_…" } liefert ein kurzlebiges Zugriffstoken (bfa_…), das im Arbeitsspeicher gehalten wird. Es werden keine Cookies verwendet, daher spielt das Blockieren von Drittanbieter-Cookies in einem iframe keine Rolle.
Laden: GET /v1/signing/session liefert die Ansicht des Unterzeichners (Titel des Umschlags, Absender, Rolle und Felder des Empfängers, vorbelegte Werte, den Verbraucherhinweis) und erfasst beim ersten Mal recipient.viewed. GET /v1/signing/document ist das anzuzeigende PDF.
Verifizieren (nur mit email_otp): POST /v1/signing/otp sendet einen sechsstelligen Code per E-Mail (10 Minuten gültig), und POST /v1/signing/otp/verify prüft ihn. Ein falscher Code liefert verified: false mit den verbleibenden Versuchen. verification.verified in der Ansicht ist bereits true, wenn die Methode des Empfängers keinen Code erfordert.
Absenden: POST /v1/signing/submit mit den values der Felder (gezeichnete, getippte oder hochgeladene Unterschriften), der Einwilligung in den Hinweis und viewedDocumentHash: dem SHA-256 genau des PDFs, das angezeigt wurde. Hat sich das Dokument seitdem geändert, wird das Absenden abgelehnt (409).
Oder ablehnen: POST /v1/signing/decline { "reason": "…" } beendet den Umschlag (envelope.declined).

Der Empfänger ist erst an der Reihe, wenn alle früheren Routing-Gruppen fertig sind; vorher enthält die Ansicht canSign: false, und ein Absenden wird mit 409 not-your-turn beantwortet.

Verifizierung der Unterzeichner

Jeder Empfänger hat eine verification-Methode: die der Rolle (festgelegt im Rollenbereich des Vorlagen-Designers), sofern der Umschlag sie nicht pro Empfänger überschreibt (im Sendebildschirm oder mit recipients[].verification).

Methode	Was der Unterzeichner tut	Geeignet, wenn
`none` (Standard)	Öffnet den eindeutigen Signaturlink und unterschreibt	Der Link wird ihm per E-Mail gesendet: Nur wer Zugriff auf dieses Postfach hat, besitzt ihn
`email_otp`	Öffnet den Link und gibt dann einen sechsstelligen Code ein, der an dieselbe Adresse gesendet wurde	Sie einen zweiten, frischen Nachweis im Moment der Unterschrift wünschen (Verträge mit hohem Wert, geteilte Postfächer)
`integrator_asserted`	Unterschreibt in Ihrem Produkt, das für seine Identität bürgt (`externalUserId`)	Eingebettete Unterschrift hinter Ihrer eigenen Anmeldung

none ist der Standard, weil der Link, den Bona Fide per E-Mail sendet, selbst eindeutig für den Empfänger und nicht zu erraten ist: Wer ihn öffnet, zeigt die Kontrolle über die E-Mail-Adresse, und genau auf diese Zuordnung stützen sich die Gesetze zu elektronischen Signaturen (ESIGN / UETA in den USA, einfache elektronische Signaturen nach eIDAS). Vergleichbare Produkte verwenden dies ebenfalls als Standard. Mit email_otp veröffentlichte Vorlagen behalten diese Methode, und ein ausdrückliches email_otp funktioniert weiterhin überall.

Zwei Abläufe verlassen sich nie allein auf einen Link:

Dauerhafte Signaturlinks (/l/…): Der Besucher gibt seine eigene Adresse ein und bestätigt deshalb immer einen per E-Mail gesendeten Code, bevor ein Umschlag erstellt wird, unabhängig von der Vorlage.
Von Ihnen erzeugte Sitzungen (POST /v1/envelopes/{id}/sessions) enthalten überhaupt keinen Nachweis der E-Mail-Adresse: Das ist Aufgabe Ihrer Anmeldung, verwenden Sie für sie daher integrator_asserted (mit externalUserId) oder email_otp.

Das Abschlusszertifikat hält pro Unterzeichner fest, was tatsächlich verwendet wurde:

Erfasst als	Wann
E-Mail-Link (eindeutiger Link, gesendet an Adresse)	`none`, über den per E-Mail gesendeten Link unterschrieben
E-Mail-Link + Einmalcode (gesendet an Adresse)	`email_otp`, über den per E-Mail gesendeten Link unterschrieben
Signaturlink + Einmalcode (gesendet an Adresse)	Ein Besucher eines dauerhaften Links
Einmalcode (gesendet an Adresse)	`email_otp` in einer von Ihnen erzeugten Sitzung
Vom Absender ausgestellte Signatursitzung	`none` in einer von Ihnen erzeugten Sitzung
Bestätigung durch den Integrator	`integrator_asserted`

Die öffentliche Prüfzusammenfassung zeigt dieselben Bezeichnungen ohne die Adresse.

Sprachen

Die Signaturseite, ihre E-Mails (Anfrage, Erinnerungen, Codes, abgeschlossen, storniert), die Seite der dauerhaften Links und die Statusseite für Beobachter sind in 50 Sprachen verfügbar. Ein Unterzeichner sieht sie in dieser Rangfolge:

die Sprache, die er im Sprachmenü der Seite gewählt hat (auf diesem Gerät gespeichert);
<bf-signing locale="…"> (eingebettete Unterschrift) oder ?locale= bei einem gehosteten Link;
die locale des Empfängers, festgelegt beim Erstellen des Umschlags (recipients[].locale oder locale am Umschlag für alle ohne eigene Angabe);
die Sprache seines Browsers.

E-Mails brauchen eine Sprache, bevor jemand eine Seite öffnet. Sie verwenden daher die locale des Empfängers und sind ohne Angabe auf Englisch. Dauerhafte Links senden die E-Mail mit dem Code in der Sprache, die die Seite des Besuchers anzeigt.

{
  "template": "tpl_…",
  "locale": "es-419",
  "recipients": [
    { "role": "client", "name": "Ana Souza", "email": "ana@example.com", "locale": "pt-BR" },
    { "role": "company", "name": "Lee Park", "email": "lee@example.com" }
  ]
}

Ähnliche Tags werden akzeptiert und als die Sprache gespeichert, der sie entsprechen (de-AT → de, es-MX → es-419, zh-TW → zh-Hant); alles andere ist ein Validierungsfehler. Übersetzte Einwilligungshinweise weisen darauf hin, dass der englische Text gilt, und der Unterzeichner kann zu ihm wechseln; die Sprache, in der der Hinweis gelesen wurde, wird mit der Unterschrift erfasst (consentLocale im Audit-Event recipient.signed).

Code	Sprache	Eigenname
`ar`	Arabisch	العربية	von rechts nach links
`hy`	Armenisch	Հայերեն
`bn`	Bengalisch	বাংলা
`bg`	Bulgarisch	Български
`zh-Hans`	Chinesisch (vereinfacht)	简体中文
`zh-Hant`	Chinesisch (traditionell)	繁體中文
`hr`	Kroatisch	Hrvatski
`cs`	Tschechisch	Čeština
`da`	Dänisch	Dansk
`nl`	Niederländisch	Nederlands
`en-GB`	Englisch (Vereinigtes Königreich)	English (UK)
`en-US`	Englisch (USA)	English (US)
`et`	Estnisch	Eesti
`fil`	Filipino	Filipino
`fi`	Finnisch	Suomi
`fr`	Französisch	Français
`fr-CA`	Französisch (Kanada)	Français (Canada)
`de`	Deutsch	Deutsch
`el`	Griechisch	Ελληνικά
`he`	Hebräisch	עברית	von rechts nach links
`hi`	Hindi	हिन्दी
`hu`	Ungarisch	Magyar
`id`	Indonesisch	Bahasa Indonesia
`it`	Italienisch	Italiano
`ja`	Japanisch	日本語
`ko`	Koreanisch	한국어
`lv`	Lettisch	Latviešu
`lt`	Litauisch	Lietuvių
`ms`	Malaiisch	Bahasa Melayu
`mr`	Marathi	मराठी
`nb`	Norwegisch	Norsk bokmål
`fa`	Persisch (Farsi)	فارسی	von rechts nach links
`pl`	Polnisch	Polski
`pt-BR`	Portugiesisch (Brasilien)	Português (Brasil)
`pt-PT`	Portugiesisch (Portugal)	Português (Portugal)
`ro`	Rumänisch	Română
`ru`	Russisch	Русский
`sr-Latn`	Serbisch (lateinisch)	Srpski
`sk`	Slowakisch	Slovenčina
`sl`	Slowenisch	Slovenščina
`es-419`	Spanisch (Lateinamerika)	Español (Latinoamérica)
`es-ES`	Spanisch (Spanien)	Español (España)
`sw`	Swahili	Kiswahili
`sv`	Schwedisch	Svenska
`te`	Telugu	తెలుగు
`th`	Thailändisch	ไทย
`tr`	Türkisch	Türkçe
`uk`	Ukrainisch	Українська
`ur`	Urdu	اردو	von rechts nach links
`vi`	Vietnamesisch	Tiếng Việt

Dauerhafte Signaturlinks

Ein Signaturlink ist eine dauerhafte URL für Verträge, die viele Personen auf dieselbe Weise unterschreiben: eine Verzichtserklärung, ein Vertrag für Freiberufler, Bedingungen für ein Pilotprojekt. Jeder Besucher, der ihn abschließt, erhält seinen eigenen Umschlag.

curl https://api.bonafidesign.com/v1/signing-links \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "tpl_…",
    "visitorRole": "contractor",
    "countersign": { "role": "company", "mode": "auto" },
    "limits": { "perEmailPerDay": 3, "perIpPerHour": 20, "dailyCap": 200, "allowedEmailDomains": ["example.com"] }
  }'

visitorRole ist die Unterzeichnerrolle, die der Besucher übernimmt. Links unterstützen einen Besucher und höchstens einen Gegenzeichner: mode: "auto" zeichnet automatisch mit dem Plattformsiegel von Bona Fide gegen, mode: "person" leitet den Umschlag an die angegebene email weiter. Jede weitere Nicht-CC-Rolle hätte keinen Empfänger, daher werden solche Vorlagen abgelehnt.
Der Besucher gibt seinen Namen, seine E-Mail-Adresse und die Variablen der Vorlage ein und bestätigt dann einen E-Mail-Code, bevor irgendetwas erstellt wird (POST /v1/links/{id}/start, dann POST /v1/links/{id}/verify).
limits begrenzt die Nutzung pro E-Mail-Adresse und Tag (Standard 3), pro IP und Stunde (Standard 20), pro Tag insgesamt und nach E-Mail-Domain. Mit dedupe (standardmäßig an) erhält eine E-Mail-Adresse, die bereits unterschrieben hat, 409 already-signed.
PATCH /v1/signing-links/{id} pausiert (active: false) oder reaktiviert den Link oder stellt ihn auf eine neuere Version um; beim Löschen eines Links bleiben die damit erstellten Umschläge erhalten. Jede Nutzung löst signing_link.used aus.