Início rápido

Este passo a passo leva um modelo publicado até um PDF assinado e selado. Ele usa uma chave de teste, então nada é cobrado e todo documento recebe a marca d’água TEST.

Crie uma chave de API
Seção intitulada “Crie uma chave de API”

As chaves de API são criadas no painel, em Configurações › Chaves de API. Escolha Teste para este passo a passo: a chave começa com bf_test_. A chave completa é exibida uma única vez; guarde-a em uma variável de ambiente.
Janela do terminal
```
export BONA_FIDE_API_KEY=bf_test_…
```
Toda requisição a envia como Authorization: Bearer … (ou x-api-key: …). Consulte Autenticação.
Encontre seu modelo
Seção intitulada “Encontre seu modelo”

Os modelos são criados no painel (envie um PDF ou documento do Word e posicione os campos, ou escreva no modo Documento) e depois publicados. Liste-os para obter o id:
Janela do terminal
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 retorna os roles e os fields da versão e o JSON Schema das suas variables. A página do modelo no painel também tem um painel Usar na API com uma requisição pronta para essa versão exata.

Crie um envelope

POST /v1/envelopes renderiza o modelo com suas variáveis, fixa a versão e inicia o roteamento. Informe um destinatário por papel (papéis CC são opcionais). Envie um Idempotency-Key para que uma nova tentativa não envie duas vezes.

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

A resposta é 201 Created com o envelope:

{
  "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 define como os destinatários são alcançados: email (o padrão) envia a cada destinatário um link de assinatura por e-mail quando chega a vez dele; embedded e none não enviam e-mail, e você mesmo abre as sessões de assinatura (próximo passo).

Deixe o destinatário assinar
Seção intitulada “Deixe o destinatário assinar”

Gere uma sessão de assinatura para o destinatário a partir do seu backend. As sessões têm curta duração (ttlSeconds, de 60 a 3600, padrão 600) e são de uso único.
- Incorporada
- Hospedada
Janela do terminal
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"] }'
Passe o token retornado (bfs_…) para a sua página e renderize o 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 para React e Vue, eventos e o modelo de segurança: Assinatura incorporada.
Janela do terminal
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" }'
Redirecione o signatário para a url retornada (https://sign.bonafidesign.com/s/bfs_…). A página hospedada é pensada primeiro para celular e não exige conta.
Com a verificação padrão email_otp, o signatário confirma um código de seis dígitos enviado para o e-mail dele antes de enviar. No modo de teste, os e-mails só são entregues a membros da sua organização, então use o seu próprio endereço durante os testes.

Seja notificado da conclusão

Cadastre um endpoint de webhook em Configurações › Webhooks (ou com POST /v1/webhook-endpoints) e guarde o segredo whsec_…. Quando o último destinatário assina, você recebe envelope.completed, com todas as variáveis e valores preenchidos em data.values. O PDF selado vem depois, com 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);
});

Baixe o PDF selado (o documento com o certificado de conclusão, com carimbo de tempo):

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

Lista completa de eventos, novas tentativas e verificação manual: Webhooks.

Entrando em produção

Troque a chave de teste por uma chave bf_live_. Envelopes de produção não têm marca d’água, os e-mails vão para qualquer destinatário e os envelopes concluídos contam para o seu plano (Planos e limites). Tudo o que uma chave cria assume o modo dela, as listagens só mostram esse modo e os envelopes de teste só notificam endpoints de webhook do modo de teste, então cadastre também um endpoint de produção.

Início rápido

Crie uma chave de API

Encontre seu modelo

Crie um envelope

Deixe o destinatário assinar

Seja notificado da conclusão

Entrando em produção