Ga naar inhoud
bona fidedocs

Snelstart

Deze stapsgewijze uitleg brengt een gepubliceerd sjabloon naar een ondertekende, verzegelde pdf. U gebruikt een testkey, dus er wordt niets gefactureerd en elk document krijgt het watermerk TEST.

  1. Maak een API-key aan

    Section titled “Maak een API-key aan”

    API-keys maakt u aan in het dashboard, onder Instellingen › API-keys. Kies voor deze uitleg Test: de key begint met bf_test_. De volledige key wordt één keer getoond; sla hem op als omgevingsvariabele.

    Terminal window
    export BONA_FIDE_API_KEY=bf_test_…

    Elk request stuurt hem mee als Authorization: Bearer … (of x-api-key: …). Zie Authenticatie.

  2. Zoek uw sjabloon op

    Section titled “Zoek uw sjabloon op”

    Sjablonen ontwerpt u in het dashboard (upload een pdf of Word-document en plaats velden, of schrijf het in Documentmodus) en publiceert u daarna. Vraag de lijst op om het id te krijgen:

    Terminal window
    curl https://api.bonafidesign.com/v1/templates \
      -H "Authorization: Bearer $BONA_FIDE_API_KEY"

    GET /v1/templates/{id}/versions/latest geeft de roles en fields van de versie en het JSON Schema van de variables. De sjabloonpagina in het dashboard heeft ook een paneel Gebruiken in API met een kant-en-klaar request voor precies die versie.

  3. Maak een envelop aan

    Section titled “Maak een envelop aan”

    POST /v1/envelopes rendert het sjabloon met uw variabelen, legt de versie vast en start de routering. Geef één ontvanger per rol op (CC-rollen zijn optioneel). Stuur een Idempotency-Key mee, zodat een nieuwe poging niet twee keer kan versturen.

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

    Het antwoord is 201 Created met de envelop:

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

    delivery bepaalt hoe ontvangers worden bereikt: bij email (de standaard) krijgt elke ontvanger een ondertekeningslink per e-mail zodra die aan de beurt is; bij embedded en none wordt er geen e-mail verstuurd en opent u de ondertekeningssessies zelf (volgende stap).

  4. Laat de ontvanger ondertekenen

    Section titled “Laat de ontvanger ondertekenen”

    Maak vanuit uw backend een ondertekeningssessie aan voor de ontvanger. Sessies zijn kortlevend (ttlSeconds, 60 tot 3600, standaard 600) en voor eenmalig gebruik.

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

    Geef het geretourneerde token (bfs_…) door aan uw pagina en render de webcomponent:

    <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 voor React en Vue, events en het beveiligingsmodel: Ingesloten ondertekening.

    Met de standaardverificatie email_otp bevestigt de ondertekenaar vóór het indienen een zescijferige code die naar zijn of haar e-mailadres is gestuurd. In testmodus wordt e-mail alleen bezorgd bij leden van uw organisatie, dus gebruik tijdens het testen uw eigen adres.

  5. Ontvang een melding bij voltooiing

    Section titled “Ontvang een melding bij voltooiing”

    Registreer een webhook-endpoint in Instellingen › Webhooks (of met POST /v1/webhook-endpoints) en bewaar het geheim whsec_…. Wanneer de laatste ontvanger ondertekent, ontvangt u envelope.completed, met alle variabelen en ingevulde waarden in data.values. De verzegelde pdf volgt met 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 de verzegelde pdf (het document met het voltooiingscertificaat, voorzien van een tijdstempel):

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

    Volledige lijst met events, nieuwe pogingen en handmatige verificatie: Webhooks.

Live gaan

Section titled “Live gaan”

Vervang de testkey door een bf_live_-key. Live enveloppen hebben geen watermerk, e-mail gaat naar elke ontvanger en voltooide enveloppen tellen mee voor uw abonnement (Abonnementen & limieten). Alles wat een key aanmaakt, krijgt de modus van die key, de lijsten van de key tonen alleen die modus en testenveloppen sturen alleen meldingen naar webhook-endpoints in testmodus. Registreer dus ook een live endpoint.