跳转到内容
bona fidedocs

签署会话与链接

收件人在 Bona Fide 的签署页面上签署：可以是位于 https://sign.bonafidesign.com/s/… 的托管页面，也可以是通过 <bf-signing> 嵌入到您产品中的同一页面。收件人无需账户。让他们进入签署流程的是签署会话。

签署会话

章节标题“签署会话”

电子邮件投递会自动为您创建会话（即邮件中的链接）。对于嵌入式签署或自行投递的签署，请从您的后端签发会话：

Terminal window
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"
}
字段 说明
recipient 信封中仍可签署的收件人（不是抄送，且尚未完成）
mode embedded（默认）或 hosted。托管式的 url 形如 …/s/<token>，可用于重定向或由您自行发送
allowedOrigins 最多 10 个允许以框架形式嵌入该页面的源
returnUrl 签署人完成后，托管页面将其带往的地址
ttlSeconds 60 到 3600，默认 600

会话只能使用一次：收件人提交后会话即失效，已使用或已过期的会话会返回 410 Gone。请在每次渲染页面时签发一个新会话。只有当信封处于 sent 状态时才能创建会话，作废信封会使其所有会话失效。

签署人需要经历的步骤

章节标题“签署人需要经历的步骤”

签署页面（以及您基于同一 API 构建的任何自定义界面）遵循以下步骤：

  1. 交换：POST /v1/signing/exchange { "token": "bfs_…" } 返回一个保存在内存中的短时效访问令牌（bfa_…）。整个过程不涉及 Cookie，因此在 iframe 中屏蔽第三方 Cookie 也没有影响。
  2. 加载：GET /v1/signing/session 返回签署人视图（信封标题、发件人、收件人的角色和字段、预填值、消费者披露），并在首次加载时记录 recipient.viewed。GET /v1/signing/document 是要显示的 PDF。
  3. 验证（仅限 email_otp）：POST /v1/signing/otp 通过电子邮件发送 6 位验证码（有效期 10 分钟），POST /v1/signing/otp/verify 对其进行校验。验证码错误时返回 verified: false 以及剩余尝试次数。当收件人的验证方式不需要验证码时，视图中的 verification.verified 已为 true。
  4. 提交：POST /v1/signing/submit，附带字段的 values（手写、键入或上传的签名）、对披露内容的同意，以及 viewedDocumentHash：即所显示 PDF 的 SHA-256。如果此后文档发生了变化，提交会被拒绝（409）。
  5. 或者拒绝：POST /v1/signing/decline { "reason": "…" } 会终止信封（envelope.declined）。

只有在之前的所有流转组都完成后，才轮到该收件人；在此之前，视图中的 canSign: false，提交会返回 409 not-your-turn。

签署人验证

章节标题“签署人验证”

每位收件人都有一个 verification 方式：默认采用角色的验证方式（在模板设计器的角色面板中设置），除非信封针对该收件人进行了覆盖（在发送界面中，或通过 recipients[].verification）。

方式 签署人需要做什么 适用场景
none（默认） 打开唯一的签署链接并签署 链接通过电子邮件发送给签署人：只有能访问该收件箱的人才能拿到
email_otp 打开链接，然后输入发送到同一地址的 6 位验证码 您希望在签署时获得第二份即时证明（高价值合同、共享收件箱）
integrator_asserted 在您的产品中签署，由您的产品为其身份背书（externalUserId） 在您自己的登录体系之后进行的嵌入式签署

之所以默认使用 none，是因为 Bona Fide 通过电子邮件发送的链接本身就是该收件人独有且无法猜测的：能打开链接，就表明其掌控该电子邮件地址，而这正是电子签名法律所依赖的归属依据（美国的 ESIGN / UETA，以及 eIDAS 下的简单电子签名）。同类产品也默认采用这种方式。使用 email_otp 发布的模板会保留该设置，显式指定的 email_otp 在任何地方都继续有效。

有两种流程从不只依赖链接：

  • 常设签署链接（/l/…）：访问者自行输入其电子邮件地址，因此在创建信封之前，他们总是需要确认通过电子邮件发送的验证码，无论模板如何设置。
  • 您签发的会话（POST /v1/envelopes/{id}/sessions）完全不带有电子邮件地址的证明：这是您的登录体系的职责，因此请为这类会话使用 integrator_asserted（配合 externalUserId）或 email_otp。

完成证书会为每位签署人记录实际使用的方式：

记录内容 适用情形
电子邮件链接（唯一链接已发送至地址） none，通过电子邮件中的链接签署
电子邮件链接 + 一次性验证码（已发送至地址） email_otp，通过电子邮件中的链接签署
签署链接 + 一次性验证码（已发送至地址） 常设链接的访问者
一次性验证码（已发送至地址） 在您签发的会话中使用 email_otp
由发件人签发的签署会话 在您签发的会话中使用 none
集成方声明 integrator_asserted

公开验证摘要显示相同的标签，但不含地址。

语言

章节标题“语言”

签署页面、其电子邮件（签署请求、提醒、验证码、完成通知、作废通知）、常设链接页面以及查看者状态页面支持 50 种语言。签署人看到的语言按以下优先顺序确定：

  1. 签署人在页面语言菜单中选择的语言（在该设备上会被记住）；
  2. <bf-signing locale="…">（嵌入式签署）或托管链接上的 ?locale=；
  3. 创建信封时为收件人设置的 locale（recipients[].locale，或信封上的 locale，适用于所有未单独设置的人）；
  4. 签署人浏览器的语言。

电子邮件在任何人打开页面之前就需要确定语言，因此会使用收件人的 locale，未设置时为英语。常设链接会以访问者页面所显示的语言发送验证码邮件。

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

相近的语言标签也会被接受，并按其对应的语言存储（de-AT → de，es-MX → es-419，zh-TW → zh-Hant）；其他值均视为校验错误。翻译后的同意披露会注明以英文文本为准，签署人可以切换到英文原文；阅读披露时所用的语言会随签名一并记录（recipient.signed 审计事件中的 consentLocale）。

代码 语言 本地名称
ar 阿拉伯语 العربية 从右向左
hy 亚美尼亚语 Հայերեն
bn 孟加拉语 বাংলা
bg 保加利亚语 Български
zh-Hans 中文（简体） 简体中文
zh-Hant 中文（繁体） 繁體中文
hr 克罗地亚语 Hrvatski
cs 捷克语 Čeština
da 丹麦语 Dansk
nl 荷兰语 Nederlands
en-GB 英语（英国） English (UK)
en-US 英语（美国） English (US)
et 爱沙尼亚语 Eesti
fil 菲律宾语 Filipino
fi 芬兰语 Suomi
fr 法语 Français
fr-CA 法语（加拿大） Français (Canada)
de 德语 Deutsch
el 希腊语 Ελληνικά
he 希伯来语 עברית 从右向左
hi 印地语 हिन्दी
hu 匈牙利语 Magyar
id 印度尼西亚语 Bahasa Indonesia
it 意大利语 Italiano
ja 日语 日本語
ko 韩语 한국어
lv 拉脱维亚语 Latviešu
lt 立陶宛语 Lietuvių
ms 马来语 Bahasa Melayu
mr 马拉地语 मराठी
nb 挪威语 Norsk bokmål
fa 波斯语 فارسی 从右向左
pl 波兰语 Polski
pt-BR 葡萄牙语（巴西） Português (Brasil)
pt-PT 葡萄牙语（葡萄牙） Português (Portugal)
ro 罗马尼亚语 Română
ru 俄语 Русский
sr-Latn 塞尔维亚语（拉丁字母） Srpski
sk 斯洛伐克语 Slovenčina
sl 斯洛文尼亚语 Slovenščina
es-419 西班牙语（拉丁美洲） Español (Latinoamérica)
es-ES 西班牙语（西班牙） Español (España)
sw 斯瓦希里语 Kiswahili
sv 瑞典语 Svenska
te 泰卢固语 తెలుగు
th 泰语 ไทย
tr 土耳其语 Türkçe
uk 乌克兰语 Українська
ur 乌尔都语 اردو 从右向左
vi 越南语 Tiếng Việt

常设签署链接

章节标题“常设签署链接”

签署链接是一个永久 URL，适用于很多人以相同方式签署的合同：免责声明、承包商协议、试点项目条款等。每位完成签署的访问者都会得到自己的信封。

Terminal window
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 是访问者所担任的签署人角色。链接支持一位访问者和最多一位会签人：mode: "auto" 使用 Bona Fide 平台印章自动会签，mode: "person" 将信封流转到指定的 email。其他任何非抄送角色都将没有收件人，因此这类模板会被拒绝。
  • 访问者输入其姓名、电子邮件和模板的变量，然后在创建任何内容之前确认电子邮件验证码（先调用 POST /v1/links/{id}/start，再调用 POST /v1/links/{id}/verify）。
  • limits 可按每个电子邮件每天（默认 3 次）、每个 IP 每小时（默认 20 次）、每天总量以及电子邮件域限制使用。启用 dedupe（默认开启）时，已经签署过的电子邮件地址会收到 409 already-signed。
  • PATCH /v1/signing-links/{id} 可暂停（active: false）、恢复链接，或将其切换到更新的版本；删除链接会保留其已创建的信封。每次使用都会发出 signing_link.used。