DocuSign API问题：使用模板创建信封时模板角色未合并

我之前也碰到过一模一样的问题，折腾了好一阵才找到根源，给你梳理下可能的原因和对应的解决办法：

常见原因 #

• 角色名称匹配不精确：DocuSign对roleName的匹配是大小写敏感且会识别所有字符（包括隐形空格、全角符号等）。哪怕模板里的角色是Role_01而你请求里写的是role_01，或者模板角色名称末尾多了一个空格，都会导致匹配失败，最终DocuSign会认为你要新增一个角色，而不是替换模板里的现有角色。
• 模板角色的特殊配置：如果模板里的角色被设置为“不可修改”或者关联了特定的收件人组，可能会导致API请求无法替换该角色的信息，反而触发新增逻辑。
• 请求字段干扰：虽然你的请求看起来没问题，但如果不小心额外添加了recipientId字段，且该ID和模板角色的内部ID不匹配，也会导致DocuSign创建新收件人而非合并现有角色。

解决步骤 #

1. 精确复制角色名称：直接从DocuSign控制台的模板编辑页面，复制角色的名称（比如选中role_01右键复制），粘贴到请求的roleName字段中，彻底避免手动输入的拼写或格式错误。
2. 验证模板角色的API数据：调用DocuSign的模板详情API（GET /templates/{templateId}），查看返回结果中roles数组里的name字段，确保和你请求里的roleName完全一致（包括大小写、空格）。
3. 检查模板角色设置：进入模板编辑页面，确认目标角色没有被设置为“锁定收件人”或关联了固定收件人，确保角色是可被API替换的状态。
4. 简化请求结构：暂时移除请求中不必要的字段，只保留email、name、roleName这三个核心字段，排除其他字段的干扰。

举个修正后的请求示例（确保roleName和模板完全一致）：

{ 
  "emailSubject":"Example Email", 
  "status":"created", 
  "templateId":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", 
  "templateRoles":[{ 
    "email":"john.doe@gmail.com", 
    "name":"John Doe", 
    "roleName":"Role_01"  // 这里要和模板角色名称完全匹配
  }] 
}

按照上面的步骤排查，基本就能解决角色未合并的问题了。

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