Szybki start

Ten przewodnik prowadzi od opublikowanego szablonu do podpisanego, zapieczętowanego pliku PDF. Korzysta z klucza testowego, więc nic nie jest rozliczane, a każdy dokument ma znak wodny TEST.

1. Utwórz klucz API

   Klucze API tworzy się w panelu, w sekcji Ustawienia › Klucze API. Na potrzeby tego przewodnika wybierz Test: klucz zaczyna się od bf_test_. Pełny klucz jest wyświetlany tylko raz; zapisz go jako zmienną środowiskową.

   export BONA_FIDE_API_KEY=bf_test_…

   Każde żądanie przesyła go jako Authorization: Bearer … (lub x-api-key: …). Zobacz Uwierzytelnianie.

2. Znajdź swój szablon

   Szablony projektuje się w panelu (prześlij dokument PDF lub Word i rozmieść pola albo napisz go w trybie Document), a następnie publikuje. Pobierz ich listę, aby uzyskać identyfikator:

   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 zwraca roles i fields danej wersji oraz JSON Schema jej variables. Strona szablonu w panelu ma też panel Użyj w API z gotowym żądaniem dla dokładnie tej wersji.

3. Utwórz kopertę

   POST /v1/envelopes renderuje szablon z Twoimi zmiennymi, przypina wersję i rozpoczyna kierowanie do odbiorców. Podaj jednego odbiorcę na każdą rolę (role CC są opcjonalne). Wyślij Idempotency-Key, aby ponowienie nie mogło wysłać koperty dwa razy.

   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()

   Odpowiedź to 201 Created z kopertą:

   {
     "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
   }

   Wypróbuj bez wysyłania

   Dodaj ?dry_run=true, aby zwalidować zmienne i odbiorców oraz wyrenderować dokument bez zapisywania, wysyłania i rozliczania czegokolwiek. Odpowiedź (200) zawiera documentHash wyrenderowanego dokumentu i liczbę stron.

   delivery określa, jak docierasz do odbiorców: email (domyślnie) wysyła każdemu odbiorcy link do podpisu, gdy nadejdzie jego kolej; embedded i none nie wysyłają wiadomości e-mail, a sesje podpisywania otwierasz samodzielnie (następny krok).

4. Pozwól odbiorcy podpisać

   Utwórz dla odbiorcy sesję podpisywania w swoim backendzie. Sesje są krótkotrwałe (ttlSeconds, od 60 do 3600, domyślnie 600) i jednorazowe.

   Osadzone

   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"]
     }'

   Przekaż zwrócony token (bfs_…) do swojej strony i wyrenderuj komponent webowy:

   <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>

   Nakładki dla React i Vue, zdarzenia i model bezpieczeństwa: Osadzone podpisywanie.

   Hostowane

   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" }'

   Przekieruj osobę podpisującą pod zwrócony url (https://sign.bonafidesign.com/s/bfs_…). Hostowana strona jest projektowana przede wszystkim z myślą o urządzeniach mobilnych i nie wymaga konta.

   Przy domyślnej weryfikacji email_otp osoba podpisująca przed wysłaniem potwierdza sześciocyfrowy kod wysłany na jej adres e-mail. W trybie testowym wiadomości e-mail są dostarczane tylko członkom Twojej organizacji, więc podczas testów używaj własnego adresu.

5. Otrzymaj powiadomienie o zakończeniu

   Zarejestruj punkt końcowy webhooka w sekcji Ustawienia › Webhooki (lub za pomocą POST /v1/webhook-endpoints) i zachowaj sekret whsec_…. Gdy podpisze ostatni odbiorca, otrzymasz envelope.completed ze wszystkimi zmiennymi i wpisanymi wartościami w data.values. Zapieczętowany PDF pojawi się wraz ze zdarzeniem 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);
   });

   Pobierz zapieczętowany PDF (dokument z certyfikatem ukończenia, opatrzony znacznikiem czasu):

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

   Pełna lista zdarzeń, ponawianie i ręczna weryfikacja: Webhooki.

Przejście na produkcję

Zamień klucz testowy na klucz bf_live_. Koperty produkcyjne nie mają znaku wodnego, wiadomości e-mail trafiają do każdego odbiorcy, a zakończone koperty wliczają się do Twojego planu (Plany i limity). Wszystko, co tworzy klucz, przejmuje jego tryb, jego listy pokazują tylko ten tryb, a koperty testowe powiadamiają wyłącznie punkty końcowe webhooków w trybie testowym, więc zarejestruj też punkt końcowy produkcyjny.