DocuSign多文档场景下锚点重复添加Sign Here标签问题求助

你遇到的问题根源在于每个CompositeTemplate都重复创建了同一个recipient_id=1的Signer对象。DocuSign会自动合并所有相同recipient_id的收件人配置，导致每个文档的锚点都会匹配所有CompositeTemplate中定义的SignHere标签，最终每个锚点出现多个重复标签。

修复方案1：简化结构，统一管理文档与标签 #

重构代码，将文档收集和标签收集分开，只创建一次收件人对象并包含所有文档对应的签名字段，避免重复定义收件人。

修改后的代码：

private function buildEnvelope($envelopeFiles, $user): EnvelopeDefinition 
{
    $recipientEmail = $user->email; 
    $recipientName = $user->first_name . " " . $user->last_name; 
   
    // 收集所有文档对象
    $documents = [];
    // 收集所有文档对应的签名字段
    $signHereTabs = [];

    foreach ($envelopeFiles as $index => $documentPath) {
        $fileContent = file_get_contents($documentPath);
        $fileName = pathinfo($documentPath, PATHINFO_BASENAME);
        $fileExtension = pathinfo($documentPath, PATHINFO_EXTENSION);
        $documentId = $index + 1;

        // 创建当前文档的Document对象
        $documents[] = new Document([
            'document_base64' => base64_encode($fileContent),
            'name' => $fileName,
            'file_extension' => $fileExtension,
            'document_id' => $documentId,
        ]);

        // 创建当前文档对应的SignHere标签，绑定到指定文档ID
        $signHereTabs[] = new SignHere([
            'document_id' => $documentId,
            'page_number' => 1,
            'recipient_id' => '1',
            'anchor_string' => 'Initials',
            'tab_label' => "Sign_Doc_{$documentId}", // 唯一标识避免冲突
            'anchor_x_offset' => '40',
            'anchor_y_offset' => '0',
        ]);
    }

    // 创建单个收件人对象，包含所有签名字段
    $signer = new Signer([
        'email' => $recipientEmail,
        'name' => $recipientName,
        'recipient_id' => '1',
        'routing_order' => '1',
        'tabs' => new Tabs(['sign_here_tabs' => $signHereTabs]),
    ]);

    $recipients = new Recipients(['signers' => [$signer]]);

    // 创建信封定义
    $envelopeDefinition = new EnvelopeDefinition([
        'documents' => $documents,
        'recipients' => $recipients,
        'email_subject' => "Please sign the documents",
        'status' => "sent",
    ]);

    return $envelopeDefinition;
}

修复方案2：保留CompositeTemplate结构（适用于需结合模板的场景） #

如果业务必须使用CompositeTemplate，可通过sequence控制执行顺序，先添加所有文档，再统一应用收件人配置，避免重复定义收件人。

修改后的代码：

private function buildEnvelope($envelopeFiles, $user): EnvelopeDefinition 
{
    $recipientEmail = $user->email; 
    $recipientName = $user->first_name . " " . $user->last_name; 
   
    $compositeTemplates = [];
    $signHereTabs = [];

    // 1. 先创建所有文档的CompositeTemplate
    foreach ($envelopeFiles as $index => $documentPath) {
        $fileContent = file_get_contents($documentPath);
        $fileName = pathinfo($documentPath, PATHINFO_BASENAME);
        $fileExtension = pathinfo($documentPath, PATHINFO_EXTENSION);
        $documentId = $index + 1;

        $document = new Document([
            'document_base64' => base64_encode($fileContent),
            'name' => $fileName,
            'file_extension' => $fileExtension,
            'document_id' => $documentId,
        ]);

        // 收集当前文档的签名字段
        $signHereTabs[] = new SignHere([
            'document_id' => $documentId,
            'page_number' => 1,
            'recipient_id' => '1',
            'anchor_string' => 'Initials',
            'tab_label' => "Sign_Doc_{$documentId}",
            'anchor_x_offset' => '40',
            'anchor_y_offset' => '0',
        ]);

        // 添加仅包含文档的CompositeTemplate
        $compositeTemplates[] = new CompositeTemplate([
            'sequence' => $index + 1,
            'document' => $document,
        ]);
    }

    // 2. 创建包含收件人配置的CompositeTemplate（最后执行）
    $signer = new Signer([
        'email' => $recipientEmail,
        'name' => $recipientName,
        'recipient_id' => '1',
        'routing_order' => '1',
        'tabs' => new Tabs(['sign_here_tabs' => $signHereTabs]),
    ]);

    $recipients = new Recipients(['signers' => [$signer]]);
    $inlineTemplate = new InlineTemplate([
        'sequence' => count($envelopeFiles) + 1,
        'recipients' => $recipients,
    ]);

    $compositeTemplates[] = new CompositeTemplate([
        'inline_templates' => [$inlineTemplate],
    ]);

    // 3. 创建信封定义
    $envelopeDefinition = new EnvelopeDefinition([
        'composite_templates' => $compositeTemplates,
        'email_subject' => "Please sign the documents",
        'status' => "sent",
    ]);

    return $envelopeDefinition;
}

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