使用复合模板时单选组无法预填充的技术问题咨询

我之前也踩过DocuSign复合模板预填充单选组的坑，结合API规范和实际调试经验来看，你的请求里大概率是几个关键配置没到位，导致单选组无法和模板关联上。我来帮你梳理下核心问题和修复方案：

1. 必须指定与模板匹配的groupName #

这是最容易忽略的点：DocuSign的单选组是通过groupName来关联模板中的对应控件的，你的请求里完全没这个属性，系统根本不知道要把预填充值应用到哪个单选组上。

假设你模板里的单选组名称是language_selector，修正后的请求结构应该是这样：

{
  "compositeTemplates": [
    {
      "inlineTemplates": [
        {
          "recipients": {
            "signers": [
              {
                "tabs": {
                  "radioGroupTabs": [
                    {
                      "groupName": "language_selector", // 必须和模板里的单选组名称完全一致
                      "radios": [
                        { "value": "NL", "selected": "false" },
                        { "value": "FR", "selected": "true" },
                        { "value": "EN", "selected": "false" },
                        { "value": "DE", "selected": "false" }
                      ]
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

2. 核对单选按钮的value与模板完全匹配 #

要确保请求里的value和模板中每个单选按钮设置的Value属性100%一致，包括大小写、拼写、特殊字符。比如模板里FR是大写，你就不能写成fr或者Fr，否则系统识别不到要选中哪个选项。

3. 复合模板的序列顺序要正确（如果用了服务器模板） #

如果你是结合服务器模板+内联模板的复合模板，一定要给serverTemplates和inlineTemplates设置正确的sequence值：服务器模板的序号要小于内联模板，这样内联模板的预填充设置才能覆盖/应用到服务器模板上。示例如下：

"compositeTemplates": [
  {
    "serverTemplates": [
      {
        "sequence": "1",
        "templateId": "你的服务器模板ID"
      }
    ],
    "inlineTemplates": [
      {
        "sequence": "2", // 序号大于服务器模板，确保内联配置生效
        "recipients": {
          "signers": [
            {
              "recipientId": "1", // 必须和模板里签署人的recipientId一致
              "tabs": {
                "radioGroupTabs": [
                  {
                    "groupName": "language_selector",
                    "radios": [/* ... */]
                  }
                ]
              }
            }
          ]
        }
      }
    ]
  }
]

4. 验证签署人recipientId的一致性 #

预填充的tabs是绑定到指定签署人的，所以请求里的recipientId必须和模板中对应签署人的recipientId完全匹配，否则系统会把预填充值忽略掉。

建议你先简化请求，只保留单选组的预填充配置进行测试，排除其他标签的干扰，这样更容易定位问题。

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