我在通过REST API创建并发送信封时，遇到了在DocGen（文档生成）表单字段的预填充问题。尽管尝试了多种做法，字段在文档中呈现为未解析的占位符（例如 {{Agreement Party}}、{{demo_field}}），而不是显示通过API传入的值。

API基础URL：https://demo.docusign.net/restapi/v2.1/

模板包含两个通过GET /templates/{templateId} 确认的DocGen表单字段：

• 字段标签：Agreement Party
  内部名称：AgreementParty_displayName_Z2bXgzv
  完全限定路径：com.docusign.platform@1/AgreementParty/displayName
  类型：TextBox

• 字段标签：demo_field
  内部名称：C_demo_field_value_1Xkjiv
  完全限定路径：account._771d9b65_90d3_4661_8916_9f42a88bc2eb.custom.fields@1/C_demo_field/value
  类型：TextBox

收件人角色：test_signer
收件人ID：55136564

我的尝试（均未成功）：

1. 在签署人选项卡下使用locked: true的标准textTabs
   — 字段显示为未解析的占位符 {{placeholders}}
2. 在签署人下的prefillTabs
   — 错误：INVALID_TAB_OPERATION — PrefillTab不允许用于收件人
3. 在inlineTemplates内的收件人级别使用prefillTabs
   — 字段仍显示为 {{placeholders}}
4. 在根信封级别使用prefillTabs
   — 字段仍显示为 {{placeholders}}
5. 在根级别使用docGenFormFields，带有documentId和 docGenFormFieldList
   — 字段仍显示为 {{placeholders}}

用于方案5 的示例有效负载：

{
   "emailSubject": "Please sign this contract",
   "status": "sent",
   "compositeTemplates": [ 
   {  
      "compositeTemplateId": "1",
      "serverTemplates": [
          { "sequence": "1", "templateId": "3cfaca9c-ffd5-4c16-a416-992ca05317b0" }  
      ],  
      "inlineTemplates": [
          {  
          "sequence": "2",  
          "recipients": {  
            "signers": [  
              {  
                "name": "John Doe",  
                "email": "[email protected]",  
                "recipientId": "55136564",  
                "roleName": "test_signer"  
              }  
            ]  
          }  
        }  
      ]  
    }  
  ],  
  "docGenFormFields": [  
    {  
      "documentId": "1",  
      "docGenFormFieldList": [  
        { "name": "AgreementParty_displayName_Z2bXgzv", "value": "John Doe" },  
        { "name": "C_demo_field_value_1Xkjiv", "value": "Ritik Test"   
      ]  
    }  
  ]  
}

当前信封已成功创建并发送（HTTP 201）。收件人会收到邮件并可以打开文档。然而，字段 {{Agreement Party}} 和 {{demo_field}} 仍然是文档正文中的未解析占位文本，而不是在API请求中提供的值。

我期望通过API请求提供的DocGen表单字段值在发给签署人之前就被解析并呈现为文档中的实际文本。签署人应看到预填的值（例如 "John Doe" 和 "Test"），且不应能够编辑它们。

通过REST API程序化发送信封时，预填DocGen表单字段（isAceGenDocument: true）的正确API方法是什么？或者是否存在一个必须在POST /envelopes之前调用或替代调用的单独DocGen专用API端点？

compositeTemplates方法是否支持DocGen字段解析，还是必须使用不同的信封创建方法？

是否需要在模板或账户层面进行额外配置，以通过API启用DocGen字段解析？

解决方案

要填充Document Generation字段，需要遵循一系列特定的调用顺序。

1. 将信封创建为草稿（状态为“created”，而非“sent”）
2. 调用 DocumentGeneration:getEnvelopeDocGenFormFields 以获取文档上的 docGenFormFields 列表。同时你还需要在该API调用的响应中返回的 documentId 值，以完成下一步。
3. 使用 DocumentGeneration:updateEnvelopeDocGenFormFields 根据上一步响应中指定的 docGenFormFields 将 value 更新为相应的发送方数据。
4. 通过将状态设为 sent，使用 Envelopes:update 端点来发送信封。
   你也可以查看这里的示例，详细演示了这些步骤。