创建Envelope时为签署人预填充自定义字段失败，求解决方案

我有一个包含单份文档的模板，文档内设有多个需为每位签署人填充不同内容的字段（如company_name、signer_name）。目标是创建信封（Envelope）时为签署人预填充字段：

• 签署人1：company_name赋值"Alice's company"，signer_name赋值"Alice"
• 签署人2：company_name赋值"Bob's company"，signer_name赋值"Bob"

我调用DocuSign API创建信封，请求端点为：

/restapi/v2.1/accounts/{accountId}/envelopes

请求体如下：

{
  "emailSubject": "Email Subject",
  "templateId": "my-template-id",
  "status": "sent",
  "customFields": {
    "textCustomFields": [
      {
        "fieldId": "10851848897",
        "name": "company_name",
        "required": "true",
        "show": "true",
        "value": "Alice's company"
      },
      {
        "fieldId": "10851848898",
        "name": "signer_name",
        "required": "true",
        "show": "true",
        "value": "Alice"
      }
    ]
  },
  "templateRoles": [
    {
      "email": "alice@maildomain.com",
      "emailNotification": {
        "emailBody": "email body",
        "emailSubject": "email subject",
        "supportedLanguage": "en"
      },
      "roleName": "signer",
      "routingOrder": "1"
    }
  ]
}

但Alice收到签署链接后，文档字段未被预填充。调用以下端点获取文档字段列表：

/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/documents/{documentId}/fields

返回空结果：

{
    "documentFields": []
}

问题核心是你将模板字段的预填充值放在了customFields中——这是信封级全局自定义字段，和模板内绑定签署角色的字段无关。正确做法是将预填充值放在templateRoles对应角色对象的tabs属性里。

修正后的请求体 #

{
  "emailSubject": "Email Subject",
  "templateId": "my-template-id",
  "status": "sent",
  "templateRoles": [
    {
      "email": "alice@maildomain.com",
      "emailNotification": {
        "emailBody": "email body",
        "emailSubject": "email subject",
        "supportedLanguage": "en"
      },
      "roleName": "signer",
      "routingOrder": "1",
      "tabs": {
        "textTabs": [
          {
            "tabLabel": "company_name",
            "value": "Alice's company"
          },
          {
            "tabLabel": "signer_name",
            "value": "Alice"
          }
        ]
      }
    },
    {
      "email": "bob@maildomain.com",
      "roleName": "signer",
      "routingOrder": "2",
      "tabs": {
        "textTabs": [
          {
            "tabLabel": "company_name",
            "value": "Bob's company"
          },
          {
            "tabLabel": "signer_name",
            "value": "Bob"
          }
        ]
      }
    }
  ]
}

关键注意事项 #

1. 字段与角色绑定：模板内创建的company_name、signer_name字段必须关联到对应的签署角色（如signer），否则预填充值无法匹配到字段。
2. 用tabLabel匹配字段：textTabs中通过tabLabel对应模板字段的标签名（也可使用tabId，但tabLabel更易维护）。
3. 移除无效的customFields：该属性用于信封全局自定义字段，和文档内签署字段无关，无需保留。

验证方式 #

重新创建信封后，调用获取文档字段的API即可看到已填充的字段值；签署人打开链接时，文档字段会显示预填充内容。

内容的提问来源于stack exchange，提问作者Игорь