Pikaopas

Tämä opas vie julkaistun mallin allekirjoitetuksi ja sinetöidyksi PDF:ksi. Se käyttää testiavainta, joten mitään ei laskuteta ja jokaiseen asiakirjaan tulee vesileima TEST.

1. Luo API-avain

   API-avaimet luodaan hallintapaneelissa kohdassa Asetukset › API-avaimet. Valitse tätä opasta varten Test: avain alkaa merkkijonolla bf_test_. Koko avain näytetään vain kerran; tallenna se ympäristömuuttujaan.

   export BONA_FIDE_API_KEY=bf_test_…

   Jokainen pyyntö lähettää sen muodossa Authorization: Bearer … (tai x-api-key: …). Katso Todennus.

2. Etsi mallisi

   Mallit suunnitellaan hallintapaneelissa (lataa PDF- tai Word-asiakirja ja sijoita kentät tai kirjoita malli asiakirjatilassa) ja julkaistaan sitten. Hae niiden luettelo saadaksesi tunnuksen:

   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 palauttaa version roles- ja fields-tiedot sekä sen variables-kentän JSON Scheman. Hallintapaneelin mallisivulla on myös Käytä API:ssa -paneeli, jossa on valmis pyyntö juuri sille versiolle.

3. Luo kirjekuori

   POST /v1/envelopes renderöi mallin muuttujillasi, lukitsee version ja aloittaa reitityksen. Anna yksi vastaanottaja roolia kohden (CC-roolit ovat valinnaisia). Lähetä Idempotency-Key, jotta uudelleenyritys ei voi lähettää kahdesti.

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

   Vastaus on 201 Created, ja siinä on kirjekuori:

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

   Kokeile lähettämättä

   Lisää ?dry_run=true, niin muuttujat ja vastaanottajat validoidaan ja asiakirja renderöidään ilman, että mitään tallennetaan, lähetetään tai laskutetaan. Vastauksessa (200) on renderöity documentHash ja sivumäärä.

   delivery määrää, miten vastaanottajat tavoitetaan: email (oletus) lähettää jokaiselle vastaanottajalle allekirjoituslinkin sähköpostitse, kun on hänen vuoronsa; embedded ja none eivät lähetä sähköpostia, vaan avaat allekirjoitusistunnot itse (seuraava vaihe).

4. Anna vastaanottajan allekirjoittaa

   Luo vastaanottajalle allekirjoitusistunto taustajärjestelmästäsi. Istunnot ovat lyhytikäisiä (ttlSeconds, 60–3600, oletus 600) ja kertakäyttöisiä.

   Upotettu

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

   Välitä palautettu token (bfs_…) sivullesi ja renderöi verkkokomponentti:

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

   React- ja Vue-kääreet, tapahtumat ja tietoturvamalli: Upotettu allekirjoitus.

   Isännöity

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

   Ohjaa allekirjoittaja palautettuun url-osoitteeseen (https://sign.bonafidesign.com/s/bfs_…). Isännöity sivu on suunniteltu ensisijaisesti mobiilille, eikä se vaadi tiliä.

   Oletusarvoisella email_otp-vahvistuksella allekirjoittaja vahvistaa sähköpostiinsa lähetetyn kuusinumeroisen koodin ennen lähettämistä. Testitilassa sähköposti toimitetaan vain organisaatiosi jäsenille, joten käytä omaa osoitettasi testatessasi.

5. Saa ilmoitus valmistumisesta

   Rekisteröi webhook-päätepiste kohdassa Asetukset › Webhookit (tai kutsulla POST /v1/webhook-endpoints) ja säilytä whsec_…-salaisuus. Kun viimeinen vastaanottaja allekirjoittaa, saat tapahtuman envelope.completed, jonka data.values sisältää kaikki muuttujat ja syötetyt arvot. Sinetöity PDF seuraa tapahtumalla 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);
   });

   Lataa sinetöity PDF (asiakirja valmistumistodistuksineen, aikaleimattuna):

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

   Täydellinen tapahtumaluettelo, uudelleenyritykset ja manuaalinen tarkistus: Webhookit.

Tuotantoon siirtyminen

Vaihda testiavain bf_live_-avaimeen. Tuotantotilan kirjekuorissa ei ole vesileimaa, sähköposti lähtee kaikille vastaanottajille ja valmiit kirjekuoret lasketaan pakettisi kiintiöön (Paketit ja rajat). Kaikki, mitä avain luo, saa sen tilan, sen luettelot näyttävät vain sen tilan, ja testikirjekuoret ilmoittavat vain testitilan webhook-päätepisteille, joten rekisteröi myös tuotantotilan päätepiste.