DocuSign添加补充文档后嵌入签署视图不显示问题排查

问题情况 #

你在DocuSign里添加了补充文档，想让收件人用嵌入签署视图时能看到，但现在文档没显示。信封创建没报错，收件人也能正常打开签署视图，就是缺了补充文档。

代码问题分析 #

看你贴的代码，问题出在补充文档的位置：你把$document2放在了EnvelopeDefinition的顶层documents数组里，但同时你用了CompositeTemplates（包含服务器模板）。在DocuSign的规则里，只要用了复合模板，系统就只会处理复合模板里配置的文档，顶层的documents会被忽略，所以补充文档没被加载到签署流程里。

解决步骤 #

把补充文档移到复合模板里，两种方法任选：

方法1：直接把补充文档加到现有复合模板 #

修改复合模板的创建代码，把$document2放进CompositeTemplate的document字段，同时移除顶层的setDocuments调用：

// 创建复合模板时加入补充文档
$compTemplate = new CompositeTemplate([
    'composite_template_id' => '1',
    'document' => $document2, // 补充文档放在这里
    'server_templates' => [
        new ServerTemplate([
            'sequence' => '1',
            'template_id' => $instance->docuSignTemplate->template_id,
        ]),
    ],
    'inline_templates' => [
        new InlineTemplate([
            'sequence' => '2',
            'recipients' => $recipientsServerTemplate,
        ]),
    ],
]);

$envelopeDefinition = new EnvelopeDefinition();
$envelopeDefinition->setStatus('sent');
// 删掉这行：$envelopeDefinition->setDocuments([$document2]);
$envelopeDefinition->setCompositeTemplates([$compTemplate]);

方法2：新增复合模板单独放补充文档 #

如果想把服务器模板和补充文档分开管理，就新增一个复合模板，注意调整sequence确保顺序正确：

// 原有的服务器模板复合模板不变
$compTemplate = new CompositeTemplate([
    'composite_template_id' => '1',
    'server_templates' => [
        new ServerTemplate([
            'sequence' => '1',
            'template_id' => $instance->docuSignTemplate->template_id,
        ]),
    ],
    'inline_templates' => [
        new InlineTemplate([
            'sequence' => '2',
            'recipients' => $recipientsServerTemplate,
        ]),
    ],
]);

// 新增补充文档的复合模板
$supplementTemplate = new CompositeTemplate([
    'composite_template_id' => '2',
    'document' => $document2,
    'inline_templates' => [
        new InlineTemplate([
            'sequence' => '3', // 顺序在服务器模板之后
            'recipients' => $recipientsServerTemplate, // 关联需要查看的签署人
        ]),
    ],
]);

$envelopeDefinition = new EnvelopeDefinition();
$envelopeDefinition->setStatus('sent');
// 删掉顶层setDocuments，添加两个复合模板
$envelopeDefinition->setCompositeTemplates([$compTemplate, $supplementTemplate]);

额外注意点 #

• 确保补充文档的document_id和服务器模板里的文档ID不重复，避免冲突
• display: modal和signer_must_acknowledge: view的配置要生效，必须让签署人正确关联到这个文档，也就是收件人配置要包含在对应模板的inline_templates里

内容的提问来源于stack exchange，提问作者Val Vincent Montesclaros