Démarrage rapide

Ce tutoriel vous 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é d’API

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

   export BONA_FIDE_API_KEY=bf_test_…

   Chaque requête l’envoie dans l’en-tête Authorization: Bearer … (ou x-api-key: …). Consultez Authentification.

2. Trouver votre modèle

   Les modèles se conçoivent dans le tableau de bord (téléversez un PDF ou un document Word et placez-y des champs, ou rédigez-le 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 toute prête 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, fixe la version et lance l’acheminement. Indiquez un destinataire par rôle (les rôles CC sont facultatifs). Envoyez une Idempotency-Key pour qu’une nouvelle tentative ne puisse pas provoquer un double 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 rendu et le nombre de pages.

   delivery détermine comment les destinataires sont joints : avec email (la valeur par défaut), chaque destinataire reçoit un lien de signature par courriel quand vient son tour; avec embedded et none, aucun courriel n’est envoyé 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 à partir de votre back-end. 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 composant Web :

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

   Adaptateurs 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 demande aucun compte.

   Avec la vérification email_otp par défaut, le signataire confirme un code à six chiffres envoyé à son adresse courriel avant de soumettre. En mode test, les courriels ne sont livrés qu’aux membres de votre organisation : utilisez donc votre propre adresse pendant vos essais.

5. Être averti de la finalisation

   Enregistrez un point de terminaison 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 les 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 accompagné de 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 courriels sont envoyés à tous les destinataires et les enveloppes finalisées sont comptabilisées dans 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 n’avertissent que les points de terminaison de webhook en mode test : enregistrez donc aussi un point de terminaison en production.