Início rápido

Este guia passo a passo leva um modelo publicado até um PDF assinado e selado. Utiliza uma chave de teste, pelo que nada é faturado e todos os documentos recebem a marca de água TEST.

1. Crie uma chave de API

   As chaves de API são criadas no painel, em Definições › Chaves de API. Escolha Teste para este guia: a chave começa por bf_test_. A chave completa só é mostrada uma vez; guarde-a numa variável de ambiente.

   export BONA_FIDE_API_KEY=bf_test_…

   Todos os pedidos a enviam como Authorization: Bearer … (ou x-api-key: …). Consulte Autenticação.

2. Encontre o seu modelo

   Os modelos são concebidos no painel (carregue um PDF ou um documento do Word e coloque os campos, ou redija-o no modo Documento) e depois publicados. Liste-os para obter o id:

   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 devolve os roles e os fields da versão e o JSON Schema das respetivas variables. A página do modelo no painel tem também um painel Utilizar na API com um pedido pronto para essa versão exata.

3. Crie um envelope

   POST /v1/envelopes gera o documento a partir do modelo com as suas variáveis, fixa a versão e inicia o encaminhamento. Indique um destinatário por função (as funções CC são opcionais). Envie um Idempotency-Key para que uma repetição não envie o envelope duas vezes.

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

   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
   }

   Experimente sem enviar

   Acrescente ?dry_run=true para validar as variáveis e os destinatários e gerar o documento sem guardar, enviar ou faturar nada. A resposta (200) inclui o documentHash gerado e o número de páginas.

   delivery determina como os destinatários são contactados: email (a predefinição) envia a cada destinatário uma ligação de assinatura por e-mail quando chega a sua vez; embedded e none não enviam e-mails, e as sessões de assinatura são abertas por si (passo seguinte).

4. Deixe o destinatário assinar

   Crie uma sessão de assinatura para o destinatário a partir do seu backend. As sessões são de curta duração (ttlSeconds, de 60 a 3600, predefinição 600) e de utilização única.

   Integrada

   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 devolvido (bfs_…) à sua página e apresente 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 modelo de segurança: Assinatura integrada.

   Alojada

   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 o url devolvido (https://sign.bonafidesign.com/s/bfs_…). A página alojada foi concebida primeiro para dispositivos móveis e não exige conta.

   Com a verificação predefinida email_otp, o signatário confirma um código de seis dígitos enviado para o seu e-mail antes de submeter. No modo de teste, os e-mails só são entregues a membros da sua organização, por isso utilize o seu próprio endereço durante os testes.

5. Receba uma notificação na conclusão

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

   Transfira o PDF selado (o documento com o respetivo certificado de conclusão, com carimbo temporal):

   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, repetições e verificação manual: Webhooks.

Passar para produção

Substitua a chave de teste por uma chave bf_live_. Os envelopes de produção não têm marca de água, os e-mails são enviados a 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 dessa chave, as listas só mostram esse modo e os envelopes de teste só notificam endpoints de webhook do modo de teste, por isso registe também um endpoint de produção.