Docusign模板设置疑问：同角色不同收件人UI报错但API可创建

UI与API的校验逻辑差异 #

DocuSign的UI和API在收件人唯一性校验上存在明确区别：

• UI端校验：
  • 当模板中存在相同角色名称的收件人时，UI会默认将其视为同一角色的重复实例，自动同步姓名、邮箱等信息，并强制要求同一签署顺序下的收件人必须唯一（即邮箱/姓名组合不能重复），这就是触发Each recipient in the signing order must be unique错误的原因。
  • UI的设计逻辑更偏向引导用户创建“单角色多实例”的标准模板场景，而非允许同一角色名对应不同身份的收件人。
• API端校验：
  • API的校验逻辑更灵活，它通过**收件人ID（recipientId）**来唯一识别每个收件人，而非依赖角色名称、姓名或邮箱。
  • 只要为每个收件人分配了唯一的recipientId，即使角色名称相同、签署顺序一致，且姓名/邮箱不同，API也会允许创建这样的模板。

收件人唯一性的底层识别规则 #

DocuSign系统判断收件人唯一性的优先级如下：

1. 收件人ID（recipientId）：这是API层面的核心唯一标识，每个收件人必须拥有独一无二的recipientId，无论其他属性是否重复。
2. 邮箱地址+姓名组合：在UI场景下，当角色名称相同时，系统会通过邮箱+姓名的组合判断是否为同一收件人，不允许同一签署顺序下出现重复组合。
3. 角色名称：仅当角色名称不同时，UI才允许同一签署顺序下存在不同的收件人（即使邮箱/姓名重复，但这种场景不推荐）。

场景适配建议 #

如果需要保留“同角色名、不同身份收件人”的模板设置：

• 可通过API持续维护该模板，API支持这种灵活配置。
• 若必须通过UI修改，建议为两个收件人设置不同的角色名称（比如在原角色名后加后缀，如Approver_1和Approver_2），再分别配置姓名、邮箱和签署顺序，即可绕过UI的校验限制。

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