Sessões e links de assinatura

Os destinatários assinam na página de assinatura da Bona Fide: na página hospedada em https://sign.bonafidesign.com/s/… ou na mesma página incorporada ao seu produto com <bf-signing>. Os destinatários não precisam de conta. O que dá acesso a eles é uma sessão de assinatura.

Sessões de assinatura

A entrega por e-mail cria as sessões para você (o link no e-mail). Para assinatura incorporada ou entregue por você mesmo, gere uma a partir do seu 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	Observações
`recipient`	Um destinatário do envelope que ainda pode assinar (não CC, não concluído)
`mode`	`embedded` (padrão) ou `hosted`. As `url`s hospedadas são `…/s/<token>`, para redirecionar ou enviar você mesmo
`allowedOrigins`	Até 10 origens que podem exibir a página incorporada em um frame
`returnUrl`	Para onde a página hospedada leva o signatário quando ele termina
`ttlSeconds`	De 60 a 3600, padrão 600

As sessões são de uso único: assim que o destinatário envia, a sessão é consumida, e uma sessão usada ou expirada responde 410 Gone. Gere uma nova sempre que a sua página for renderizada. As sessões só podem ser criadas enquanto o envelope está sent, e anular o envelope encerra todas elas.

O que o signatário percorre

A página de assinatura (e qualquer interface personalizada que você construa sobre a mesma API) segue estas etapas:

Troca: POST /v1/signing/exchange { "token": "bfs_…" } retorna um token de acesso de curta duração (bfa_…) mantido em memória. Nenhum cookie é usado, então o bloqueio de cookies de terceiros não faz diferença em um iframe.
Carregamento: GET /v1/signing/session retorna a visão do signatário (título do envelope, remetente, papel e campos do destinatário, valores preenchidos previamente, o aviso ao consumidor) e registra recipient.viewed na primeira vez. GET /v1/signing/document é o PDF a ser exibido.
Verificação (somente com email_otp): POST /v1/signing/otp envia por e-mail um código de seis dígitos (válido por 10 minutos) e POST /v1/signing/otp/verify o confere. Um código errado retorna verified: false com as tentativas restantes. O verification.verified da visão já é true quando o método do destinatário não exige código.
Envio: POST /v1/signing/submit com os values dos campos (assinaturas desenhadas, digitadas ou carregadas), o consentimento ao aviso e viewedDocumentHash: o SHA-256 do PDF exato que foi exibido. Se o documento tiver mudado desde então, o envio é recusado (409).
Ou recusa: POST /v1/signing/decline { "reason": "…" } encerra o envelope (envelope.declined).

Só é a vez do destinatário quando todos os grupos de roteamento anteriores terminaram; antes disso, a visão tem canSign: false, e um envio responde 409 not-your-turn.

Verificação do signatário

Cada destinatário tem um método de verification: o do papel (definido no painel de papéis do editor de modelos), a menos que o envelope o substitua por destinatário (na tela de envio ou com recipients[].verification).

Método	O que o signatário faz	Quando usar
`none` (padrão)	Abre o link de assinatura exclusivo e assina	O link é enviado por e-mail: só quem tem acesso àquela caixa de entrada o possui
`email_otp`	Abre o link e depois digita um código de seis dígitos enviado ao mesmo endereço	Você quer uma segunda prova, recente, no momento da assinatura (contratos de alto valor, caixas de entrada compartilhadas)
`integrator_asserted`	Assina no seu produto, que atesta quem ele é (`externalUserId`)	Assinatura incorporada atrás do seu próprio login

none é o padrão porque o link que a Bona Fide envia por e-mail já é exclusivo do destinatário e impossível de adivinhar: abri-lo demonstra controle do endereço de e-mail, que é a atribuição em que se baseiam as leis de assinatura eletrônica (ESIGN / UETA nos EUA, assinaturas eletrônicas simples no eIDAS). Produtos comparáveis também usam esse padrão. Modelos publicados com email_otp o mantêm, e um email_otp explícito continua funcionando em todos os lugares.

Dois fluxos nunca dependem só de um link:

Links de assinatura permanentes (/l/…): o visitante digita o próprio endereço, então sempre confirma um código enviado por e-mail antes que um envelope seja criado, independentemente do que diz o modelo.
Sessões que você gera (POST /v1/envelopes/{id}/sessions) não trazem nenhuma prova do endereço de e-mail: essa é a função do seu login, então use integrator_asserted (com externalUserId) ou email_otp nelas.

O certificado de conclusão registra, por signatário, o que foi de fato usado:

Registrado como	Quando
Link por e-mail (link exclusivo enviado para endereço)	`none`, assinado a partir do link enviado por e-mail
Link por e-mail + código de uso único (enviado para endereço)	`email_otp`, assinado a partir do link enviado por e-mail
Link de assinatura + código de uso único (enviado para endereço)	Um visitante de link permanente
Código de uso único (enviado para endereço)	`email_otp` em uma sessão que você gerou
Sessão de assinatura emitida pelo remetente	`none` em uma sessão que você gerou
Declaração do integrador	`integrator_asserted`

O resumo público de verificação mostra os mesmos rótulos, sem o endereço.

Idiomas

A página de assinatura, os e-mails dela (solicitação, lembretes, códigos, concluído, anulado), a página do link permanente e a página de status do observador estão disponíveis em 50 idiomas. O signatário os vê nesta ordem de preferência:

o idioma que ele escolheu no menu de idiomas da página (lembrado naquele dispositivo);
<bf-signing locale="…"> (assinatura incorporada) ou ?locale= em um link hospedado;
o locale do destinatário, definido quando o envelope é criado (recipients[].locale, ou locale no envelope para todos que não têm o seu);
o idioma do navegador dele.

Os e-mails precisam de um idioma antes que alguém abra uma página, então usam o locale do destinatário e ficam em inglês quando ele não existe. Os links permanentes enviam o e-mail com o código no idioma exibido na página do 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" }
  ]
}

Tags próximas são aceitas e armazenadas como o idioma a que correspondem (de-AT → de, es-MX → es-419, zh-TW → zh-Hant); qualquer outro valor é um erro de validação. Os avisos de consentimento traduzidos informam que vale o texto em inglês, e o signatário pode alternar para ele; o idioma em que o aviso foi lido é registrado com a assinatura (consentLocale no evento de auditoria recipient.signed).

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

Links de assinatura permanentes

Um link de assinatura é uma URL permanente para contratos que muitas pessoas assinam da mesma forma: um termo de isenção, um contrato de prestador de serviços, os termos de um piloto. Cada visitante que o conclui recebe o próprio envelope.

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 é o papel de signatário que o visitante assume. Os links aceitam um visitante e no máximo um contra-assinante: mode: "auto" contra-assina automaticamente com o selo da plataforma Bona Fide, e mode: "person" encaminha o envelope ao email informado. Qualquer outro papel que não seja CC ficaria sem destinatário, então modelos assim são recusados.
O visitante informa nome, e-mail e as variáveis do modelo e depois confirma um código enviado por e-mail antes que qualquer coisa seja criada (POST /v1/links/{id}/start e, em seguida, POST /v1/links/{id}/verify).
limits restringe o uso por e-mail por dia (padrão 3), por IP por hora (padrão 20), por dia no total e por domínio de e-mail. Com dedupe (ativado por padrão), um endereço de e-mail que já assinou recebe 409 already-signed.
PATCH /v1/signing-links/{id} pausa (active: false), retoma ou move o link para uma versão mais recente; excluir um link mantém os envelopes que ele criou. Cada uso emite signing_link.used.