Sesiones y enlaces de firma

Los destinatarios firman en la página de firma de Bona Fide: ya sea en la página alojada en https://sign.bonafidesign.com/s/…, o 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 entregada por 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 todavía puede firmar (no CC, sin terminar)
`mode`	`embedded` (predeterminado) o `hosted`. Las `url` alojadas tienen el formato `…/s/<token>`, para redirigir a ellas o enviarlas usted mismo
`allowedOrigins`	Hasta 10 orígenes que pueden incrustar 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 de forma predeterminada

Las sesiones son de un solo uso: cuando el destinatario envía, la sesión queda consumida, y una sesión usada o vencida 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 estado sent, y anular el sobre las finaliza todas.

Los pasos que sigue el firmante

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

Intercambio: POST /v1/signing/exchange { "token": "bfs_…" } devuelve un token de acceso de corta duración (bfa_…) que se mantiene en memoria. No se usan cookies, así que el bloqueo de cookies de terceros no afecta dentro de un iframe.
Carga: GET /v1/signing/session devuelve la vista del firmante (título del sobre, remitente, rol y campos del destinatario, valores prellenados, la divulgación al consumidor) y registra recipient.viewed la primera vez. GET /v1/signing/document es el PDF que se debe mostrar.
Verificación (solo con email_otp): POST /v1/signing/otp envía por correo un código de seis dígitos (válido 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.
Envío: POST /v1/signing/submit con los values de los campos (firmas dibujadas, escritas o subidas), el consentimiento a la divulgación y viewedDocumentHash: el SHA-256 del PDF exacto que se mostró. Si el documento cambió desde entonces, el envío se rechaza (409).
O rechazo: POST /v1/signing/decline { "reason": "…" } finaliza el sobre (envelope.declined).

Es el turno del destinatario solo cuando terminaron todos los grupos de enrutamiento anteriores; antes de eso, 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), a menos que el sobre lo reemplace para ese destinatario (en la pantalla de envío o con recipients[].verification).

Método	Lo que hace el firmante	Úselo cuando
`none` (predeterminado)	Abre el enlace de firma único y firma	El enlace se le envía por correo: solo alguien con acceso a esa bandeja de entrada lo tiene
`email_otp`	Abre el enlace y luego ingresa un código de seis dígitos enviado por correo a la misma dirección	Quiere una segunda prueba, reciente, en el momento de la firma (contratos de alto valor, bandejas de entrada compartidas)
`integrator_asserted`	Firma en su producto, que da fe de su identidad (`externalUserId`)	Firma integrada detrás de su propio inicio de sesión

none es el valor predeterminado porque el enlace que Bona Fide envía 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 comparables también lo usan de forma predeterminada. Las plantillas publicadas con email_otp lo conservan, y un email_otp explícito sigue funcionando en todas partes.

Hay dos flujos que nunca dependen solo de un enlace:

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

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

Se registra como	Cuándo
Enlace por correo (enlace único enviado a dirección)	`none`, firmado desde el enlace enviado por correo
Enlace por correo + código de un solo uso (enviado a dirección)	`email_otp`, firmado desde el enlace enviado 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 que usted generó
Sesión de firma emitida por el remitente	`none` en una sesión que usted generó
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. Un firmante los ve en este orden de preferencia:

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

Los correos necesitan un idioma antes de que alguien abra una página, así que usan el locale del destinatario y se envían en inglés si no lo tiene. Los enlaces permanentes envían el correo con el 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 cercanas se aceptan y se almacenan 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. Las divulgaciones de consentimiento traducidas indican que se aplica el texto en inglés, y el firmante puede cambiar a ese texto; el idioma en el que se leyó la divulgación 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 muchas personas firman de la misma manera: una exención de responsabilidad, un contrato de contratista, 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 asume 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" envía el sobre al email indicado. Cualquier otro rol que no sea CC quedaría sin destinatario, así que esas plantillas se rechazan.
El visitante ingresa su nombre, su correo electrónico y las variables de la plantilla, y luego confirma un código enviado por correo antes de que se cree nada (POST /v1/links/{id}/start y luego POST /v1/links/{id}/verify).
limits limita el uso por correo electrónico por día (3 de forma predeterminada), por IP por hora (20 de forma predeterminada), por día en total y por dominio de correo. Con dedupe (activado de forma predeterminada), una dirección de correo que ya firmó 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; eliminar un enlace conserva los sobres que creó. Cada uso emite signing_link.used.