Guida rapida

Questa procedura guidata porta un modello pubblicato fino a un PDF firmato e sigillato. Usa una chiave di prova, quindi nulla viene fatturato e ogni documento riporta la filigrana TEST.

Crei una chiave API
Sezione intitolata “Crei una chiave API”

Le chiavi API si creano nella dashboard, in Impostazioni › Chiavi API. Per questa procedura scelga Test: la chiave inizia con bf_test_. La chiave completa viene mostrata una sola volta; la salvi in una variabile d’ambiente.
Finestra del terminale
```
export BONA_FIDE_API_KEY=bf_test_…
```
Ogni richiesta la invia come Authorization: Bearer … (o x-api-key: …). Veda Autenticazione.
Trovi il Suo modello
Sezione intitolata “Trovi il Suo modello”

I modelli si progettano nella dashboard (caricando un PDF o un documento Word e posizionando i campi, oppure scrivendoli in modalità Documento) e poi si pubblicano. Li elenchi per ottenere l’id:
Finestra del terminale
curl https://api.bonafidesign.com/v1/templates \ -H "Authorization: Bearer $BONA_FIDE_API_KEY"
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, … }]
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 restituisce i roles e i fields della versione e il JSON Schema delle sue variables. La pagina del modello nella dashboard ha anche un pannello Usa nell’API con una richiesta già pronta per quella versione specifica.

Crei una busta

POST /v1/envelopes compone il modello con le Sue variabili, fissa la versione e avvia l’instradamento. Indichi un destinatario per ruolo (i ruoli in CC sono facoltativi). Invii una Idempotency-Key, così un nuovo tentativo non può inviare la busta due volte.

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

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_…', … }] }

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 risposta è 201 Created con la busta:

{
  "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 stabilisce come vengono raggiunti i destinatari: con email (il valore predefinito) ogni destinatario riceve via e-mail un link di firma quando è il suo turno; con embedded e none non viene inviata alcuna e-mail e le sessioni di firma le apre Lei (passo successivo).

Faccia firmare il destinatario
Sezione intitolata “Faccia firmare il destinatario”

Crei dal Suo backend una sessione di firma per il destinatario. Le sessioni hanno una breve durata (ttlSeconds, da 60 a 3600, predefinito 600) e sono monouso.
- Integrata
- Ospitata
Finestra del terminale
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"] }'
Passi alla Sua pagina il token restituito (bfs_…) e visualizzi il 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>
Wrapper React e Vue, eventi e modello di sicurezza: Firma integrata.
Finestra del terminale
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" }'
Reindirizzi il firmatario all’url restituito (https://sign.bonafidesign.com/s/bfs_…). La pagina ospitata è pensata prima di tutto per i dispositivi mobili e non richiede un account.
Con la verifica predefinita email_otp, prima di inviare il firmatario conferma un codice di sei cifre ricevuto via e-mail. In modalità di prova le e-mail vengono recapitate solo ai membri della Sua organizzazione, quindi durante i test usi il Suo indirizzo.

Riceva una notifica al completamento

Registri un endpoint webhook in Impostazioni › Webhook (o con POST /v1/webhook-endpoints) e conservi il segreto whsec_…. Quando l’ultimo destinatario firma, riceve envelope.completed, con tutte le variabili e tutti i valori inseriti in data.values. Il PDF sigillato segue con 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);
});

Scarichi il PDF sigillato (il documento con il suo certificato di completamento, con marca temporale):

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

Elenco completo degli eventi, nuovi tentativi e verifica manuale: Webhook.

Passaggio in produzione

Sostituisca la chiave di prova con una chiave bf_live_. Le buste di produzione non hanno filigrana, le e-mail raggiungono qualsiasi destinatario e le buste completate vengono conteggiate nel Suo piano (Piani e limiti). Tutto ciò che una chiave crea assume la sua modalità, i suoi elenchi mostrano solo quella modalità e le buste di prova notificano solo gli endpoint webhook in modalità di prova: registri quindi anche un endpoint di produzione.

Guida rapida

Crei una chiave API

Trovi il Suo modello

Crei una busta

Faccia firmare il destinatario

Riceva una notifica al completamento

Passaggio in produzione