DocuSign API预填充问题：同标签只读TextTabs仅最后一个字段被填充

这个问题我之前帮人排查过，核心原因是DocuSign API对同标签字段的默认匹配逻辑导致的——当你只传递一个带目标tabLabel的TextTab条目时，系统会默认把值只应用到文档中最后一个匹配该标签的字段（按渲染顺序），它默认认为同标签字段是冗余的，而非需要批量填充的重复内容。

下面给你两个可靠的解决方案：

方案一：通过tabId精准定位每个字段（推荐） #

这是最稳妥的方法，因为每个字段都有唯一的tabId，不会出现匹配错误。步骤如下：

1. 先调用DocuSign的模板详情API（GET /templates/{templateId}），获取模板中所有文本字段的信息，从中提取出所有tabLabel为CandidateName的字段对应的tabId。
2. 在创建信封的API请求中，为每个tabId单独创建一个TextTab对象，设置相同的value即可。

示例JSON请求片段：

"recipients": {
  "signers": [
    {
      "email": "signer@example.com",
      "name": "Signer Name",
      "recipientId": "1",
      "tabs": {
        "textTabs": [
          {
            "tabId": "abc123", // 第一个CandidateName字段的tabId
            "value": "Alex Smith",
            "readOnly": true
          },
          {
            "tabId": "def456", // 第二个CandidateName字段的tabId
            "value": "Alex Smith",
            "readOnly": true
          },
          {
            "tabId": "ghi789", // 第三个CandidateName字段的tabId
            "value": "Alex Smith",
            "readOnly": true
          }
        ]
      }
    }
  ]
}

方案二：为每个字段创建带位置信息的TextTab条目 #

如果暂时无法获取tabId，可以通过指定字段的pageNumber、xPosition、yPosition结合tabLabel来区分不同字段。不过这种方法要注意，如果文档布局有变动，位置信息会失效，所以不如方案一可靠。

示例JSON请求片段：

"textTabs": [
  {
    "tabLabel": "CandidateName",
    "value": "Alex Smith",
    "readOnly": true,
    "pageNumber": "1",
    "xPosition": "100",
    "yPosition": "200"
  },
  {
    "tabLabel": "CandidateName",
    "value": "Alex Smith",
    "readOnly": true,
    "pageNumber": "2",
    "xPosition": "100",
    "yPosition": "200"
  }
]

另外补充一点：你设置字段为非必填且只读是没问题的，API填充不受这个限制，问题完全出在同标签字段的匹配逻辑上，按上面的方法调整后就能实现所有同标签字段都被填充。

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