Schnellstart

Diese Anleitung führt von einer veröffentlichten Vorlage bis zu einem unterschriebenen, versiegelten PDF. Sie verwendet einen Testschlüssel: Es wird nichts berechnet, und jedes Dokument trägt das Wasserzeichen TEST.

1. API-Schlüssel erstellen

   API-Schlüssel werden im Dashboard unter Einstellungen › API-Schlüssel erstellt. Wählen Sie für diese Anleitung Test: Der Schlüssel beginnt mit bf_test_. Der vollständige Schlüssel wird nur einmal angezeigt; speichern Sie ihn als Umgebungsvariable.

   export BONA_FIDE_API_KEY=bf_test_…

   Jede Anfrage sendet ihn als Authorization: Bearer … (oder x-api-key: …). Siehe Authentifizierung.

2. Vorlage finden

   Vorlagen werden im Dashboard gestaltet (ein PDF oder Word-Dokument hochladen und Felder platzieren oder den Vertrag im Dokumentmodus schreiben) und anschließend veröffentlicht. Listen Sie sie auf, um die ID zu erhalten:

   curl

   curl https://api.bonafidesign.com/v1/templates \
     -H "Authorization: Bearer $BONA_FIDE_API_KEY"

   TypeScript

   const res = await fetch('https://api.bonafidesign.com/v1/templates', {
     headers: { Authorization: `Bearer ${process.env.BONA_FIDE_API_KEY}` },
   });
   const { data } = await res.json(); // [{ id: 'tpl_…', name: 'Mutual NDA', latestVersion: 3, … }]

   Python

   import os, requests
   
   API = "https://api.bonafidesign.com"
   headers = {"Authorization": f"Bearer {os.environ['BONA_FIDE_API_KEY']}"}
   
   templates = requests.get(f"{API}/v1/templates", headers=headers).json()["data"]

   GET /v1/templates/{id}/versions/latest liefert die roles und fields der Version sowie das JSON Schema ihrer variables. Die Vorlagenseite im Dashboard hat außerdem ein Panel In API verwenden mit einer fertigen Anfrage für genau diese Version.

3. Umschlag erstellen

   POST /v1/envelopes rendert die Vorlage mit Ihren Variablen, legt die Version fest und startet das Routing. Geben Sie einen Empfänger pro Rolle an (CC-Rollen sind optional). Senden Sie einen Idempotency-Key mit, damit eine Wiederholung nicht doppelt versendet.

   curl

   curl https://api.bonafidesign.com/v1/envelopes \
     -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: onboarding-8841" \
     -d '{
       "template": "tpl_…",
       "version": "latest",
       "variables": {
         "client": { "name": "Acme Robotics, Inc." },
         "effective_date": "2026-10-13"
       },
       "recipients": [
         { "role": "client", "name": "Jane Doe", "email": "jane@acme.dev" }
       ],
       "delivery": "embedded",
       "externalId": "user_8841",
       "dedupeOn": "external_id"
     }'

   TypeScript

   const res = await fetch('https://api.bonafidesign.com/v1/envelopes', {
     method: 'POST',
     headers: {
       Authorization: `Bearer ${process.env.BONA_FIDE_API_KEY}`,
       'Content-Type': 'application/json',
       'Idempotency-Key': 'onboarding-8841',
     },
     body: JSON.stringify({
       template: 'tpl_…',
       version: 'latest',
       variables: { client: { name: 'Acme Robotics, Inc.' }, effective_date: '2026-10-13' },
       recipients: [{ role: 'client', name: 'Jane Doe', email: 'jane@acme.dev' }],
       delivery: 'embedded',
       externalId: 'user_8841',
       dedupeOn: 'external_id',
     }),
   });
   if (res.status === 422) {
     // RFC 9457 problem: one entry per error, each with a JSON Pointer such as /variables/client/name
     console.error((await res.json()).errors);
   }
   const envelope = await res.json(); // { id: 'env_…', status: 'sent', recipients: [{ id: 'rcp_…', … }] }

   Python

   res = requests.post(
       f"{API}/v1/envelopes",
       headers={**headers, "Idempotency-Key": "onboarding-8841"},
       json={
           "template": "tpl_…",
           "version": "latest",
           "variables": {"client": {"name": "Acme Robotics, Inc."}, "effective_date": "2026-10-13"},
           "recipients": [{"role": "client", "name": "Jane Doe", "email": "jane@acme.dev"}],
           "delivery": "embedded",
           "externalId": "user_8841",
           "dedupeOn": "external_id",
       },
   )
   if res.status_code == 422:
       print(res.json()["errors"])  # [{"pointer": "/variables/client/name", "message": "…"}]
   envelope = res.json()

   Die Antwort ist 201 Created mit dem Umschlag:

   {
     "id": "env_8Gm2kQ4rT1",
     "organization": "org_…",
     "template": "tpl_…",
     "templateVersion": 3,
     "status": "sent",
     "seal": "not_started",
     "testMode": true,
     "recipients": [
       {
         "id": "rcp_5Jw0pLs9Xe",
         "role": "client",
         "name": "Jane Doe",
         "email": "jane@acme.dev",
         "order": 1,
         "status": "sent",
         "verification": "email_otp",
         "completedAt": null
       }
     ],
     "documentHash": "9f2c…",
     "sealedDocumentHash": null,
     "externalId": "user_8841",
     "metadata": {},
     "createdAt": "2026-10-13T13:58:04.512Z",
     "completedAt": null
   }

   Ausprobieren, ohne zu senden

   Hängen Sie ?dry_run=true an, um Variablen und Empfänger zu validieren und das Dokument zu rendern, ohne etwas zu speichern, zu senden oder zu berechnen. Die Antwort (200) enthält den gerenderten documentHash und die Seitenzahl.

   delivery legt fest, wie Empfänger erreicht werden: Bei email (Standard) erhält jeder Empfänger einen Signaturlink per E-Mail, sobald er an der Reihe ist; embedded und none senden keine E-Mail, und Sie öffnen die Signatursitzungen selbst (nächster Schritt).

4. Empfänger unterschreiben lassen

   Erzeugen Sie in Ihrem Backend eine Signatursitzung für den Empfänger. Sitzungen sind kurzlebig (ttlSeconds, 60 bis 3600, Standard 600) und nur einmal verwendbar.

   Eingebettet

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

   Übergeben Sie das zurückgegebene token (bfs_…) an Ihre Seite und rendern Sie die Web Component:

   <script type="module" src="https://js.bonafidesign.com/v1"></script>
   
   <bf-signing session="bfs_…"></bf-signing>
   <script>
     document.querySelector('bf-signing')
       .addEventListener('completed', (e) => console.log('signed', e.detail.envelope));
   </script>

   Wrapper für React und Vue, Events und das Sicherheitsmodell: Eingebettete Unterschrift.

   Gehostet

   curl https://api.bonafidesign.com/v1/envelopes/env_8Gm2kQ4rT1/sessions \
     -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "recipient": "rcp_5Jw0pLs9Xe", "mode": "hosted", "returnUrl": "https://app.example.com/done" }'

   Leiten Sie den Unterzeichner zur zurückgegebenen url (https://sign.bonafidesign.com/s/bfs_…) weiter. Die gehostete Seite ist für Mobilgeräte optimiert und erfordert kein Konto.

   Mit der Standardverifizierung email_otp bestätigt der Unterzeichner vor dem Absenden einen sechsstelligen Code, der an seine E-Mail-Adresse gesendet wird. Im Testmodus werden E-Mails nur an Mitglieder Ihrer Organisation zugestellt; verwenden Sie beim Testen also Ihre eigene Adresse.

5. Beim Abschluss benachrichtigt werden

   Registrieren Sie unter Einstellungen › Webhooks (oder mit POST /v1/webhook-endpoints) einen Webhook-Endpunkt und bewahren Sie das Secret whsec_… auf. Sobald der letzte Empfänger unterschrieben hat, erhalten Sie envelope.completed mit allen Variablen und eingegebenen Werten in data.values. Das versiegelte PDF folgt mit envelope.sealed.

   import express from 'express';
   import { Webhook } from 'standardwebhooks';
   
   const wh = new Webhook(process.env.BONA_FIDE_WEBHOOK_SECRET!);
   const app = express();
   
   app.post('/hooks/bona-fide', express.raw({ type: 'application/json' }), async (req, res) => {
     const event = wh.verify(req.body, req.headers as Record<string, string>) as { type: string; data: any };
     if (event.type === 'envelope.completed') await saveValues(event.data.envelope.id, event.data.values);
     if (event.type === 'envelope.sealed') await fetchSealedPdf(event.data.envelope.id);
     res.sendStatus(204);
   });

   Laden Sie das versiegelte PDF herunter (das Dokument mit Abschlusszertifikat und Zeitstempel):

   curl -o signed.pdf "https://api.bonafidesign.com/v1/envelopes/env_8Gm2kQ4rT1/document?version=sealed" \
     -H "Authorization: Bearer $BONA_FIDE_API_KEY"

   Alle Events, Wiederholungen und manuelle Prüfung: Webhooks.

Live gehen

Ersetzen Sie den Testschlüssel durch einen bf_live_-Schlüssel. Live-Umschläge haben kein Wasserzeichen, E-Mails gehen an alle Empfänger, und abgeschlossene Umschläge werden auf Ihren Tarif angerechnet (Tarife & Limits). Alles, was ein Schlüssel erstellt, übernimmt dessen Modus, seine Listen zeigen nur diesen Modus, und Test-Umschläge benachrichtigen nur Webhook-Endpunkte im Testmodus. Registrieren Sie daher auch einen Live-Endpunkt.