使用DocuSign PHP API从模板创建信封并添加自定义文档失败求助

我之前也碰到过一模一样的问题，你的核心问题出在文档更新的方式上：当你调用EnvelopesApi->update()并设置setDocuments()时，DocuSign API会直接替换信封里现有的所有文档，而不是追加新文档。这就是为什么两种流程都只保留了其中一类文档的原因。

下面给你两种可行的解决方案，按需选择：

方案一：创建信封时同时包含模板和自定义文档 #

这是最直接的方式，在初始创建信封的EnvelopeDefinition里，同时指定模板和自定义文档，这样DocuSign会把两者合并到同一个信封中。

需要注意：

• 自定义文档的DocumentId不能和模板里的文档ID重复（模板里的文档ID通常从1开始，你可以给自定义文档设为2、3这类新ID）
• 要把信封状态设置为sent，确保创建后直接发送

修改后的代码示例：

public function send($signer_name,$signer_email, $cc_name, $cc_email, $template_id,$email_subject, $extrapdf = null) { 
    $this->checkToken(); 

    $sign_here = new \DocuSign\eSign\Model\SignHere([ 
        'anchor_string' => '/sn1/', 
        'anchor_units' => 'pixels', 
        'anchor_y_offset' => '10', 
        'anchor_x_offset' => '20'
    ]); 

    // 创建签署角色
    $templateRole = new DocuSign\eSign\Model\TemplateRole(); 
    $templateRole->setEmail($signer_email); 
    $templateRole->setName($signer_name); 
    $templateRole->setRoleName('Signer 1'); 
    $templateRole->setTabs(new \DocuSign\eSign\Model\Tabs(['sign_here_tabs' => [$sign_here]])); 

    $templateRole2 = new DocuSign\eSign\Model\TemplateRole(); 
    $templateRole2->setEmail($cc_email); 
    $templateRole2->setName($cc_name); 
    $templateRole2->setRoleName('Signer 2'); 
    $templateRole2->setTabs(new \DocuSign\eSign\Model\Tabs(['sign_here_tabs' => [$sign_here]])); 

    // 创建信封定义
    $envelop_definition = new DocuSign\eSign\Model\EnvelopeDefinition(); 
    $envelop_definition->setTemplateId($template_id); 
    $envelop_definition->setEmailSubject($email_subject); 
    $envelop_definition->setTemplateRoles(array($templateRole, $templateRole2)); 

    // 如果有自定义PDF，直接添加到信封定义中
    if ($extrapdf != null) { 
        $extrapdf64 = base64_encode($extrapdf); 
        $document = new DocuSign\eSign\Model\Document(); 
        $document->setDocumentBase64($extrapdf64); 
        $document->setName("HomeownershipCounseling.pdf"); 
        $document->setDocumentId("2"); // 用和模板文档不重复的ID
        $document->setFileExtension("PDF"); 

        // 将自定义文档添加到信封的文档列表中
        $envelop_definition->setDocuments([$document]); 
    }

    // 设置信封状态为已发送
    $envelop_definition->setStatus('sent'); 

    // 创建并发送信封
    $envelopeApi = new DocuSign\eSign\Api\EnvelopesApi(self::$apiClient); 
    $results = $envelopeApi->createEnvelope(self::$accountID, $envelop_definition); 

    return $results; 
}

方案二：先创建草稿信封，再追加自定义文档 #

如果你必须分步骤操作（比如先创建模板信封，后续再添加文档），可以先把信封创建为created状态（草稿），然后用DocumentsApi->createDocument()方法追加文档，最后再更新信封状态为sent。

关键代码片段：

// 1. 创建草稿信封（状态设为created，不发送）
$envelop_definition->setStatus('created'); 
$results = $envelopeApi->createEnvelope(self::$accountID, $envelop_definition); 
$envelopeId = $results['envelope_id'];

// 2. 追加自定义文档
if ($extrapdf != null) {
    $extrapdf64 = base64_encode($extrapdf); 
    $document = new DocuSign\eSign\Model\Document(); 
    $document->setDocumentBase64($extrapdf64); 
    $document->setName("HomeownershipCounseling.pdf"); 
    $document->setDocumentId("2"); 
    $document->setFileExtension("PDF"); 

    $documentsApi = new DocuSign\eSign\Api\DocumentsApi(self::$apiClient);
    $documentsApi->createDocument(self::$accountID, $envelopeId, $document);
}

// 3. 更新信封状态为已发送
$updateDefinition = new \DocuSign\eSign\Model\EnvelopeDefinition();
$updateDefinition->setStatus('sent');
$results = $envelopeApi->update(self::$accountID, $envelopeId, $updateDefinition);

额外注意事项 #

• 确认模板中的文档ID：如果不确定模板里的文档ID，可以调用EnvelopesApi->listDocuments()查询已创建信封的文档列表，避免ID冲突
• 自定义文档的Base64编码要确保正确，不要包含多余的换行或空格
• 如果需要给自定义文档添加签署标签，可以在创建文档时一并设置，或者后续用TabsApi添加

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