如何在 DocuSign 发送方完成通知中动态插入签署人姓名-html教程-PHP中文网

如何在 DocuSign 发送方完成通知中动态插入签署人姓名

DocuSign 的 SenderEnvelopeComplete_HtmlBody 模板不支持 [[Data:SignerName]] 等占位符，因其作用域仅限于收件人（签署人）通知；发送方通知需通过自定义事件回调或 API 查询获取签署人信息后主动注入。

docusign 的 `senderenvelopecomplete_htmlbody` 模板不支持 `[[data:signername]]` 等占位符，因其作用域仅限于收件人（签署人）通知；发送方通知需通过自定义事件回调或 api 查询获取签署人信息后主动注入。

在使用 DocuSign Java SDK 构建“嵌入式签署（captive signing）”流程时，若希望在发送方收到的“信封已完成”邮件通知中显示签署人姓名（如 “张三已签署您的文档”），需明确一个关键前提：SenderEnvelopeComplete_HtmlBody 模板本身无法解析 [[Data:SignerName]] 或 [[Data:SignerEmail]]。

这是因为该模板的设计语义面向“发送方”（即创建并发起信封的用户），而一个信封可能包含多个签署人、抄送人或审批人。系统无法在模板渲染阶段自动判断应取哪一位签署人的数据——尤其当信封尚未完成时，甚至可能尚无确定的已签署人。因此，DocuSign 仅在面向具体收件人的模板（如 RecipientEnvelopeComplete_HtmlBody）中提供 [[Data:SignerName]] 等上下文变量。

✅ 正确实现路径如下：

启用 Connect Webhook 或使用 Events API
配置 DocuSign Connect（推荐）或轮询 envelopes/{envelopeId}/recipients 接口，在收到 envelope-completed 事件后，立即调用：
```
GET /v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients
```
解析响应中 signers 数组，提取 name 和 email（注意：需确保签署人已提交，状态为 completed）。

通过 REST API 自定义发送方通知（推荐）
禁用默认发送方邮件（在信封创建时设置 emailSettings.senderEmailNotifications.envelopeComplete = false），改由后端服务在监听到完成事件后，调用企业邮件服务（如 SendGrid、SMTP）发送定制化通知：

// 示例：Java 中构建自定义通知正文
String signerName = getCompletedSignerName(envelopeId); // 从 recipients API 获取
String subject = "✅ 文档已签署完成 — " + signerName;
String htmlBody = """
    <p>您好，</p>
    <p><strong>%s</strong> 已于 %s 完成签署。</p>
    <p><a href="https://app.docusign.com/organizations/%s/envelopes/%s">查看信封详情</a></p>
    """.formatted(signerName, LocalDateTime.now(), accountId, envelopeId);
sendCustomEmail(senderEmail, subject, htmlBody);

注意事项
- ✖️ 不要尝试覆盖 SenderEnvelopeComplete_HtmlBody 并硬编码占位符——它们将始终为空字符串；
- ✅ 若信封仅含唯一签署人且业务允许延迟几秒，可通过 recipients API 实现 99% 准确率的姓名注入；
- ? 调用 recipients API 需使用与创建信封相同的 OAuth token（或集成密钥+JWT），确保权限充足（signature scope）；
- ⚠️ 注意时区与时间格式一致性，建议以 ISO 8601 格式返回签署完成时间（completedDateTime 字段）。