Inicio rápido

Este recorrido lleva una plantilla publicada hasta un PDF firmado y sellado. Usa una clave de prueba, así que no se factura nada y cada documento lleva la marca de agua TEST.

1. Cree una clave de API

   Las claves de API se crean en el panel, en Configuración › Claves de API. Elija Prueba para este recorrido: la clave comienza con bf_test_. La clave completa se muestra una sola vez; guárdela como variable de entorno.

   export BONA_FIDE_API_KEY=bf_test_…

   Cada solicitud la envía como Authorization: Bearer … (o x-api-key: …). Consulte Autenticación.

2. Busque su plantilla

   Las plantillas se diseñan en el panel (suba un PDF o un documento de Word y coloque campos, o redáctela en el modo Documento) y luego se publican. Enumérelas para obtener el 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 devuelve los roles y los fields de la versión, y el JSON Schema de sus variables. La página de la plantilla en el panel también tiene un panel Usar en la API con una solicitud lista para usar con esa versión exacta.

3. Cree un sobre

   POST /v1/envelopes genera la plantilla con sus variables, fija la versión y comienza el enrutamiento. Indique un destinatario por rol (los roles CC son opcionales). Envíe una Idempotency-Key para que un reintento no pueda enviar el sobre dos veces.

   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 respuesta es 201 Created con el sobre:

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

   Pruébelo sin enviar

   Agregue ?dry_run=true para validar las variables y los destinatarios y generar el documento sin almacenar, enviar ni facturar nada. La respuesta (200) incluye el documentHash generado y la cantidad de páginas.

   delivery determina cómo se contacta a los destinatarios: email (el valor predeterminado) envía a cada destinatario un enlace de firma por correo electrónico cuando es su turno; embedded y none no envían ningún correo, y usted mismo abre las sesiones de firma (siguiente paso).

4. Permita que el destinatario firme

   Genere una sesión de firma para el destinatario desde su backend. Las sesiones son de corta duración (ttlSeconds, de 60 a 3600, 600 de forma predeterminada) y de un solo uso.

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

   Pase el token devuelto (bfs_…) a su página y renderice el componente 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>

   Wrappers para React y Vue, eventos y modelo de seguridad: Firma 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" }'

   Redirija al firmante a la url devuelta (https://sign.bonafidesign.com/s/bfs_…). La página alojada está diseñada primero para dispositivos móviles y no requiere una cuenta.

   Con la verificación predeterminada email_otp, el firmante confirma un código de seis dígitos enviado a su correo electrónico antes de enviar. En modo de prueba, los correos electrónicos solo se entregan a los miembros de su organización, así que use su propia dirección mientras hace pruebas.

5. Reciba una notificación al completarse

   Registre un endpoint de webhook en Configuración › Webhooks (o con POST /v1/webhook-endpoints) y guarde el secreto whsec_…. Cuando firma el último destinatario, usted recibe envelope.completed, con cada variable y cada valor ingresado en data.values. El PDF sellado llega después 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);
   });

   Descargue el PDF sellado (el documento con su certificado de finalización y con sello de tiempo):

   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, reintentos y verificación manual: Webhooks.

Pasar a producción

Reemplace la clave de prueba por una clave bf_live_. Los sobres de producción no llevan marca de agua, los correos electrónicos llegan a cualquier destinatario y los sobres completados cuentan para su plan (Planes y límites). Todo lo que crea una clave adopta su modo, sus listas solo muestran ese modo y los sobres de prueba solo notifican a los endpoints de webhook en modo de prueba, así que registre también un endpoint de producción.