Démarrage rapide

Ce tutoriel mène d’un modèle publié à un PDF signé et scellé. Il utilise une clé de test : rien n’est facturé et chaque document porte le filigrane TEST.

1. Créer une clé API

   Les clés API se créent dans le tableau de bord, sous Paramètres › Clés API. Choisissez Test pour ce tutoriel : la clé commence par bf_test_. La clé complète n’est affichée qu’une seule fois ; enregistrez-la dans une variable d’environnement.

   export BONA_FIDE_API_KEY=bf_test_…

   Chaque requête l’envoie sous la forme Authorization: Bearer … (ou x-api-key: …). Consultez Authentification.

2. Trouver votre modèle

   Les modèles se conçoivent dans le tableau de bord (importez un PDF ou un document Word et placez-y des champs, ou rédigez le contrat en mode Document), puis se publient. Listez-les pour obtenir leur identifiant :

   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 renvoie les roles et les fields de la version, ainsi que le JSON Schema de ses variables. La page du modèle dans le tableau de bord comporte aussi un panneau Utiliser dans l’API avec une requête prête à l’emploi pour cette version précise.

3. Créer une enveloppe

   POST /v1/envelopes génère le document à partir du modèle et de vos variables, fige la version et lance l’acheminement. Indiquez un destinataire par rôle (les rôles en copie sont facultatifs). Envoyez un Idempotency-Key pour qu’une nouvelle tentative ne déclenche pas un second envoi.

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

   La réponse est un 201 Created contenant l’enveloppe :

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

   Essayer sans envoyer

   Ajoutez ?dry_run=true pour valider les variables et les destinataires et générer le document sans rien enregistrer, envoyer ni facturer. La réponse (200) contient le documentHash du document généré et son nombre de pages.

   delivery détermine la manière de joindre les destinataires : avec email (valeur par défaut), chaque destinataire reçoit un lien de signature par e-mail quand vient son tour ; embedded et none n’envoient aucun e-mail, et c’est vous qui ouvrez les sessions de signature (étape suivante).

4. Faire signer le destinataire

   Créez une session de signature pour le destinataire depuis votre backend. Les sessions sont éphémères (ttlSeconds, de 60 à 3600, 600 par défaut) et à usage unique.

   Intégrée

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

   Transmettez le token renvoyé (bfs_…) à votre page et affichez le web component :

   <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 React et Vue, événements et modèle de sécurité : Signature intégrée.

   Hébergée

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

   Redirigez le signataire vers l’url renvoyée (https://sign.bonafidesign.com/s/bfs_…). La page hébergée est conçue d’abord pour le mobile et ne nécessite aucun compte.

   Avec la vérification par défaut email_otp, le signataire confirme, avant de valider, un code à six chiffres envoyé à son adresse e-mail. En mode test, les e-mails ne sont remis qu’aux membres de votre organisation : utilisez donc votre propre adresse pendant vos tests.

5. Être notifié de la finalisation

   Enregistrez un endpoint de webhook dans Paramètres › Webhooks (ou avec POST /v1/webhook-endpoints) et conservez le secret whsec_…. Quand le dernier destinataire a signé, vous recevez envelope.completed, avec toutes les variables et valeurs saisies dans data.values. Le PDF scellé suit avec 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);
   });

   Téléchargez le PDF scellé (le document avec son certificat de finalisation, horodaté) :

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

   Liste complète des événements, nouvelles tentatives et vérification manuelle : Webhooks.

Passer en production

Remplacez la clé de test par une clé bf_live_. Les enveloppes en production ne portent pas de filigrane, les e-mails sont envoyés à tous les destinataires et les enveloppes finalisées sont décomptées de votre forfait (Forfaits et limites). Tout ce qu’une clé crée prend son mode, ses listes n’affichent que ce mode, et les enveloppes de test ne notifient que les endpoints de webhook en mode test : enregistrez donc aussi un endpoint de production.