DocuSign双人签名实现：非模板方案及SetDocumentVisibilityService权限报错排查

一、除模板外的双人签名实现方式 #

• 直接创建签署信封：无需预先保存模板，直接在代码中构建EnvelopeDefinition对象，添加两个Signer实例，为每个签署人指定对应的签署标签（如SignHere）及文档位置，最后通过EnvelopesApi.createEnvelope提交信封即可发起双人签署流程。
• 使用复合模板：若需要复用部分文档或签署配置但不想创建公共模板，可通过复合模板（Composite Templates）将文档、签署人配置灵活组合，实现定制化的双人签署场景。

二、SetDocumentVisibilityService相关问题解决与使用方法 #

报错原因 #

你遇到的ACCOUNT_LACKS_PERMISSIONS错误，核心原因是你的DocuSign账户未开启**文档可见性（Document Visibility）**功能。该功能默认关闭，需由账户管理员在账户设置中开启，或联系DocuSign支持团队协助开启。

开启功能后实现多人签名的步骤（Java示例） #

1. 确认账户权限：联系管理员确保账户已启用文档可见性功能。
2. 构建基础签署信封：创建包含多个签署人和对应签署标签的EnvelopeDefinition，并提交信封获取envelopeId。
3. 配置文档可见性规则：为每个签署人创建DocumentVisibility对象，指定其可访问的文档ID，再通过SetDocumentVisibilityService.updateDocumentVisibility提交配置。

示例代码片段：

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

// 构建信封定义
EnvelopeDefinition envelopeDefinition = new EnvelopeDefinition();
envelopeDefinition.setEmailSubject("双人签署请求");

// 添加待签署文档
Document document = new Document();
document.setDocumentBase64(Base64.getEncoder().encodeToString(Files.readAllBytes(Paths.get("contract.pdf"))));
document.setName("合作合同.pdf");
document.setDocumentId("1");
envelopeDefinition.setDocuments(Arrays.asList(document));

// 添加第一个签署人
Signer signer1 = new Signer();
signer1.setEmail("signer1@yourdomain.com");
signer1.setName("张三");
signer1.setRecipientId("1");
SignHere signHere1 = new SignHere();
signHere1.setDocumentId("1");
signHere1.setPageNumber("1");
signHere1.setXPosition("150");
signHere1.setYPosition("200");
signer1.setTabs(new Tabs().setSignHereTabs(Arrays.asList(signHere1)));

// 添加第二个签署人
Signer signer2 = new Signer();
signer2.setEmail("signer2@yourdomain.com");
signer2.setName("李四");
signer2.setRecipientId("2");
SignHere signHere2 = new SignHere();
signHere2.setDocumentId("1");
signHere2.setPageNumber("1");
signHere2.setXPosition("350");
signHere2.setYPosition("200");
signer2.setTabs(new Tabs().setSignHereTabs(Arrays.asList(signHere2)));

envelopeDefinition.setRecipients(new Recipients().setSigners(Arrays.asList(signer1, signer2)));
envelopeDefinition.setStatus("sent");

// 创建信封
EnvelopesApi envelopesApi = new EnvelopesApi(apiClient);
EnvelopeSummary envelopeSummary = envelopesApi.createEnvelope(accountId, envelopeDefinition);
String envelopeId = envelopeSummary.getEnvelopeId();

// 配置文档可见性（允许两个签署人查看文档1）
SetDocumentVisibilityService visibilityService = new SetDocumentVisibilityService(apiClient);
DocumentVisibility vis1 = new DocumentVisibility();
vis1.setDocumentId("1");
vis1.setRecipientId("1");
vis1.setVisibility("true");

DocumentVisibility vis2 = new DocumentVisibility();
vis2.setDocumentId("1");
vis2.setRecipientId("2");
vis2.setVisibility("true");

visibilityService.updateDocumentVisibility(accountId, envelopeId, Arrays.asList(vis1, vis2));

注意事项 #

• 文档可见性功能的作用是控制不同签署人能查看的文档范围，如果你的场景不需要限制文档访问，无需使用该服务，直接创建包含多签署人的信封即可实现双人签名。
• 开启账户的文档可见性功能必须由账户管理员操作，普通用户无法自行开启。

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