Docusign REST API单文档多签署人签署异常问题咨询

可行性确认 #

你的需求完全可实现，单个Docusign信封（Envelope）默认支持最多500个不同签署人在同一份文档上填写独立内容，不存在单信封仅对应一个签署人的限制，Envelope ID是整个签署流程的唯一标识，和签署人数量无关。

问题根源 #

你当前出现的签署人权限异常、字段自动填充问题完全由代码逻辑和模板配置不匹配导致，具体问题如下：

• 所有签署人使用了相同的RoleName：你代码中循环创建TemplateRole时，所有对象的RoleName都设为了固定值Signatory。Docusign的模板角色和签署人是一一对应的，如果你后台模板只配置了1个Signatory角色，所有重名的签署人配置会被系统识别为同一个签署人的重复提交，后续的签署人会被默认授予只读权限。
• 未给每个签署人设置唯一的recipientId：Docusign依靠唯一的recipientId区分不同收件人，你未手动赋值的前提下，系统会给所有重名角色分配相同的默认id，导致字段权限、签署位置的匹配完全混乱。
• 模板字段未对应多角色配置：你的Docusign模板中所有可编辑字段、签署位置仅绑定了第一个Signatory角色，没有为其他签署人预留对应角色的可编辑区域，所以后续签署人看不到自己的输入位置，首个签署人填写的内容会自动同步到所有同角色绑定的字段上。

修复步骤 #

1. 调整Docusign后台模板配置：按你业务需要的最大签署人数量，创建对应数量的独立角色，例如Signatory1、Signatory2、Signatory3等，每个角色对应的签署位置、可编辑字段单独配置，确保每个字段仅绑定到对应角色。
2. 修改代码逻辑，调整后的代码参考如下：

private def makeEnvelope(contacts: List[Contact], accountInfo: AccountInfo, leadId:Int, whichForm:FORMTYPE) = {
  val env = new EnvelopeDefinition
  val eventNotification = new EventNotification
  
  eventNotification.setUrl(callbackURL) // 为保护隐私使用虚拟变量名
  env.setTemplateId(templateId)

  eventNotification.setRequireAcknowledgment("true")
  eventNotification.setIncludeDocuments("true")
  eventNotification.setLoggingEnabled("true")
  var envelopeEvents : List[EnvelopeEvent]= List.empty[EnvelopeEvent]
  val envelopeEvent = new EnvelopeEvent
  envelopeEvent.setEnvelopeEventStatusCode("completed")
  envelopeEvent.setIncludeDocuments("true")
  envelopeEvents = envelopeEvent :: envelopeEvents
  eventNotification.setEnvelopeEvents(envelopeEvents.asJava)
  env.setEventNotification(eventNotification)

  var signerList = List[TemplateRole]()
  // 改动点：循环时用索引为每个签署人分配唯一的roleName和recipientId
  for((contact, index) <- contacts.zipWithIndex) {
    val signer = new TemplateRole
    val signEmail = contact.email
    val roleIndex = index + 1 // 从1开始和模板角色名匹配

    signer.setEmail(signEmail)
    signer.setName(contact.fullName)
    // 分配唯一角色名，和你模板配置的角色名对应
    signer.setRoleName(s"Signatory$roleIndex")
    // 分配唯一收件人ID
    signer.setRecipientId(roleIndex.toString)

    val showAddress: Boolean = contacts.length == 1
    // tabs为CRM导出的映射数据，用于用户签署Docusign表单时预填充内容
    val tabs = populateFormData(accountInfo, contact, whichForm, showAddress)
    signer.setTabs(tabs)

    signerList = signer :: signerList
  }

  env.setTemplateRoles(signerList.asJava)
  env.setStatus("sent")
  env
}

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