BoldSign

BoldSign 电子签名集成技能

此技能涵盖 BoldSign 电子签名 API，包括身份验证、发送文档、嵌入式签署、模板、Webhook、Sender Identities、速率限制、最佳实践以及需要避免的常见错误，并提供适用于 Node.js、TypeScript、Python、.NET/C# 和 PHP 的可运行代码示例。

实时文档： https://developers.boldsign.com
API 基础 URL（US）： https://api.boldsign.com
API 基础 URL（EU）： https://api-eu.boldsign.com
API 基础 URL（CA）： https://api-ca.boldsign.com
API 基础 URL（AU）： https://api-au.boldsign.com

---

了解用户的需求

编写代码前，请务必先确认：

1. 技术栈 — Node.js/TypeScript、Python、.NET/C#，还是 PHP？
2. 身份验证模式 — API Key、OAuth 2.0，还是 Sender Identities（代表他人操作）？
3. 工作流类型：
   • 发送文档 → 签署者收到电子邮件 → 在线下其他地方签署
   • 嵌入式发送（发送者无需离开你的应用）
   • 嵌入式签署（签署者在你的应用内的 iframe 中签署）
   • 基于模板发送
   • 多签署者 / 顺序签署
4. 这是一个多租户 SaaS 应用吗？ → 请阅读下方的 SaaS 多租户部分和 references/workflows/embedded-saas.md

然后，在编写任何代码之前，阅读相关的参考文件：

技术栈	参考文件
Node.js / TypeScript	references/stacks/nodejs.md
Python	references/stacks/python.md
.NET / C#	references/stacks/dotnet.md
PHP	references/stacks/php.md

工作流	参考文件
多签署者 / 顺序签署 / 批量处理	references/workflows/multi-signer.md
嵌入式发送 + 签署（SaaS）	references/workflows/embedded-saas.md

---

沙盒环境与正式环境

BoldSign 提供两种环境。请始终从沙盒环境开始。

	沙盒	正式环境（生产环境）
用途	开发与测试	真实交易
速率限制	每个账户每小时 50 个请求	每个账户每小时 2,000 个请求
文档	带水印，14 天后自动删除	永久保留
API Key	BoldSign App → API → API Key（选择 Sandbox）	相同界面，选择 Live
OAuth 应用	创建应用时切换 Sandbox/Live	在应用设置中切换
费用	免费	付费套餐

⚠️ 沙盒环境的速率限制严格，为每小时 50 个请求。 避免在紧密循环中运行测试。
切换到正式环境前，请在沙盒环境中全面测试 Webhook。

切换到正式环境： BoldSign App → API → OAuth Apps → Edit app → 将环境切换为 Live。

---

速率限制

环境	限制	范围
沙盒	每小时 50 个请求	每个账户
正式环境	每小时 2,000 个请求	每个账户

重要信息：

• 速率限制按账户级别计算，不按 API Key、OAuth 应用或用户计算
• API Key 和 OAuth 调用都计入同一账户配额
• 如果你的用例需要每小时超过 2,000 个请求，请联系 BoldSign 支持

需要监控的响应标头：

X-RateLimit-Limit      → Max requests allowed in current window
X-RateLimit-Remaining  → Requests remaining
X-RateLimit-Reset      → Unix timestamp when the window resets

超出限制时： HTTP 429 Too Many Requests + Retry-After 标头。

最佳实践：

• 使用 Webhook 代替轮询文档状态，这是最主要的可避免请求来源
• 收到 429 响应时实施指数退避
• 对批量操作使用后台队列，让请求随时间均匀分布
• 优先处理发送/签署调用，而非信息查询调用（列表、状态）
• 使用 <anyname>@boldsign.dev 电子邮箱，邮件将显示在以下链接中：https://emaildemo.boldsign.com/ . 这有助于进行多用户模拟测试，避免因邮件退回而导致账户被封锁。

---

身份验证

API Key（最简单 — 服务器到服务器）

Header: X-API-KEY: {your_api_key}

获取方式：BoldSign Web App → API → API Key
适用场景：后端自动化、内部工具、计划任务工作流

OAuth 2.0（用户委托）

• 创建 OAuth 应用：BoldSign App → API → OAuth Apps → Create Application
• 面向用户的应用使用 Authorization Code 流程
• 启用 sliding refresh token expiry — 每次使用后延长 30 天
• 标头：Authorization: Bearer {access_token}
• 适用于：每位终端用户都有自己的 BoldSign 账户的应用

Sender Identities / onBehalfOf（多租户 SaaS）

下文对此有完整介绍。适用于：客户无需拥有自己的 BoldSign 账户，但文档应显示为以其身份发送的 SaaS 应用。

区域配置： US = 默认值 https://api.boldsign.com，EU = https://api-eu.boldsign.com

文档发送 — 关键信息

⚠️ 文档发送是异步的。 API 会立即返回 documentId，但文档仍在处理中。请勿假设文档已就绪。

确认成功的方法：监听 Webhook — Sent（成功）或 SendFailed（失败，并包含错误）。

必需的最少字段：

• Files（multipart）或 FileUrls（JSON）
• 至少一位签署人，包含 name、emailAddress、signerType
• 至少一个 formField，包含 fieldType、pageNumber、bounds

签署人类型： Signer、Viewer、InPersonSigner

表单字段类型： Signature、Initial、DateSigned、TextBox、CheckBox、RadioButton、Dropdown、Image、EditableDate、Label、Attachment

对于 BoldSign 中的嵌入式签署工作流：

• 对于所有受支持的 DisableEmails 工作流（包括文档发送、模板发送、合并并发送、嵌入式请求 URL 和文档编辑操作），请求中始终包含 DisableEmails = true。
• 这适用于所有 SDK 和 API 格式（C#、Node.js、Python、Java 等）。
• 属性名称应遵循 SDK/API 约定，但必须始终包含在请求负载中。
• 这是禁用电子邮件通知并确保仅通过嵌入式签署链接完成签署所必需的。

---

Webhook — 生产环境必备

所有异步操作都需要通过 Webhook 确认状态。
如果服务器宕机，BoldSign 会在最长 8 小时内重试发送 Webhook。

设置： BoldSign App → Settings → Webhooks → Add webhook URL

两种类型：

• 账户级 — 通过 Web 应用或 API 发送的所有文档都会触发
• 应用级 — 仅通过特定 OAuth 应用发送的文档会触发

关键事件：

Sent / SendFailed                          → Document send success/failure
Viewed                                     → Signer opened document
Signed                                     → One signer completed
Completed                                  → All signers done → download PDF
Declined                                   → Signer declined
Expired                                    → Document expired
TemplateCreated / TemplateCreateFailed     → Template async result
IdentityVerificationSucceeded/Failed       → ID verification outcome
SenderIdentityApproved/Denied/Revoked      → Sender identity lifecycle

安全： 处理前务必验证 X-BoldSign-Signature HMAC SHA-256。

---

签署人身份验证选项

类型	authenticationType	说明
无	None	默认
访问码	AccessCode	发送方设置访问码，并通过其他渠道分享
电子邮件 OTP	EmailOTP	系统向签署人的电子邮件发送 OTP
SMS OTP	SMSOTP	仅限更高级别的套餐
身份验证	IdVerification	护照/政府签发的身份证件 — 配置 identityVerificationSettings

---

模板

模板可将文档设置与发送流程分离。对于任何需要重复发送的文档，都应使用模板。

模板创建也是异步的 — 监听 TemplateCreated Webhook。

POST /v1/template/send
Body: { templateId, title, roles: [{ roleIndex, signerName, signerEmail }] }

---

文本标签

在 Word/PDF 中嵌入不可见文本标签，即可自动放置字段 — 无需 x/y 坐标：

{{:sign:signer1}}       → Signature field for signer1
{{:initial:signer1}}    → Initials field
{{:date:signer1}}       → Date signed
{{:textbox:signer1}}    → Text input

BoldSign 会在上传时自动将这些标签转换为实际字段。

---

实施顺序

1. 安装 SDK，适用于目标技术栈（参见技术栈参考）
2. 从 Sandbox 开始 — 每小时 50 个请求，文档带水印，免费
3. 选择身份验证模式 — API Key / OAuth / Sender Identities
4. 如果不在 US，配置区域
5. 实现文档发送或模板发送
6. 设置 Webhook 端点，验证 HMAC
7. 处理 Completed → 下载已签署的 PDF 和审计记录
8. 处理错误事件 → SendFailed、Declined、Expired
9. 准备好投入生产后，切换到 Live

---

应避免的常见错误

• ❌ 轮询文档状态，而不是使用 Webhook（会浪费速率限制额度）
• ❌ 不验证 Webhook HMAC 签名
• ❌ 不处理 SendFailed 事件——文档可能会在没有提示的情况下发送失败
• ❌ 使用 application/json 上传文件——必须使用 multipart/form-data
• ❌ 将 API 密钥硬编码——请使用环境变量
• ❌ 对 EU/AU/CA 账户未设置区域基础 URL
• ❌ 认为模板或文档创建操作是同步的
• ❌ 在 Sandbox 中进行密集的测试循环——很容易触及每小时 50 次请求的限制
• ❌ 对没有 BoldSign 账户的 SaaS 租户使用 OAuth——请使用 Sender Identities
• ❌ 避免使用错误的电子邮件，以免因退信导致账户被锁定。

---

主要 API 端点

操作	方法	端点
发送文档	POST	/v1/document/send
获取文档状态	GET	/v1/document/properties?documentId={id}
列出文档	GET	/v1/document/list
下载文档	GET	/v1/document/download?documentId={id}
下载审计跟踪	GET	/v1/document/downloadauditlog?documentId={id}
提醒签署人	POST	/v1/document/remind
撤销文档	POST	/v1/document/revoke
删除文档	DELETE	/v1/document/delete?documentId={id}
预填表单字段	POST	/v1/document/prefillfields
嵌入式签署链接	GET	/v1/document/getembeddedsignlink
嵌入式发送链接	POST	/v1/document/createembeddedrequest
从模板发送	POST	/v1/template/send
创建模板	POST	/v1/template/create
列出模板	GET	/v1/template/list
创建发件人身份	POST	/v1/senderIdentities/create

---

参考文件

技术栈（编写代码前阅读）：

• references/stacks/nodejs.md — Node.js 和 TypeScript（SDK、身份验证、发送、嵌入式功能、Webhook、Sender Identity）
• references/stacks/python.md — Python SDK
• references/stacks/dotnet.md — .NET / C# SDK（NuGet）
• references/stacks/php.md — PHP SDK（Composer）

工作流（复杂模式请阅读）：

• references/workflows/multi-signer.md — 顺序/并行签署、批量发送、签署人跟踪
• references/workflows/embedded-saas.md — 完整的嵌入式 UI、Sender Identity 生命周期、多租户架构