本文详解如何在个性化内容场景下，合理选择 docusign 的批量发送（bulk send）或单个信封+嵌入式签名（embedded signing）方案，并提供可落地的 api 调用流程、安全实践与代码示例。
本文详解如何在个性化内容场景下，合理选择 docusign 的批量发送（bulk send）或单个信封+嵌入式签名（embedded signing）方案，并提供可落地的 api 调用流程、安全实践与代码示例。
在实际业务中，许多企业希望向大量客户批量发送待签署文件（如合同续费、报价单），同时要求每份文件包含动态字段（例如个性化价格、客户名称、服务周期等），并引导用户在自有网站内完成签署——即“点击按钮 → 弹窗/跳转 → 签署文档”。此时，开发者常误以为必须使用 DocuSign 的 Bulk Send 功能来提升效率。但需明确：Bulk Send 仅适用于纯邮件通知型远程签署（Remote Signing），不支持嵌入式签名（Embedded Signing）。一旦你的流程依赖 CreateRecipientView 生成签名链接并在前端重定向或 iframe 加载，则 Bulk Send 将无法满足需求。
✅ 正确技术路径：按需创建 + 嵌入式签名
当每个信封内容存在差异（如 renewal price 不同）、且需在自有网页中完成签署时，应采用以下标准流程：
-
以集成用户身份（JWT 授权）创建个性化信封
使用模板（Template）预置结构，通过 templateRoles 注入动态数据（如 customFields, textTabs, numberTabs）。 -
为每位签署人即时生成唯一签名链接
调用 /v2.1/accounts/{accountId}/envelopes/{envelopeId}/views/recipient，传入 returnUrl、authenticationMethod 和 email/name 等必要参数。 -
前端安全引导签署
用户点击「立即签署」后，前端跳转至返回的 url（推荐 window.location.href 重定向，避免 iframe 安全限制）。
示例：创建信封并获取嵌入式签名链接（Python + requests）
import requests
import json
BASE_URL = "https://demo.docusign.net/restapi"
ACCOUNT_ID = "your-account-id"
ACCESS_TOKEN = "your-jwt-bearer-token"
# Step 1: 创建个性化信封（基于模板）
envelope_data = {
"templateId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"templateRoles": [{
"email": "client@example.com",
"name": "Alice Johnson",
"roleName": "Signer",
"tabs": {
"textTabs": [{
"tabLabel": "renewal_price",
"value": "$2,499.00"
}]
}
}],
"status": "sent"
}
resp = requests.post(
f"{BASE_URL}/v2.1/accounts/{ACCOUNT_ID}/envelopes",
headers={"Authorization": f"Bearer {ACCESS_TOKEN}", "Content-Type": "application/json"},
data=json.dumps(envelope_data)
)
envelope_id = resp.json()["envelopeId"]
# Step 2: 获取嵌入式签名视图 URL
view_req = {
"returnUrl": "https://your-app.com/signing-complete",
"authenticationMethod": "none", # 或 "sms", "password" 等
"email": "client@example.com",
"userName": "Alice Johnson",
"clientUserId": "client_abc123" # 必填！标识嵌入式用户（不可为空）
}
resp = requests.post(
f"{BASE_URL}/v2.1/accounts/{ACCOUNT_ID}/envelopes/{envelope_id}/views/recipient",
headers={"Authorization": f"Bearer {ACCESS_TOKEN}", "Content-Type": "application/json"},
data=json.dumps(view_req)
)
signing_url = resp.json()["url"] # ⚠️ 此 URL 一次性有效，10 分钟过期
print("Redirect user to:", signing_url)? 关键注意事项：
- clientUserId 是嵌入式签名的强制字段，代表该签署人在你系统中的唯一 ID（如数据库 user_id）。DocuSign 会校验该值是否与创建信封时 templateRoles.clientUserId 一致（若使用模板）或 signers.clientUserId 一致（若使用复合模板/裸信封）。
- 签名 URL 具有时效性（默认 10 分钟），切勿缓存或长期存储；应在用户触发动作（如点击按钮）时实时生成并跳转。
- 若需支持未登录用户，建议采用「邮箱+验证码」或「手机号+短信码」二次认证，再关联到 clientUserId，杜绝 ID 滥用风险。
❌ 为什么 Bulk Send 不适用？
Bulk Send 的设计目标是：一份模板 + 一个收件人列表 CSV → 一键触发数千封标准化邮件。其 API 流程如下：
POST /v2.1/accounts/{accountId}/bulk_send_lists/{listId}/send返回的 batchId 和 envelopeOrTemplateId 仅用于后台异步任务追踪，不会暴露单个信封 ID，也无法为指定签署人生成 Recipient View 链接。所有签署行为均由 DocuSign 邮件系统驱动，完全脱离你的前端控制。
因此，当你需要：
- 在自有页面渲染签署界面（非 DocuSign 邮件跳转）
- 每份文档含差异化字段（价格、条款、附件）
- 实时控制用户身份与会话上下文
→ 则必须放弃 Bulk Send，改用「逐个创建信封 + 嵌入式签名」模式。现代 API 性能足以支撑每秒数次调用，配合异步队列（如 Celery/RabbitMQ），轻松处理日均万级签署请求。
? 最佳实践总结
| 场景 | 推荐方案 | 关键动作 |
|---|---|---|
| 内容高度统一 + 签署人无需登录你的系统 | ✅ Bulk Send | 上传 CSV，配置模板，调用 /bulk_send_lists/{id}/send |
| 内容个性化 + 需嵌入至自有网站 | ✅ 单信封 + Embedded Signing | JWT 创建信封 → CreateRecipientView → 前端跳转 |
| 需并发管理多批次签署任务（如 A/B 测试不同报价） | ✅ 自建任务跟踪表 | 在数据库记录 batch_id, client_user_id, envelope_id, status，供运营侧查看进度 |
最后提醒：无论采用哪种方式，务必启用 DocuSign 的 Connect Webhook 监听 EnvelopeCompleted、EnvelopeDeclined 等事件，实现签署结果的自动回写与业务闭环。这才是企业级电子签约系统的完整拼图。
