关于DocuSign API中Tabs与自定义字段的区别及填充400错误问询

嘿，我来帮你理清DocuSign里Tabs和自定义字段（Custom Fields）的核心区别，再解决你遇到的400错误问题～

先把这两个概念掰明白，避免混淆：

• 作用与呈现方式：
  • Tabs是文档上的交互式可视化元素，比如签名框、日期输入框、文本填写框这些，直接显示在文档页面上，供签署人或发件人手动填写/操作，位置固定在文档的某个坐标点。
  • 自定义字段是信封/文档的后台元数据，默认不会显示在文档上（除非你通过特定配置把它的值映射到文档的Tabs里），更像是用来存储附加信息的「隐形标签」，比如订单号、客户ID这类用于系统追踪、后续查询的内容。
• 使用场景：
  • 需要签署人在文档可见位置填写内容？用Tabs；
  • 需要存一些不需要签署人看到，但内部系统要用到的信息？用自定义字段。
• API层级差异：
  • Tabs嵌套在recipients下的对应签署人节点里（或者模板的角色配置中）；
  • 自定义字段分两种：信封级的放在请求根节点的customFields里，文档级的放在对应文档的documentFields数组中。

你说模板里已经配置了对应名称的自定义字段，但加参数后报错400，大概率是请求格式踩坑了，给你几个排查和修复方向：

1. 确认字段层级，别放错位置：
   先去模板里看清楚这个自定义字段是信封级还是文档级：
   • 信封级字段要放在请求根节点的customFields下，格式参考：

     "customFields": {
       "textCustomFields": [
         {
           "name": "你的字段名",
           "value": "要填充的内容"
         }
       ]
     }
     

   • 文档级字段要放在对应文档的documentFields数组里，格式参考：

     "documents": [
       {
         "documentId": "1",
         "documentFields": [
           {
             "name": "你的文档级字段名",
             "value": "填充内容"
           }
         ]
       }
     ]
     

2. 字段名称必须严格匹配：
   DocuSign的自定义字段名称是大小写敏感的，空格、标点都不能错，要确保请求里的name和模板里配置的完全一致。
3. 不要重复定义模板已有的字段属性：
   如果模板已经配置了这个字段的required、show等属性，你只需要在请求里给name和value赋值就行，别额外加模板里已经有的属性，不然容易触发格式错误。
4. 别把Tabs当成自定义字段来填：
   有时候会搞混——如果模板里的字段是文档上可见的输入框，那它属于Tabs，不是自定义字段，这时候要去templateRoles里的对应签署人tabs节点下赋值，而不是用customFields。

给你一个完整的示例：用模板创建信封并填充信封级自定义字段的正确请求结构

{
  "templateId": "你的模板ID",
  "templateRoles": [
    {
      "email": "signer@example.com",
      "name": "张三",
      "roleName": "签署人"
    }
  ],
  "customFields": {
    "textCustomFields": [
      {
        "name": "客户订单号",
        "value": "ORD-20240501"
      }
    ]
  },
  "status": "sent"
}

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