Kom hurtigt i gang

Denne gennemgang fører en udgivet skabelon hele vejen til en underskrevet, forseglet PDF. Den bruger en testnøgle, så intet faktureres, og alle dokumenter får vandmærket TEST.

1. Opret en API-nøgle

   API-nøgler oprettes i dashboardet under Indstillinger › API-nøgler. Vælg Test til denne gennemgang: nøglen begynder med bf_test_. Den fulde nøgle vises kun én gang; gem den som en miljøvariabel.

   export BONA_FIDE_API_KEY=bf_test_…

   Hver anmodning sender den som Authorization: Bearer … (eller x-api-key: …). Se Godkendelse.

2. Find din skabelon

   Skabeloner designes i dashboardet (upload et PDF- eller Word-dokument og placer felter, eller skriv det i dokumenttilstand) og udgives derefter. Vis dem for at få id’et:

   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 returnerer versionens roles, fields og JSON Schema for dens variables. Skabelonens side i dashboardet har også et panel, Brug i API, med en færdig anmodning til netop den version.

3. Opret en kuvert

   POST /v1/envelopes renderer skabelonen med dine variabler, fastlåser versionen og begynder at sende kuverten videre. Angiv én modtager pr. rolle (CC-roller er valgfrie). Send en Idempotency-Key, så et genforsøg ikke kan sende to gange.

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

   Svaret er 201 Created med kuverten:

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

   Prøv uden at sende

   Tilføj ?dry_run=true for at validere variablerne og modtagerne og rendere dokumentet uden at gemme, sende eller fakturere noget. Svaret (200) indeholder det renderede dokuments documentHash og antallet af sider.

   delivery bestemmer, hvordan modtagerne nås: email (standard) sender hver modtager et underskriftslink pr. e-mail, når det er deres tur; embedded og none sender ingen e-mails, og du åbner selv signeringssessionerne (næste trin).

4. Lad modtageren underskrive

   Opret en signeringssession til modtageren fra din backend. Sessioner er kortlivede (ttlSeconds, 60 til 3600, standard 600) og kan kun bruges én gang.

   Indlejret

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

   Send det returnerede token (bfs_…) til din side, og render webkomponenten:

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

   Wrappers til React og Vue, hændelser og sikkerhedsmodellen: Indlejret underskrift.

   Hostet

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

   Omdiriger underskriveren til den returnerede url (https://sign.bonafidesign.com/s/bfs_…). Den hostede side er bygget til mobilen først og kræver ingen konto.

   Med standardverificeringen email_otp bekræfter underskriveren en sekscifret kode, der sendes til vedkommendes e-mail, før der indsendes. I testtilstand leveres e-mails kun til medlemmer af din organisation, så brug din egen adresse, mens du tester.

5. Få besked ved fuldførelse

   Registrer et webhook-slutpunkt under Indstillinger › Webhooks (eller med POST /v1/webhook-endpoints), og gem hemmeligheden whsec_…. Når den sidste modtager har underskrevet, modtager du envelope.completed med alle variabler og udfyldte værdier i data.values. Den forseglede PDF følger med 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);
   });

   Download den forseglede PDF (dokumentet med fuldførelsescertifikatet, tidsstemplet):

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

   Fuld liste over hændelser, genforsøg og manuel verificering: Webhooks.

Gå live

Skift testnøglen ud med en bf_live_-nøgle. Kuverter i live-tilstand får intet vandmærke, e-mails går til alle modtagere, og fuldførte kuverter tæller med i din plan (Planer og grænser). Alt, hvad en nøgle opretter, får nøglens tilstand, nøglens lister viser kun den tilstand, og testkuverter giver kun besked til webhook-slutpunkter i testtilstand, så registrer også et slutpunkt til live-tilstand.