You need to enable JavaScript to run this app. 使用DocuSign PHP SDK创建信封时如何正确替换模板基础文档
优惠活动
大模型
产品
解决方案
定价
更多

使用DocuSign PHP SDK创建信封时如何正确替换模板基础文档

信封文档替换实现说明与代码修复

思路判断

  • 不需要调用EnvelopeDocuments:update接口。这个接口的使用场景是信封已经创建完成(处于草稿/已发送状态)之后,对信封内关联的文档做后置修改,你现在是在创建信封的环节就要替换模板自带的文档,完全可以在创建信封的请求里通过复合模板能力直接实现,不需要额外调用后续更新接口,避免多余的接口开销。
  • 你选择用复合模板做创建阶段文档替换的大方向是正确的,当前代码运行报错有两个核心原因:一是存在PHP语法解析错误,二是复合模板的文档覆盖逻辑配置错误。

代码即时错误排查

你附的代码中存在直接导致解析失败的语法问题:实例化$documentUpdated对象时,传入的数组在'document_id' => '1'行结束后,没有闭合new Document()的调用括号,直接进入了$comp_template2的实例化逻辑,这种情况下PHP会直接抛出语法解析错误,根本不会走到接口请求环节。

复合模板替换逻辑校正

  • 你之前的写法是拆分了两个独立的复合模板:第一个复合模板关联服务器模板、填充收件人角色;第二个复合模板单独挂载新PDF文档。这种配置的最终效果是信封内同时保留模板自带的基础文档和你新上传的PDF,属于文档叠加,不是替换。
  • 正确的替换逻辑是把要替换的自定义文档,和关联的服务器模板放到同一个复合模板下,并且设置和原模板内文档完全相同的document_id,系统会自动用你传入的新文档内容覆盖服务器模板绑定的同ID文档,同时完整保留模板上所有的标签定位、签署关联、权限配置逻辑。
  • 同个复合模板下的服务器模板、内联模板、自定义文档需要保持一致的序列值,系统会按序列顺序合并同个复合模板的所有配置,最终生成完整的信封结构。

修复后可正常运行的代码

private function make_envelope(array $args): EnvelopeDefinition
{
    // 初始化签署人配置
    $signer = new Signer([
        'email' => $args['signer_email'],
        'name' => $args['signer_name'],
        'role_name' => "signer",
        'recipient_id' => "1",
    ]);

    $companySigner = new Signer([
        'email' => $args['companySigner_email'],
        'name' => $args['companySigner_name'],
        'role_name' => "companySigner",
        'recipient_id' => "2"
    ]);

    $recipients_server_template = new Recipients([
        'signers' => [$signer, $companySigner]
    ]);

    // 读取需要替换的自定义PDF文档
    $doc_file = 'Fiber_Connect_Customer_Agreement.pdf';
    $content_bytes = file_get_contents(self::DEMO_DOCS_PATH . $doc_file);
    $base64_file_content = base64_encode($content_bytes);

    // 初始化替换文档:document_id必须和原模板内的目标文档ID保持一致(通常模板默认文档ID为1)
    $documentUpdated = new Document([
        'document_base64' => $base64_file_content,
        'name' => 'Prepared Fiber Connect Customer Agreement',
        'file_extension' => 'pdf',
        'document_id' => '1'
    ]);

    // 把服务器模板、收件人配置、替换文档全部绑定到同一个复合模板下
    $comp_template1 = new CompositeTemplate([
        'composite_template_id' => "1",
        'server_templates' => [
            new ServerTemplate([
                'sequence' => "1",
                'template_id' => $args['template_id']
            ])
        ],
        // 挂载需要替换的自定义文档
        'document' => $documentUpdated,
        'inline_templates' => [
            new InlineTemplate([
                'sequence' => "1",
                'recipients' => $recipients_server_template
            ])
        ]
    ]);

    // 生成信封定义,无需额外拆分第二个复合模板
    $envelope_definition = new EnvelopeDefinition([
        'status' => "sent",
        'composite_templates' => [$comp_template1]
    ]);

    return $envelope_definition;
}

内容的提问来源于stack exchange,提问作者bodenbox

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.11.06 00:15:04