Snabbstart

Den här genomgången tar en publicerad mall hela vägen till en signerad, förseglad PDF. Den använder en testnyckel, så ingenting debiteras och varje dokument vattenmärks med TEST.

1. Skapa en API-nyckel

   API-nycklar skapas i instrumentpanelen, under Inställningar › API-nycklar. Välj Test för den här genomgången: nyckeln börjar med bf_test_. Hela nyckeln visas bara en gång; spara den som en miljövariabel.

   export BONA_FIDE_API_KEY=bf_test_…

   Varje begäran skickar den som Authorization: Bearer … (eller x-api-key: …). Se Autentisering.

2. Hitta din mall

   Mallar utformas i instrumentpanelen (ladda upp ett PDF- eller Word-dokument och placera fält, eller skriv det i dokumentläge) och publiceras sedan. Lista dem för att få id:t:

   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 returnerar versionens roles, fields och JSON Schema för dess variables. Mallens sida i instrumentpanelen har också en panel, Använd i API, med en färdig begäran för just den versionen.

3. Skapa ett kuvert

   POST /v1/envelopes renderar mallen med dina variabler, låser versionen och börjar dirigera kuvertet. Ange en mottagare per roll (CC-roller är valfria). Skicka en Idempotency-Key så att ett omförsök inte kan skicka två gånger.

   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 är 201 Created med kuvertet:

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

   Prova utan att skicka

   Lägg till ?dry_run=true för att validera variablerna och mottagarna och rendera dokumentet utan att något sparas, skickas eller debiteras. Svaret (200) innehåller det renderade dokumentets documentHash och antalet sidor.

   delivery avgör hur mottagarna nås: email (standard) mejlar varje mottagare en signeringslänk när det är deras tur; embedded och none skickar inga mejl, och du öppnar signeringssessionerna själv (nästa steg).

4. Låt mottagaren signera

   Skapa en signeringssession för mottagaren från din backend. Sessioner är kortlivade (ttlSeconds, 60 till 3600, standard 600) och kan bara användas en gång.

   Inbäddat

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

   Skicka den returnerade token (bfs_…) till din sida och rendera webbkomponenten:

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

   Omslag för React och Vue, händelser och säkerhetsmodellen: Inbäddad signering.

   Hostat

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

   Omdirigera undertecknaren till den returnerade url (https://sign.bonafidesign.com/s/bfs_…). Den hostade sidan är byggd för mobilen först och kräver inget konto.

   Med standardverifieringen email_otp bekräftar undertecknaren en sexsiffrig kod som skickas till hens e-post innan hen skickar in. I testläge levereras e-post bara till medlemmar i din organisation, så använd din egen adress när du testar.

5. Få en avisering vid slutförande

   Registrera en webhook-slutpunkt under Inställningar › Webhooks (eller med POST /v1/webhook-endpoints) och spara hemligheten whsec_…. När den sista mottagaren har signerat får du envelope.completed, med alla variabler och ifyllda värden i data.values. Den förseglade PDF:en följer 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);
   });

   Ladda ned den förseglade PDF:en (dokumentet med slutförandecertifikatet, tidsstämplat):

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

   Fullständig lista över händelser, omförsök och manuell verifiering: Webhooks.

Gå live

Byt testnyckeln mot en bf_live_-nyckel. Kuvert i liveläge vattenmärks inte, e-post går till alla mottagare och slutförda kuvert räknas mot din plan (Planer och gränser). Allt som en nyckel skapar får nyckelns läge, nyckelns listor visar bara det läget och testkuvert aviserar bara webhook-slutpunkter i testläge, så registrera även en slutpunkt för liveläge.