集成DocuSign身份验证（电话认证）至信封时遇手机号无效问题求助

问题概述 #

在DocuSign信封中集成电话认证功能后，调用创建信封API时返回PHONE_NUMBER_INVALID错误，提示手机号无效；未启用认证前信封功能正常运行。

请求详情 #

POST端点 #

https://demo.docusign.net/restapi/v2.1/accounts/f8594d59-9d52-xxxx-xxxx-xxxxxxxxxxxx/envelopes

请求头 #

Authorization: Bearer {accestoken}
Content-Type: application/json
Accept: application/json  // 注意：原请求头中"Acces"拼写错误，需修正为"Accept"

请求体 #

{
    "accountId": "f8594d59-9d52-xxxx-xxxx-xxxxxxxxxxxx",
    "templateId": "4e2ba389-5d26-xxxx-xxxx-xxxxxxxxxxxx",
    "emailSubject": "Please sign the contract",
    "templateRoles": [
        {
            "roleName": "Sender",
            "name": "Name",
            "email": "fName.lName@xyz.com",
            "identityVerification": {
                "workflowId": "c368e411-1592-xxxx-xxxx-xxxxxxxxxxxx",
                "steps": null,
                "inputOptions": [
                    {
                        "name": "phone_number_list",
                        "valueType": "PhoneNumberList",
                        "phoneNumberList": [
                            {
                                "countryCode": "1",
                                "number": "8956324511"
                            }
                        ]
                    }
                ]
            }
        },
        {
            "roleName": "Customer",
            "name": "cFName",
            "email": "cFName.cLName@gmail.com"
        }
    ],
    "status": "sent"
}

错误响应 #

{
    "errorCode": "PHONE_NUMBER_INVALID",
    "message": "Phone number is not valid."
}

解决方案 #

以下是几个可行的修复方向：

1. 修正请求头拼写错误
   原请求头中的Acces: application/json为拼写错误，需改为Accept: application/json。虽不是直接导致手机号错误的原因，但可能影响API请求的正常解析。

2. 使用Demo环境允许的测试手机号
   DocuSign Demo环境仅接受特定测试手机号（如北美地区555开头的号码），真实手机号无法在该环境通过验证。示例替换为：

   {
       "countryCode": "1",
       "number": "5551234567"
   }
   

3. 验证手机号格式与有效性

   • 北美（countryCode=1）的手机号必须是10位纯数字，且区号需为有效的北美地区区号（895并非有效北美区号，会导致验证失败）。
   • 确保号码无括号、横杠等非数字字符，DocuSign要求纯数字格式。

4. 确认工作流配置匹配
   检查workflowId对应的身份验证工作流是否允许使用指定国家代码的手机号，以及工作流是否设置了号码格式限制。

内容的提问来源于stack exchange，提问作者Abhijeet Singh Manuwal