DocuSign信封状态问题：如何保留待处理状态补充第三方签署人信息

问题根源 #

你当前的问题是因为DocuSign在创建信封时，第三个模板角色缺少姓名和邮箱，系统会默认该角色不需要参与签署流程，所以前两个签署人完成后，信封直接进入「已完成」状态，无法再编辑补充第三个角色的信息。

具体解决方法 #

方法一：先创建草稿信封，补充信息后再发送

将信封状态设置为created（草稿），此时信封不会触发签署流程。等确定第三个角色的信息后，先更新该角色的姓名和邮箱，再将信封状态改为sent启动签署。

修改创建信封的代码：

const envelope = await envelopesApi.createEnvelope(accountId, {
  envelopeDefinition: {
    templateId: templateId,
    status: 'created', // 改为草稿状态
    emailSubject: `Signing template ID: ${templateId}`,
    templateRoles: [
      { 
        roleName: args.firstRole, 
        name: args.firstSignerName, 
        email: args.firstSignerEmail, 
        clientUserId: firstRoleId 
      },
      { 
        roleName: args.secondRole, 
        name: args.secondSignerName, 
        email: args.secondSignerEmail, 
        clientUserId: secondRoleId 
      },
      { 
        roleName: args.thirdRole, 
        clientUserId: thirdRoleId 
      }
    ],
  }
})

后续补充第三个角色并发送信封：

// 更新第三个角色的姓名和邮箱
await envelopesApi.updateRecipients(accountId, envelope.envelopeId, {
  recipients: {
    signers: [
      {
        roleName: args.thirdRole,
        name: '实际签署人姓名',
        email: 'actual_signer@example.com',
        clientUserId: thirdRoleId,
        recipientId: '3' // 需匹配模板中该角色的recipientId，系统也会自动分配
      }
    ]
  }
})

// 正式发送信封，触发签署流程
await envelopesApi.update(accountId, envelope.envelopeId, {
  envelope: { status: 'sent' }
})

方法二：用占位收件人临时填充，后续替换

创建信封时给第三个角色设置临时的占位信息，同时标记为可编辑。此时信封可直接设为sent，前两个签署人完成后，系统会因为存在未签署的占位角色而保持信封活跃状态，你可以随时更新该角色的真实信息。

修改第三个角色的代码：

{ 
  roleName: args.thirdRole, 
  name: '待补充签署人',
  email: 'placeholder@example.com',
  clientUserId: thirdRoleId,
  editable: true // 允许后续编辑该收件人信息
}

后续更新真实签署人信息：

await envelopesApi.updateRecipients(accountId, envelope.envelopeId, {
  recipients: {
    signers: [
      {
        roleName: args.thirdRole,
        name: '实际签署人姓名',
        email: 'actual_signer@example.com',
        clientUserId: thirdRoleId,
        recipientId: '3'
      }
    ]
  }
})

注意事项 #

• 确保第三个角色的roleName与模板中的角色名称完全一致，否则无法关联到模板角色。
• 使用updateRecipients接口时，必须保证信封状态不是「已完成」，方法一的草稿模式更稳妥；方法二要注意在前两个签署人完成后，信封仍因占位角色处于活跃状态才能更新。

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