DocuSign通过API创建信封时模板收件人覆盖未生效问题咨询

结论 #

你观测到的行为不属于DocuSign的设计预期，属于参数缺失导致的匹配异常，正常设计下传入匹配的角色参数会直接覆盖模板预设的收件人信息，而非新增收件人。

异常原因 #

• 要匹配模板中的预设角色完成信息覆盖，请求templateRoles数组的单条对象需要同时和模板的roleName、routingOrder两个字段完全一致，你当前的请求仅传入了roleName: "Scientist"，未携带和模板匹配的签署顺序参数routingOrder: 4，DocuSign无法定位到要覆盖的目标角色，就会将传入的收件人判定为新增角色，默认分配签署顺序1。
• 若确认两个参数都匹配仍出现异常，可检查模板的Scientist角色是否被设置为「锁定收件人信息，不允许通过API修改」，该配置会禁止API覆盖角色信息，不过这种情况不会触发新增收件人，只会保留原有预设信息。

修复示例 #

调整后的请求payload中Scientist角色部分补充routingOrder字段即可：

{
   "status": "sent",
   "templateId": "...",
   "templateRoles": [
      {
         "email": "...",
         "name": "...",
         "roleName": "....",
         "routingOrder": "..."
      },
      {
         "email": "newton@fma.com",
         "name": "Isaac Newton",
         "roleName": "Scientist",
         "routingOrder": 4
      }
   ]
}

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