使用DocuSign模板创建信封时修改收件人致重复收件问题

问题根源 #

你遇到的重复收件人问题，核心在于DocuSign Composite Template的收件人合并规则：只有当两个收件人的邮箱、姓名、路由顺序完全一致时，系统才会自动合并为一个收件人。你修改了邮箱/姓名后，原模板收件人和修改后的收件人不再满足合并条件，因此系统会将两者都加入信封，导致重复发送。

解决方案 #

针对你的需求，有两种可行方案：

方案1：完全替换原模板所有收件人 #

如果你需要替换模板中的全部收件人，直接在recipients对象中添加deleteExistingRecipients: true，这会清除原模板中的所有收件人，只保留你定义的修改后收件人。

修改你的serializeUpdateRecipients方法：

private serializeUpdateRecipients(signers: Signer[]) {
    // @ts-expect-error Docusign @types are not up to date
    const recipients = new docusign.Recipients();
    recipients.deleteExistingRecipients = true; // 新增此行，删除原模板收件人
    recipients.signers = signers.map(({ name, email, tabs, roleName, recipientId, routingOrder }) => (
        // @ts-expect-error Docusign @types are not up to date
        new docusign.Signer.constructFromObject({
            email,
            name,
            roleName,
            recipientId,
            routingOrder,
            tabs,
        })
    ));
    return recipients;
}

方案2：仅替换指定收件人（保留其他原收件人） #

如果你只想修改部分收件人，同时保留模板中的其他收件人，只需在EnvelopeDefinition中添加mergeRolesOnDraft: true，系统会根据recipientId或roleName匹配合并收件人——即使邮箱/姓名改变，只要recipientId和原模板一致，就会替换原收件人而非新增。

修改信封定义代码：

// @ts-expect-error exists
const envelopeDefinition = docusign.EnvelopeDefinition.constructFromObject({
    status: "sent",
    compositeTemplates: [compositeTemplate],
    mergeRolesOnDraft: true // 新增此行，启用按ID/角色合并收件人
})

补充说明 #

• 方案1适合需要完全替换所有收件人的场景，操作简单直接；
• 方案2适合只修改部分收件人的场景，需确保你修改的收件人recipientId与原模板完全一致（你当前代码已经满足这一点）。

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