如何使用DocuSign Java API向多个收件人发送签署请求？

我来帮你排查这个DocuSign Java API的问题，你遇到的TAB_REFERS_TO_MISSING_DOCUMENT错误通常和模板标签与收件人角色的匹配、信封创建逻辑有关，下面是具体的分析和解决方案：

错误原因分析 #

这个报错核心是系统找不到签署标签对应的文档或角色关联，常见触发场景有两个：

• 角色名不匹配：代码中setRoleName传入的名称和模板里定义的角色名存在差异（比如大小写、空格、拼写错误），导致标签无法关联到对应收件人。
• 信封创建逻辑错误：如果你尝试为两位收件人创建独立信封，第二次创建时没有正确复用原模板的文档关联，导致标签找不到绑定的文档。

正确解决方案：同一信封内顺序签署 #

最稳妥的方式是创建一个包含两位收件人的信封，通过设置签署顺序让DocuSign自动依次通知他们签署，这样能完整保留模板的标签与角色关联。

修正后的Java代码示例 #

// 初始化DocuSign客户端
ApiClient apiClient = new ApiClient();
apiClient.setBasePath("https://demo.docusign.net/restapi");
apiClient.addDefaultHeader("Authorization", "Bearer " + yourAccessToken);

EnvelopesApi envelopesApi = new EnvelopesApi(apiClient);

// 构建Applicant角色（第一个签署）
TemplateRole applicantRole = new TemplateRole();
applicantRole.setRoleName("Applicant") // 必须和模板内角色名完全一致（大小写、空格都要匹配）
             .setName("张三")
             .setEmail("applicant@example.com")
             .setRoutingOrder("1");

// 构建Co-applicant角色（第二个签署）
TemplateRole coApplicantRole = new TemplateRole();
coApplicantRole.setRoleName("Co-applicant") // 和模板角色名严格匹配
               .setName("李四")
               .setEmail("co-applicant@example.com")
               .setRoutingOrder("2");

// 构建信封定义
EnvelopeDefinition envelopeDefinition = new EnvelopeDefinition();
envelopeDefinition.setTemplateId("你的模板ID") // 替换为实际模板ID
                 .setStatus("sent")
                 .setTemplateRoles(Arrays.asList(applicantRole, coApplicantRole));

// 创建并发送信封
EnvelopeSummary envelopeSummary = envelopesApi.createEnvelope(yourAccountId, envelopeDefinition);
System.out.println("信封已发送，ID：" + envelopeSummary.getEnvelopeId());

关键修复点 #

1. 严格匹配角色名：登录DocuSign控制台检查模板内的角色名（比如是否是Co-applicant还是Co Applicant），代码中的setRoleName必须和模板里的名称完全一致，包括大小写和空格。
2. 确认模板标签绑定：在模板编辑页，检查每个签署标签是否正确绑定到了对应的角色（Applicant/Co-applicant），避免出现未绑定或绑定错误的标签。
3. 复用同一信封：不要为两位收件人创建独立信封，通过RoutingOrder设置签署顺序，让DocuSign自动处理后续通知逻辑。

特殊场景：手动触发二次签署 #

如果业务需要先让Applicant签署完成后，再手动触发Co-applicant的签署，可以通过更新信封收件人状态实现，避免重新创建信封：

String envelopeId = "已签署完成的信封ID";

// 获取当前信封的收件人列表
Recipients recipients = envelopesApi.listRecipients(yourAccountId, envelopeId);

// 找到Co-applicant并设置为待发送状态
for (Signer signer : recipients.getSigners()) {
    if ("Co-applicant".equals(signer.getRoleName())) {
        signer.setStatus("sent");
        break;
    }
}

// 更新收件人并重新发送
EnvelopesApi.UpdateRecipientsOptions options = new EnvelopesApi.UpdateRecipientsOptions();
options.setResendEnvelope("true");
envelopesApi.updateRecipients(yourAccountId, envelopeId, recipients, options);

内容的提问来源于stack exchange，提问作者Saul