如何通过JWT授权生成收件人正确的DocuSign信封签署链接？

问题诊断 #

你遇到的情况是因为创建收件人视图时传入了错误参数，导致返回的是管理员视角的信封查看页，而非签署人的专属签署入口。邮件里的链接正常是因为它直接绑定了签署人的身份信息。

修正方案 #

核心改动 #

1. 删除userId参数：这个参数是DocuSign内部的用户ID，用管理员JWT身份调用时传入它，会强制切换到该用户的管理员视图，而非签署视图。
2. 添加clientUserId参数（嵌入式签署必填）：这是你系统内对签署用户的唯一标识，用来告诉DocuSign当前要生成的是该用户的专属签署链接，而非通用查看链接。

修正后的完整代码 #

// 可选：先获取签署人信息，确保和创建信封时一致
const options1 = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
    },
}
const recipients = await this.apiCall(`accounts/${process.env.DOCUSIGN_ACCOUNT_ID}/envelopes/${envelopeId}/recipients`, options1);
const targetSigner = recipients.signers[0];

// 创建正确的收件人签署视图
const options = {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        email: targetSigner.email,
        userName: targetSigner.name,
        authenticationMethod: 'email',
        returnUrl: `${process.env.FRONTEND_URL}/docusign-complete?type=${type}&cid=${consignmentId}`,
        clientUserId: `your-system-user-id-${consignmentId}` // 替换为你系统中该签署用户的唯一ID
    })
}

const signingResponse = await this.apiCall(`accounts/${process.env.DOCUSIGN_ACCOUNT_ID}/envelopes/${envelopeId}/views/recipient`, options);
// signingResponse.url 就是正确的终端用户签署链接

关键注意事项 #

• 确保email和userName与创建信封时指定的签署人信息完全一致，否则DocuSign无法匹配到对应的签署任务。
• 如果是让用户在你的应用内完成签署（嵌入式场景），clientUserId是必填项；如果是跳转到DocuSign官网签署，也建议保留该参数以避免身份混淆。
• 不要使用管理员的userId，必须用签署人的身份信息（邮箱+姓名）来绑定视图。

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