使用DocuSign API创建信封时如何为无recipientId的prefillTabs组选项卡预填值？

prefillTabs的设计属性就是不属于任何签署人、无关联recipientId，本身就无法通过绑定收件人角色的templateRoles渠道赋值，这是接口设计的分层逻辑导致的常规现象，并非操作错误。实际可落地的赋值方式有两种：

方式一：创建信封时直接在信封层级写入预填值 #

• 不需要将prefillTabs配置嵌套在任何收件人、templateRole实体下，直接把prefillTabs节点放在EnvelopeDefinition的顶级层级即可
• 提交时需要保证每个预填控件的tabLabel和模板中预先配置的prefillTabs标签完全匹配，同时补充控件所在的documentId、pageNumber信息，确保接口能定位到对应模板内的预填控件
• 参考的请求结构示例：

{
  "emailSubject": "待签署文档",
  "templateId": "关联的模板ID",
  "status": "created",
  "prefillTabs": {
    "textTabs": [
      {
        "tabLabel": "客户姓名预填位",
        "value": "张三",
        "documentId": "1",
        "pageNumber": "1"
      }
    ],
    "dateTabs": [
      {
        "tabLabel": "生成日期预填位",
        "value": "2024-06-01",
        "documentId": "1",
        "pageNumber": "1"
      }
    ]
  }
}

方式二：复合模板场景下通过inlineTemplate注入配置 #

• 当需要同时引用已有模板、叠加自定义信封配置时，不要把prefillTabs放在serverTemplates节点内，要在对应的inlineTemplate层级下写入prefillTabs配置
• 该场景下同样不需要给prefillTabs关联任何收件人角色，配置会直接注入到信封维度的预填控件集合中

常见踩坑提醒 #

• 不要强制给prefillTabs节点补充recipientId属性，这类控件天生不绑定收件人，补充该字段会触发接口校验报错
• 如果使用的是较早的V2版本API，创建信封场景下的直传prefillTabs能力可能存在兼容性限制，此时可以先创建草稿状态的信封，再单独调用信封资源下的prefillTabs更新接口完成赋值
• 预填值提交后，所有后续打开信封的签署人都能看到这些预填位的内容，这类控件不会标记为“待填写”状态，不会触发任何签署人的填写动作

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