Pular para o conteúdo
bona fidedocs

Sessões e ligações de assinatura

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

Sessões de assinatura

Seção intitulada “Sessões de assinatura”

A entrega por e-mail cria as sessões automaticamente (a ligação no e-mail). Para assinatura integrada ou entregue por si, crie uma a partir do seu backend:

Janela do terminal
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 Um destinatário do envelope que ainda possa assinar (não CC, não concluído)
mode embedded (predefinição) ou hosted. Os url alojados são …/s/<token>, para redirecionar ou enviar por si
allowedOrigins Até 10 origens que podem apresentar a página integrada numa moldura
returnUrl Para onde a página alojada encaminha o signatário quando termina
ttlSeconds De 60 a 3600, predefinição 600

As sessões são de utilização única: assim que o destinatário submete, a sessão fica gasta, e uma sessão utilizada ou expirada responde 410 Gone. Crie uma nova sempre que a sua página for apresentada. As sessões só podem ser criadas enquanto o envelope está sent, e anular o envelope termina todas elas.

O que o signatário percorre

Seção intitulada “O que o signatário percorre”

A página de assinatura (e qualquer interface personalizada que construa sobre a mesma API) segue estes passos:

  1. Troca: POST /v1/signing/exchange { "token": "bfs_…" } devolve um token de acesso de curta duração (bfa_…) mantido em memória. Não são utilizados cookies, pelo que o bloqueio de cookies de terceiros não tem qualquer efeito num iframe.
  2. Carregamento: GET /v1/signing/session devolve a vista do signatário (título do envelope, remetente, a função e os campos do destinatário, valores pré-preenchidos, o aviso ao consumidor) e regista recipient.viewed na primeira vez. GET /v1/signing/document é o PDF a apresentar.
  3. Verificação (apenas com email_otp): POST /v1/signing/otp envia por e-mail um código de seis dígitos (válido durante 10 minutos) e POST /v1/signing/otp/verify verifica-o. Um código errado devolve verified: false com as tentativas restantes. O verification.verified da vista já é true quando o método do destinatário não exige código.
  4. Submissão: POST /v1/signing/submit com os values dos campos (assinaturas desenhadas, escritas ou carregadas), o consentimento ao aviso e viewedDocumentHash: o SHA-256 do PDF exato que foi mostrado. Se o documento tiver mudado entretanto, a submissão é recusada (409).
  5. Ou recusa: POST /v1/signing/decline { "reason": "…" } termina o envelope (envelope.declined).

Só é a vez do destinatário quando todos os grupos de encaminhamento anteriores terminaram; até lá, a vista tem canSign: false e uma submissão responde 409 not-your-turn.

Verificação do signatário

Seção intitulada “Verificação do signatário”

Cada destinatário tem um método de verification: o da função (definido no painel de funções do editor de modelos), a menos que o envelope o substitua por destinatário (no ecrã de envio ou com recipients[].verification).

Método O que o signatário faz Quando utilizar
none (predefinição) Abre a ligação de assinatura única e assina A ligação é-lhe enviada por e-mail: só quem tem acesso a essa caixa de correio a possui
email_otp Abre a ligação e depois introduz um código de seis dígitos enviado para o mesmo endereço Pretende uma segunda prova, recente, no momento da assinatura (contratos de valor elevado, caixas de correio partilhadas)
integrator_asserted Assina no seu produto, que garante a sua identidade (externalUserId) Assinatura integrada por trás do seu próprio início de sessão

none é a predefinição porque a ligação que a Bona Fide envia por e-mail já é exclusiva do destinatário e impossível de adivinhar: abri-la demonstra o controlo do endereço de e-mail, que é a atribuição em que assentam as leis sobre assinatura eletrónica (ESIGN / UETA nos EUA, assinaturas eletrónicas simples ao abrigo do eIDAS). Produtos comparáveis também a utilizam por predefinição. Os modelos publicados com email_otp mantêm-no, e um email_otp explícito continua a funcionar em todo o lado.

Há dois fluxos que nunca dependem apenas de uma ligação:

  • Ligações de assinatura permanentes (/l/…): o visitante escreve o seu próprio endereço, pelo que confirma sempre um código enviado por e-mail antes de ser criado um envelope, independentemente do que o modelo indique.
  • Sessões criadas por si (POST /v1/envelopes/{id}/sessions) não contêm qualquer prova do endereço de e-mail: essa é a função do seu início de sessão, por isso utilize integrator_asserted (com externalUserId) ou email_otp nestes casos.

O certificado de conclusão regista, por signatário, o que foi efetivamente utilizado:

Registado como Quando
Ligação por e-mail (ligação única enviada para endereço) none, assinado a partir da ligação enviada por e-mail
Ligação por e-mail + código de utilização única (enviado para endereço) email_otp, assinado a partir da ligação enviada por e-mail
Ligação de assinatura + código de utilização única (enviado para endereço) Um visitante de uma ligação permanente
Código de utilização única (enviado para endereço) email_otp numa sessão criada por si
Sessão de assinatura emitida pelo remetente none numa sessão criada por si
Declaração do integrador integrator_asserted

O resumo público de verificação mostra as mesmas etiquetas, sem o endereço.

Idiomas

Seção intitulada “Idiomas”

A página de assinatura, os respetivos e-mails (pedido, lembretes, códigos, concluído, anulado), a página da ligação permanente e a página de estado do observador estão disponíveis em 50 idiomas. O signatário vê-os por esta ordem de preferência:

  1. o idioma que escolheu no menu de idiomas da página (memorizado nesse dispositivo);
  2. <bf-signing locale="…"> (assinatura integrada) ou ?locale= numa ligação alojada;
  3. o locale do destinatário, definido quando o envelope é criado (recipients[].locale, ou locale no envelope para todos os que não têm o seu);
  4. o idioma do navegador.

Os e-mails precisam de um idioma antes de alguém abrir uma página, por isso utilizam o locale do destinatário e são enviados em inglês quando este não existe. As ligações permanentes enviam o e-mail com o código no idioma que a página do visitante apresenta.

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

São aceites etiquetas próximas, guardadas 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 indicam que prevalece o texto em inglês, e o signatário pode mudar para esse texto; o idioma em que o aviso foi lido fica registado 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 Checo Čeština
da Dinamarquês Dansk
nl Neerlandês Nederlands
en-GB Inglês (Reino Unido) English (UK)
en-US Inglês (EUA) English (US)
et Estónio 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 Marata मराठी
nb Norueguês Norsk bokmål
fa Persa (farsi) فارسی da direita para a esquerda
pl Polaco 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

Ligações de assinatura permanentes

Seção intitulada “Ligações de assinatura permanentes”

Uma ligação de assinatura é um URL permanente para contratos que muitas pessoas assinam da mesma forma: uma declaração de renúncia, um contrato de prestação de serviços, os termos de um projeto-piloto. Cada visitante que a conclui recebe o seu próprio envelope.

Janela do terminal
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 é a função de signatário que o visitante assume. As ligações suportam 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 para o email indicado. Qualquer outra função que não seja CC ficaria sem destinatário, pelo que esses modelos são recusados.
  • O visitante introduz o nome, o e-mail e as variáveis do modelo e depois confirma um código enviado por e-mail antes de ser criado o que quer que seja (POST /v1/links/{id}/start e, em seguida, POST /v1/links/{id}/verify).
  • limits limita a utilização por e-mail por dia (predefinição 3), por IP por hora (predefinição 20), por dia no total e por domínio de e-mail. Com dedupe (ativado por predefinição), um endereço de e-mail que já assinou recebe 409 already-signed.
  • PATCH /v1/signing-links/{id} coloca a ligação em pausa (active: false), retoma-a ou muda-a para uma versão mais recente; eliminar uma ligação mantém os envelopes que esta criou. Cada utilização emite signing_link.used.