文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>号码认证

服务端接口文档

最近更新时间：2026-01-16 21:05:02

我的收藏

本页目录：

交互流程


1. step1.1 到 step1.7 的逻辑由 SDK 封装，详情可参见 SDK 使用说明文档。
2. step2.1 开发者到开发者服务器的协议由开发者自行定义。
3. 开发者服务器和云通信之间的协议见验证 token 接口。

验证 token 接口

接口说明

通过客户端 SDK token，获取当前用户登录手机号码。

接口请求协议

POST + JSON

接口 URL

https://yun.tim.qq.com/v5/rapidauth/validate?sdkappid=xxxx&random=xxxx
其中，URL 参数 sdkappid 即是技术对接群工作人员提供的 Excel 表里面的应用 ID，参数 random 请填成随机数(随机生成10位)，具体如下：
URL 参数
必填
类型
描述
sdkappid
是
number
应用 ID，即技术对接群工作人员提供的 Excel 申请表里面的应用 ID。
random
是
string
随机数，10位随机数字符串。
注意：
sdkappid 和 random 需拼接在接口 URL 上，不用放在请求报文里面。

请求参数

请求参数说明如下表所示。
参数
必填
类型
描述
sig
是
string
App 凭证，具体生成方式见下方sig生成规则，sig 有效期10分钟。
time
是
string
开发者服务器当前时间戳（精确到秒）。
示例值：1622184870
carrier
否
string
运营商名，移动：mobile， 联通：unicom，电信：telecom。
注意：
非必选参数，可由客户端通过号码认证SDK的自带函数获取传参到后端，可按枚举值映射。
token
是
string
客户端SDK token。
注意：
有效期为2分钟且单次有效，成功获取手机号之后失效。

sig 生成规则

"sig" 字段根据公式 sha256(appkey=$appkey&random=$random&time=$time) 生成。伪代码如下：
string strAppKey = "5f03a35d00ee52a21327ab048186a2c4"; // 需填写工作人员提供的 Excel 表里面的应用 key（应用 Key 需要业务方高度保密，不要在客户端调用或返回客户端)，此处仅为样例参考
string strRand = "7226249334"; // url 中的 random 字段的值
string strTime = "1457336869"; // UNIX 时间戳（单位秒，对应请求参数 time）
string sig = sha256(appkey=5f03a35d00ee52a21327ab048186a2c4&random=7226249334&time=1457336869) = c13e54f047ed75e821e698730c72d030dc30e5b510b3f8a0fb6fb7605283d7df;
请求示例：
{
    "sig": "ecab4881ee80ad3d76bb1da68387428ca752eb885e52621a3129dcf4d9bc4fd4",
    "time": 1457336869,
    "carrier": "mobile",
    "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}





响应参数

响应参数说明如下表所示。 
参数
必填
类型
描述
result
是
number
错误码：
0表示成功。
非0表示失败。
errmsg
是
string
错误信息。
mobile
是
string
手机号码。
响应示例： 
{
    "mobile": "13788888888",
    "errmsg": "",
    "result": 0
}

错误码

请求错误码：
错误码
说明
处理措施
1001
sig 校验失败。
请核对 API 的 sig 格式说明。
1003
请求包体没有 sig 字段或 sig 为空。
请遵守 API 接口说明规范。
1004
请求包解析失败，通常情况下是由于没有遵守 API 接口说明规范导致的。
请遵守 API 接口说明规范。
1007
其他错误。
请咨询助手处理，一般是网络抖动导致的请求超时，可重试处理。
1019
sdkappid 不存在。
请检查请求 URL 中 sdkappid 参数是否正确设置。
1020
sdkappid 已禁用。
此 sdkappid 禁止提供服务。
1021
请求发起时间不正常，通常是由于您的服务器时间与腾讯云服务器时间差异超过10分钟导致的。
请核对服务器时间及 API 接口中的时间字段是否正常。
1031
账户欠费停服，可参见 计费概述。
请及时登录控制台充值。
1045
缺少运营商账号配置。
请咨询助手处理。
1047
认证失败。
请参考具体错误信息说明。

接入层响应参数

区别于以上业务侧返回响应，部分场景服务端接入层会直接返回失败响应，参数说明如下表所示。
参数
必填
类型
描述
ActionStatus
是
string
请求处理的结果：
FAIL：表示失败，如果为 FAIL，ErrorInfo 带上失败原因。
ErrorCode
是
number
错误码。
ErrorInfo
是
string
失败原因。
响应示例： 
{
    "ActionStatus": "FAIL",
    "ErrorCode": 60008,
    "ErrorInfo": "service timeout or request format error,please check and try again"
}

接入层公共错误码

接入层直接返回失败响应时，包含的公共错误码：
错误码
说明
处理措施
60002
HTTP 解析错误。
请检查 HTTP 请求 URL 格式。
60003
HTTP 请求 JSON 解析错误。
请检查包体 JSON 格式。
60004
检查账号失败。
请稍后重试。如果仍然失败，请联系技术支持处理。
60005
检查账号失败。
请稍后重试。如果仍然失败，请联系技术支持处理。
60007
REST 接口调用频率超过限制。
请降低请求频率。
60008
服务请求超时或 HTTP 请求格式错误。
请检查请求并重试。如果仍然失败，请联系技术支持处理。
60012
REST 接口需要带 sdkappid。
请检查请求 URL 中的 sdkappid。
60013
HTTP 响应包 JSON 解析错误。
请联系技术支持处理。
60014
检查账号超时。
请检查请求并重试。如果仍然失败，请联系技术支持处理。
60016
sdkappid 被禁用。
请联系技术支持处理。
60017
请求被禁用。
请联系技术支持处理。
60018
请求过于频繁，请稍后重试。
请检查接口调用频次是否合理。
60021
服务端 REST API 调用来源 IP 非法。
请联系技术支持处理。
60025
服务端 REST API 调用 sdkappid 错误。
请检查 URL 参数。

接入所需材料

Android 应用的包名。
Android 包签名 MD5。
iOS 应用的 bundleId。
鸿蒙应用的签名指纹值和 appId。
应用名称。
中国站