Hurtigstart

Denne gjennomgangen tar en publisert mal helt frem til en signert, forseglet PDF. Den bruker en testnøkkel, så ingenting faktureres, og alle dokumenter får vannmerket TEST.

1. Opprett en API-nøkkel

   API-nøkler opprettes i dashbordet, under Innstillinger › API-nøkler. Velg Test for denne gjennomgangen: nøkkelen begynner med bf_test_. Hele nøkkelen vises bare én gang; lagre den som en miljøvariabel.

   export BONA_FIDE_API_KEY=bf_test_…

   Hver forespørsel sender den som Authorization: Bearer … (eller x-api-key: …). Se Autentisering.

2. Finn malen din

   Maler utformes i dashbordet (last opp en PDF eller et Word-dokument og plasser felt, eller skriv den i dokumentmodus) og publiseres deretter. List dem opp for å få ID-en:

   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 versjonens roles, fields og JSON Schema-et for variables. Malsiden i dashbordet har også et Bruk i API-panel med en ferdig forespørsel for akkurat den versjonen.

3. Opprett en konvolutt

   POST /v1/envelopes rendrer malen med variablene dine, låser versjonen og starter rutingen. Oppgi én mottaker per rolle (CC-roller er valgfrie). Send en Idempotency-Key, så kan ikke et nytt forsøk sende to ganger.

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

   {
     "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 uten å sende

   Legg til ?dry_run=true for å validere variablene og mottakerne og rendre dokumentet uten å lagre, sende eller fakturere noe. Svaret (200) inneholder den rendrede documentHash og antall sider.

   delivery avgjør hvordan mottakerne nås: email (standard) sender hver mottaker en signeringslenke på e-post når det er deres tur; embedded og none sender ingen e-post, og du åpner signeringsøktene selv (neste steg).

4. La mottakeren signere

   Opprett en signeringsøkt for mottakeren fra backenden din. Økter er kortlivede (ttlSeconds, 60 til 3600, standard 600) og kan bare brukes én gang.

   Innebygd

   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 den returnerte token (bfs_…) til siden din 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>

   Innpakninger for React og Vue, hendelser og sikkerhetsmodellen: Innebygd signering.

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

   Send signataren videre til den returnerte url (https://sign.bonafidesign.com/s/bfs_…). Den hostede siden er laget for mobil først og krever ingen konto.

   Med standardverifiseringen email_otp bekrefter signataren en sekssifret kode som sendes til e-postadressen deres, før de sender inn. I testmodus leveres e-post bare til medlemmer av organisasjonen din, så bruk din egen adresse mens du tester.

5. Bli varslet ved fullføring

   Registrer et webhook-endepunkt under Innstillinger › Webhooks (eller med POST /v1/webhook-endpoints), og ta vare på whsec_…-hemmeligheten. Når den siste mottakeren signerer, mottar du envelope.completed, med alle variabler og utfylte verdier i data.values. Den forseglede PDF-en 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);
   });

   Last ned den forseglede PDF-en (dokumentet med fullføringssertifikatet, tidsstemplet):

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

   Fullstendig liste over hendelser, nye forsøk og manuell verifisering: Webhooks.

Gå i produksjon

Bytt ut testnøkkelen med en bf_live_-nøkkel. Konvolutter i produksjon får ikke vannmerke, e-post går til alle mottakere, og fullførte konvolutter teller mot planen din (Planer og grenser). Alt en nøkkel oppretter, får nøkkelens modus, listene viser bare den modusen, og testkonvolutter varsler bare webhook-endepunkter i testmodus, så registrer også et endepunkt for produksjon.