DocuSign遇WITNESS_FOR_SIGNER_ID_INVALID错误，如何创建含需见证可选收件人的信封？

问题根源 #

错误WITNESS_FOR_SIGNER_ID_INVALID是因为模板中强制绑定了见证关系，但创建信封时未提供对应见证收件人导致的。要实现第二名收件人可选，需从模板配置和API请求构建两方面调整。

解决方案步骤 #

1. 模板配置调整 #

• 登录DocuSign控制台打开目标模板，找到第二名收件人角色：
  • 将该角色设置为允许跳过（勾选「Allow recipient to skip」选项），确保模板不会强制要求该收件人存在。
  • 移除模板中预设的强制见证关联（如果有的话），改为通过API动态指定见证关系，避免模板层面的硬性校验。

2. API请求（CompositeTemplates）动态处理 #

在构建CompositeTemplates时，根据业务需求决定是否添加可选见证收件人，核心是仅在需要时才将该收件人加入Recipients列表：

// 初始化CompositeTemplate，关联目标模板
var compositeTemplate = new CompositeTemplate
{
    ServerTemplates = new List<ServerTemplate>
    {
        new ServerTemplate
        {
            TemplateId = "你的模板ID",
            Sequence = "1"
        }
    },
    InlineTemplates = new List<InlineTemplate>
    {
        new InlineTemplate
        {
            Sequence = "2",
            Recipients = new Recipients
            {
                Signers = new List<Signer>
                {
                    new Signer
                    {
                        RoleName = "主签署人",
                        Email = "signer1@example.com",
                        Name = "签署人1",
                        RecipientId = "1"
                    }
                }
            }
        }
    }
};

// 按需添加可选见证收件人
bool needWitness = false; // 根据业务逻辑设置是否需要见证人
if (needWitness)
{
    compositeTemplate.InlineTemplates[0].Recipients.Witnesses = new List<Witness>
    {
        new Witness
        {
            RoleName = "可选见证人",
            Email = "witness@example.com",
            Name = "见证人姓名",
            RecipientId = "4", // 需与模板中该角色的ID一致
            WitnessFor = "1" // 关联主签署人的RecipientId
        }
    };
}

var compositeTemplates = new List<CompositeTemplate> { compositeTemplate };

// 创建信封的原有代码保持不变
EnvelopeDefinition env = new EnvelopeDefinition {
   CompositeTemplates = compositeTemplates, 
   Status = "created"
};

var apiClient1 = new ApiClient(acct.BaseUri + "/restapi");
apiClient1.Configuration.DefaultHeader.Add("Authorization", "Bearer " + accessToken.access_token);
EnvelopesApi envelopesApi = new EnvelopesApi(apiClient1);
EnvelopeSummary results = envelopesApi.CreateEnvelope(acct.AccountId, env, new EnvelopesApi.CreateEnvelopeOptions { mergeRolesOnDraft= "true"});

关键注意事项 #

• 确保模板中可选见证角色的「允许跳过」选项已开启，否则即使API中不添加该收件人，模板仍会触发强制校验。
• 当添加见证收件人时，RecipientId必须与模板中该角色的ID匹配（错误信息中提到的recipient id =4即对应此值），WitnessFor需正确指向对应的签署人ID。
• 使用mergeRolesOnDraft=true会合并模板角色与API传入的收件人，确保动态添加/跳过收件人的逻辑正常生效。

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