Sesiones y enlaces de firma

Los destinatarios firman en la página de firma de Bona Fide: bien en la página alojada en https://sign.bonafidesign.com/s/…, bien en esa misma página integrada en su producto con <bf-signing>. Los destinatarios no necesitan una cuenta. Lo que les da acceso es una sesión de firma.

Sesiones de firma

La entrega por correo electrónico crea las sesiones por usted (el enlace del correo). Para la firma integrada o para entregar los enlaces usted mismo, genere una desde su backend:

curl https://api.bonafidesign.com/v1/envelopes/env_8Gm2kQ4rT1/sessions \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "recipient": "rcp_5Jw0pLs9Xe", "mode": "embedded", "allowedOrigins": ["https://app.example.com"], "ttlSeconds": 600 }'

{
  "id": "ses_2Hq8vNw3Kd",
  "token": "bfs_…",
  "url": "https://sign.bonafidesign.com/s/?embed=1#session=bfs_…",
  "expiresAt": "2026-10-13T14:08:04.512Z"
}

Campo	Notas
recipient	Un destinatario del sobre que aún puede firmar (que no sea CC ni haya terminado)
mode	embedded (predeterminado) o hosted. Las url alojadas tienen la forma …/s/<token>, para redirigir a ellas o enviarlas usted mismo
allowedOrigins	Hasta 10 orígenes que pueden insertar la página integrada en un marco
returnUrl	Adónde envía la página alojada al firmante cuando termina
ttlSeconds	De 60 a 3600; 600 por defecto

Las sesiones son de un solo uso: en cuanto el destinatario envía, la sesión queda consumida, y una sesión usada o caducada responde 410 Gone. Genere una nueva cada vez que se renderice su página. Las sesiones solo se pueden crear mientras el sobre está en sent, y al anular el sobre se cierran todas.

El proceso que sigue el firmante

La página de firma (y cualquier interfaz propia que cree sobre la misma API) sigue estos pasos:

1. Canje: POST /v1/signing/exchange { "token": "bfs_…" } devuelve un token de acceso de corta duración (bfa_…) que se guarda en memoria. No intervienen cookies, de modo que el bloqueo de cookies de terceros no afecta dentro de un iframe.
2. Carga: GET /v1/signing/session devuelve la vista del firmante (título del sobre, remitente, rol y campos del destinatario, valores rellenados previamente, aviso al consumidor) y registra recipient.viewed la primera vez. GET /v1/signing/document es el PDF que se debe mostrar.
3. Verificación (solo con email_otp): POST /v1/signing/otp envía por correo un código de seis dígitos (válido durante 10 minutos) y POST /v1/signing/otp/verify lo comprueba. Un código incorrecto devuelve verified: false con los intentos restantes. El valor verification.verified de la vista ya es true cuando el método del destinatario no requiere código.
4. Envío: POST /v1/signing/submit con los values de los campos (firmas dibujadas, escritas o subidas), la aceptación del aviso y viewedDocumentHash: el SHA-256 del PDF exacto que se ha mostrado. Si el documento ha cambiado desde entonces, el envío se rechaza (409).
5. O rechazo: POST /v1/signing/decline { "reason": "…" } pone fin al sobre (envelope.declined).

Al destinatario solo le toca cuando han terminado todos los grupos de enrutamiento anteriores; hasta entonces, la vista tiene canSign: false y un envío responde 409 not-your-turn.

Verificación del firmante

Cada destinatario tiene un método de verification: el de su rol (definido en el panel de roles del diseñador de plantillas), salvo que el sobre lo sustituya para ese destinatario (en la pantalla de envío o con recipients[].verification).

Método	Qué hace el firmante	Cuándo utilizarlo
none (predeterminado)	Abre el enlace de firma único y firma	Cuando el enlace se le envía por correo: solo lo tiene quien tenga acceso a ese buzón
email_otp	Abre el enlace y, a continuación, introduce un código de seis dígitos enviado por correo a la misma dirección	Cuando quiere una segunda prueba, reciente, en el momento de la firma (contratos de gran valor, buzones compartidos)
integrator_asserted	Firma en su producto, que responde de su identidad (externalUserId)	Firma integrada tras su propio inicio de sesión

none es el valor predeterminado porque el enlace que envía Bona Fide por correo es único para el destinatario e imposible de adivinar: abrirlo demuestra el control de la dirección de correo electrónico, que es la atribución en la que se basan las leyes de firma electrónica (ESIGN / UETA en EE. UU., firma electrónica simple según eIDAS). Los productos similares también lo usan por defecto. Las plantillas publicadas con email_otp lo conservan, y un email_otp explícito sigue funcionando en todos los casos.

Hay dos flujos que nunca se basan solo en un enlace:

• Enlaces de firma permanentes (/l/…): el visitante escribe su propia dirección, por lo que siempre confirma un código enviado por correo antes de que se cree un sobre, diga lo que diga la plantilla.
• Sesiones que genera usted (POST /v1/envelopes/{id}/sessions): no incluyen ninguna prueba de la dirección de correo; eso corresponde a su propio inicio de sesión, así que utilice integrator_asserted (con externalUserId) o email_otp para ellas.

El certificado de finalización registra, para cada firmante, lo que se ha utilizado realmente:

Se registra como	Cuándo
Enlace por correo (enlace único enviado a dirección)	none, firmado desde el enlace recibido por correo
Enlace por correo + código de un solo uso (enviado a dirección)	email_otp, firmado desde el enlace recibido por correo
Enlace de firma + código de un solo uso (enviado a dirección)	Un visitante de un enlace permanente
Código de un solo uso (enviado a dirección)	email_otp en una sesión generada por usted
Sesión de firma emitida por el remitente	none en una sesión generada por usted
Declaración del integrador	integrator_asserted

El resumen público de verificación muestra las mismas etiquetas, sin la dirección.

Idiomas

La página de firma, sus correos (solicitud, recordatorios, códigos, completado, anulado), la página del enlace permanente y la página de estado del observador están disponibles en 50 idiomas. El firmante los ve según este orden de preferencia:

1. el idioma que haya elegido en el menú de idiomas de la página (que se recuerda en ese dispositivo);
2. <bf-signing locale="…"> (firma integrada) o ?locale= en un enlace alojado;
3. el locale del destinatario, establecido al crear el sobre (recipients[].locale, o locale en el sobre para todos los que no tengan uno propio);
4. el idioma de su navegador.

Los correos necesitan un idioma antes de que nadie abra una página, por lo que utilizan el locale del destinatario y, si no lo hay, se envían en inglés. Los enlaces permanentes envían el correo del código en el idioma que muestra la página del visitante.

{
  "template": "tpl_…",
  "locale": "es-419",
  "recipients": [
    { "role": "client", "name": "Ana Souza", "email": "ana@example.com", "locale": "pt-BR" },
    { "role": "company", "name": "Lee Park", "email": "lee@example.com" }
  ]
}

Las etiquetas próximas se aceptan y se guardan como el idioma al que corresponden (de-AT → de, es-MX → es-419, zh-TW → zh-Hant); cualquier otra es un error de validación. Los avisos de consentimiento traducidos indican que se aplica el texto en inglés, y el firmante puede cambiar a él; el idioma en el que se ha leído el aviso se registra con la firma (consentLocale en el evento de auditoría recipient.signed).

Código	Idioma	Nombre nativo
ar	Árabe	العربية	de derecha a izquierda
hy	Armenio	Հայերեն
bn	Bengalí	বাংলা
bg	Búlgaro	Български
zh-Hans	Chino (simplificado)	简体中文
zh-Hant	Chino (tradicional)	繁體中文
hr	Croata	Hrvatski
cs	Checo	Čeština
da	Danés	Dansk
nl	Neerlandés	Nederlands
en-GB	Inglés (Reino Unido)	English (UK)
en-US	Inglés (EE. UU.)	English (US)
et	Estonio	Eesti
fil	Filipino	Filipino
fi	Finés	Suomi
fr	Francés	Français
fr-CA	Francés (Canadá)	Français (Canada)
de	Alemán	Deutsch
el	Griego	Ελληνικά
he	Hebreo	עברית	de derecha a izquierda
hi	Hindi	हिन्दी
hu	Húngaro	Magyar
id	Indonesio	Bahasa Indonesia
it	Italiano	Italiano
ja	Japonés	日本語
ko	Coreano	한국어
lv	Letón	Latviešu
lt	Lituano	Lietuvių
ms	Malayo	Bahasa Melayu
mr	Maratí	मराठी
nb	Noruego	Norsk bokmål
fa	Persa (farsi)	فارسی	de derecha a izquierda
pl	Polaco	Polski
pt-BR	Portugués (Brasil)	Português (Brasil)
pt-PT	Portugués (Portugal)	Português (Portugal)
ro	Rumano	Română
ru	Ruso	Русский
sr-Latn	Serbio (latino)	Srpski
sk	Eslovaco	Slovenčina
sl	Esloveno	Slovenščina
es-419	Español (Latinoamérica)	Español (Latinoamérica)
es-ES	Español (España)	Español (España)
sw	Suajili	Kiswahili
sv	Sueco	Svenska
te	Telugu	తెలుగు
th	Tailandés	ไทย
tr	Turco	Türkçe
uk	Ucraniano	Українська
ur	Urdu	اردو	de derecha a izquierda
vi	Vietnamita	Tiếng Việt

Enlaces de firma permanentes

Un enlace de firma es una URL permanente para contratos que firman muchas personas de la misma forma: un descargo de responsabilidad, un contrato de colaborador externo, las condiciones de un piloto. Cada visitante que lo completa obtiene su propio sobre.

curl https://api.bonafidesign.com/v1/signing-links \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "tpl_…",
    "visitorRole": "contractor",
    "countersign": { "role": "company", "mode": "auto" },
    "limits": { "perEmailPerDay": 3, "perIpPerHour": 20, "dailyCap": 200, "allowedEmailDomains": ["example.com"] }
  }'

• visitorRole es el rol de firmante que adopta el visitante. Los enlaces admiten un visitante y, como máximo, un contrafirmante: mode: "auto" contrafirma automáticamente con el sello de la plataforma Bona Fide, y mode: "person" dirige el sobre al email indicado. Cualquier otro rol que no sea CC se quedaría sin destinatario, por lo que esas plantillas se rechazan.
• El visitante introduce su nombre, su correo electrónico y las variables de la plantilla y, a continuación, confirma un código enviado por correo antes de que se cree nada (POST /v1/links/{id}/start y, después, POST /v1/links/{id}/verify).
• limits limita el uso por correo electrónico y día (3 por defecto), por IP y hora (20 por defecto), por día en total y por dominio de correo. Con dedupe (activado por defecto), una dirección de correo que ya ha firmado recibe 409 already-signed.
• PATCH /v1/signing-links/{id} pausa (active: false) o reanuda el enlace, o lo pasa a una versión más reciente; al eliminar un enlace se conservan los sobres que ha creado. Cada uso emite signing_link.used.

Nota

La página del visitante se encuentra en la url del enlace (https://sign.bonafidesign.com/l/lnk_…). GET /v1/links/{id} es la descripción pública que muestra: el nombre de la plantilla, los campos del visitante y las variables que rellena.