如何使用DocuSign API填充文档字段？预填失败问题排查

1. 转换后字段的tabLabel格式不匹配 #

当设置transformPdfFields: true时，DocuSign会将Adobe Acrobat创建的原生PDF表单字段转换为自身标签，此时生成的tabLabel会自动添加PDF.前缀，格式为PDF.<原Acrobat字段名>。你当前请求中直接使用tabLabel: "dealer_name"，和转换后的实际标签名不匹配，导致无法定位字段。

需要将tabLabel修改为PDF.dealer_name。

2. 字段未与目标签署者绑定 #

即使字段被正确识别，若未明确指定该字段属于目标签署者，预填值也无法生效。可以在textTabs对象中添加recipientId字段，明确关联到对应签署者的ID（此处为1）。

3. 验证原生PDF字段的真实名称 #

部分情况下，Adobe Acrobat中的字段可能包含嵌套层级（比如属于某个表单容器），实际字段名可能是form1[0].page1[0].dealer_name[0]这类格式。你可以通过以下方式确认：

• 调用DocuSign API的GET /envelopes/{envelopeId}/documents/{documentId}/fields接口，获取文档的完整字段列表
• 或在DocuSign控制台上传文档后，查看字段详情获取正确的tabLabel或originalTabId

如果使用originalTabId匹配原生字段，textTabs可改为：

{
  "originalTabId": "dealer_name",
  "value": "John",
  "recipientId": "1"
}

修正后的完整请求示例 #

{
  "documents": [{
    "documentId": 101,
    "documentBase64": "{{document}}",
    "name": "new",
    "fileExtension": "pdf",
    "transformPdfFields": true
  }],
  "emailSubject": "Test Sign",
  "recipients": {
    "signers": [{
      "email": "myself@gmail.com",
      "name": "Abhay",
      "recipientId": 1,
      "tabs": {
        "textTabs": [
          {
            "tabLabel": "PDF.dealer_name",
            "value": "John",
            "recipientId": "1"
          }
        ]
      }
    }]
  },
  "status": "sent"
}

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