在含两位签署人的DocuSign信封中使用PdfFormField填充失败求排查

首先看你提供的JSON，最核心的问题是结构嵌套错误，这直接导致DocuSign无法正确解析你的字段配置，另外还有几个细节问题需要调整：

1. 致命结构错误：嵌套的recipients属性 #

你在documents数组的单个document对象里又嵌套了一层recipients，这完全不符合DocuSign Envelopes API的规范——recipients必须是和documents同级的顶层属性，你现在重复定义了两次recipients，这会让API混淆，直接忽略掉你在document里配置的textTabs。

2. 细节问题：字段命名与位置错误 #

• 你写的firstname应该是firstName（DocuSign API对驼峰大小写敏感，小写的firstname会导致签署人信息解析异常）；
• 手动添加的textTabs没有放在顶层对应签署人的tabs下，导致字段无法关联到正确的签署人。

修正后的JSON示例 #

{
  "emailSubject": "Dummy",
  "status": "sent",
  "documents": [
    {
      "documentId": "1",
      "name": "dummy.pdf",
      "documentBase64": "...",
      "transformPdfFields": "true"
    }
  ],
  "recipients": {
    "signers": [
      {
        "recipientId": "1",
        "roleName": "buyer",
        "firstName": "Firstname",
        "lastName": "Lastname",
        "email": "email@gmail.com",
        "routingOrder": 1,
        "tabs": {
          "textTabs": [
            {
              "documentId": "1",
              "pageNumber": "1",
              "tabLabel": "acq-civ",
              "value": "aaaaaaaaaaaaaa",
              "required": "true"
            }
          ]
        }
      },
      {
        "recipientId": "2",
        "roleName": "owner",
        "name": "Full Name2",
        "email": "email2@gmail.com",
        "routingOrder": 2
      }
    ]
  }
}

额外排查要点 #

• PDF表单字段匹配：确保你PDF里的表单字段名称和tabLabel完全一致（大小写敏感），如果开启了transformPdfFields: "true"，DocuSign会自动将PDF表单转为标签，你手动添加的textTab会覆盖同名的自动转换字段；
• Base64编码验证：确认documentBase64没有截断或编码错误，这会导致PDF无法正常加载，字段自然无法填充；
• API返回错误：如果调用还是失败，一定要查看DocuSign返回的错误响应——API会明确指出问题（比如字段不存在、结构错误等），这是最快的排查方式；
• 权限验证：确保你的API账号有足够权限进行表单字段转换操作，部分受限账号可能无法使用transformPdfFields功能。

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