DocuSign SMS认证实现报错及IdentityVerification获取失败求助

问题场景 #

尝试借助DocuSign-SDK实现SMS认证，代码示例如下：

var signer = new Signer {...};

signer.RequireIdLookup = "true";
signer.IdCheckConfigurationName = "SMS Auth $";
signer.SmsAuthentication = new RecipientSMSAuthentication {
    SenderProvidedNumbers = new List<string> {
        "0171*******"  
    }
};

调用CreateEnvelope接口时收到以下错误：

Error calling CreateEnvelope:
{"errorCode":"INVALIDAUTHENTICATIONSETUP","message":"Recipient phone number is invalid. Phone number for SMS Authentication: provided is invalid."}

INVALIDAUTHENTICATIONSETUP: Authentication is not setup correctly for the recipient.

确认手机号有效，但未找到DocuSign管理页面的相关配置项，询问是否需要启用特定功能。

补充尝试 #

按照建议通过AccountsApi获取workflowId，但返回的IdentityVerification为空，代码如下：

var client = new ApiClient(ApiClient.Demo_REST_BasePath);

var token = "eyJ1...";
client.Configuration.DefaultHeader.Add("Authorization", "Bearer " + token);

var accountsApi = new AccountsApi(client);    
var response = accountsApi.GetAccountIdentityVerification(accountId);

var result = response.IdentityVerification; // 结果为空，原因？

询问如何启用IdentityVerification选项及注意事项。

解决方案及注意事项 #

1. 解决手机号格式错误 #

DocuSign要求SMS认证的手机号必须使用E.164标准格式，即带国家区号的+号开头格式（例如+86171xxxxxxx），不能使用0171*******这类本地格式，这是触发"手机号无效"错误的核心原因。

2. 启用并配置SMS认证功能 #

必须先在DocuSign管理后台完成SMS认证的配置，步骤如下：

• 登录DocuSign Admin控制台，进入目标账户
• 左侧菜单选择身份验证→创建新的身份验证配置
• 选择短信作为验证方式，配置名称、允许的国家/地区、验证规则等
• 保存配置后，才能通过API调用使用该认证方式

3. 解决IdentityVerification为空的问题 #

返回结果为空通常有以下原因：

• 账号权限不足：调用GetAccountIdentityVerification的API账号必须拥有账户管理员权限，普通用户账号无法查看账户级的身份验证配置
• 未创建验证配置：如果后台还未创建任何身份验证工作流，该列表自然为空，需先完成步骤2的配置
• API版本过低：确保使用的DocuSign-SDK对应API版本为v2.1及以上，旧版本不支持该接口

4. 正确的SMS认证代码示例（新版方式） #

配置好后台验证工作流并获取到workflowId后，推荐使用新版IdentityVerification方式实现SMS认证，代码示例：

var signer = new Signer {...};

// 替换为实际获取到的SMS验证workflowId
var smsWorkflowId = "your-sms-verification-workflow-id";

signer.IdentityVerification = new List<RecipientIdentityVerification>
{
    new RecipientIdentityVerification
    {
        WorkflowId = smsWorkflowId,
        InputOptions = new List<RecipientIdentityVerificationInputOption>
        {
            new RecipientIdentityVerificationInputOption
            {
                Name = "phone_number",
                Value = "+86171xxxxxxx" // E.164格式手机号
            }
        }
    }
};

额外注意事项 #

• 旧版SmsAuthentication和IdCheckConfigurationName的方式已逐步被新版IdentityVerification取代，推荐使用新版接口
• 如果使用旧版方式，IdCheckConfigurationName必须与后台配置的认证方式名称完全一致（包括空格、大小写），例如后台配置名称为"SMS Authentication"，则代码中不能写"SMS Auth $"
• 测试环境（Demo）和生产环境的配置是独立的，需分别配置

内容的提问来源于stack exchange，提问作者devmne-me