概述

本文是极验无感本机认证产品的服务端API接口说明,供开发者做接入使用。无感本机认证包含OneLogin(一键登录 APP)、OnePass(本机号码认证APP)和OnePassAPI(本机号码认证H5)三个能力。

如APP使用一键登录功能,则服务端相应对接OneLogin(一键登录APP)接口即可。

如APP使用本机号码认证功能,则服务端相应对接OnePass(本机号码认证APP)接口即可。

如H5或者小程序使用本机号码认证功能,则服务端相应对接OnePassAPI(本机号码认证H5)接口即可。

OneLogin(一键登录APP)

1、 接口地址和说明

请求URL:
https://onelogin.geetest.com/check_phone

请求方式:

  • POST

数据类型:
application/json

2、 接口请求参数

请求参数:

参数名 必选 类型 说明
process_id str SDK返回的流水号,一次有效
sign str 用户签名,用于账号校验
生成方式:
1.将app_id, 以及当前时间戳(毫秒为单位)通过”&&”连接。(app_id + ‘&&’ + timestamp)
2.使用app_key进行hmac-sha256签名。将结果转换为16进制。
token str SDK返回的运营商Token
is_phone_encode bool 返回手机号是否加密,默认不加密,加密传输情况加密方式为AES
timestamp str 当前时间(单位为毫秒),sign加密所使用的当前时间戳与其相同
authcode str 电信新版本接口校验码,仅电信手机号需此入参
注:authcode为新增参数,sdk为安卓 0.8.0/IOS 1.8.0及以上版本时,服务端均需传此参数

请求示例:

curl -H "Content-Type: application/json" -d '{"token": "客户端返回用于获取结果的token", "sign": "生成的用户签名", "process_id": "客户端返回的流水号", "authcode": "客户端返回的电信校验码", "is_phone_encode": true, "timestamp": "当前时间"}' https://onelogin.geetest.com/check_phone

3、 接口返回参数

返回参数说明:

参数名 类型 说明 是否必返回
status int 状态码 true
result str 请求成功时,返回手机号,失败时为”” true
charge bool 是否扣费标志,true计费,false不计费 true
error_msg str 请求失败时,返回对应状态码的描述 true
risk_code list 风险码(可能会有多个) false
risk_level int 风险等级(只返回最高风险等级) false
finger_print str 对应的设备的指纹 false
device_name str 设备名称 false
strategy_code list 规则返回码 false

注:集成2.0.0及以上版本SDK,且接入设备指纹功能,在成功获得手机号情况下会同时返回 risk_code/ risk_level/ finger_print/ device_name/ strategy_code 参数

风险等级说明:

字段名 等级 说明
risk_level 0 未发现风险,正常用户
risk_level 3 风险较低
risk_level 7 有较高的风险
risk_level 9 高风险,确定是风险用户

风险码说明:

风险码 风险等级 原因
2002 3/7/9 ip击中攻击数据库,威胁等级依据IP本身攻击行为的程度
4001 7 模拟器操作
4003 7 安卓端对设备有改机操作或者安装了改机软件
4004 3 设备越狱或者root
4005 3 设备安装了多开工具或者类似多开类应用
4006 7 设备处于正在被调试状态

规则返回码:

风险信息返回 strategy_code 原因
手机号频次超限 4011 一小时内同一手机号调用OneLogin次数超过限制
IP频次超限 4012 一小时内同一IP调用OneLogin次数超过限制
设备频次超限 4013 一小时内同一设备调用OneLogin次数超过限制
手机号黑名单 4021 调用OneLogin请求的手机号在黑名单里
IP黑名单 4022 调用OneLogin的 IP 在黑名单里
设备指纹黑名单 4023 调用OneLogin的设备在黑名单里
IP账户限制 4032 单IP账户数量超过限制
设备账户限制 4033 单设备指纹账户数量超过限制
新设备限制 3043 本次调用OneLogin的设备为新设备

状态码:

状态码 描述 处理建议
200 请求成功
500 从运营商获取结果失败 提供流水号,结合日志记录查询失败原因
12000 process_id为空 1、用户没有传process_id这个参数;2、请求参数格式非json导致无法识别
12001 token为空 用户未传该字段
12002 sign为空 用户未传该字段
12003 process_id不为32位 process_id不合法,需使用客户端回传process_id
12004 错误is_phone_encode类型 按文档入参要求传参
12005 时间戳不正确 按文档入参要求传参
12006 运营商配置错误 按文档入参要求传参
12007 源IP不在报备白名单中 检查应用申请时报备ip白名单列表是否包含当前服务器
12100 process_id不存在 检查sdk版本并联系客服详细处理
12101 process_id已使用过 process_id重复使用
12102 未查询到对应的app_id 检查sdk版本并联系客服详细处理
12103 查询到对应的app_id不正确 检查当前应用申请app_id是否正确使用
12104 余额不足 联系商务充值
12109 sign错误 sha256加密错误,请按照提供文档加密
12200 token失效 运营商token失效,联系客服处理

OnePass(本机号码认证APP)

1、 接口地址及说明

请求URL:

  • https://onepass.geetest.com/v2.0/check_gateway

请求方式:

  • POST

数据类型:
application/json

2、 接口请求参数

请求参数:

参数名 必选 类型 说明
process_id string SDK返回的流水号,一次有效
sign string 用户签名,用于账号校验
生成方式:
1.将app_id, 以及当前时间戳(毫秒为单位)通过”&&”连接。(app_id + ‘&&’ + timestamp)
2.使用app_key进行hmac-sha256签名。将结果转换为16进制。
accesscode string SDK返回的运营商accesscode
phone string C端用户手机号, 11位手机号
timestamp string 当前时间(单位为毫秒),sign加密所使用的当前时间戳与其相同

请求示例

curl -H "Content-Type: application/json"  -d '{"phone": "手机号", "accesscode": "客户端返回用于获取结果的token", "sign": "生成的用户签名", "process_id": "客户端返回的流水号","timestamp": "当前时间"}' https://onepass.geetest.com/v2.0/check_gateway

3、 接口返回参数

返回参数说明:

参数名 类型 说明 是否必返回
status int 状态码,200为成功,具体信息见状态码表 true
result string 请求成功时,表示校验结果,”0” 表示匹配,页面输入的手机号与当前流量卡号一致;”1” 表示不匹配,页面输入的手机号与当前流量卡号不一致 true
error_msg string 请求失败时,返回对应状态码的描述 true
risk_code list 风险码(可能会有多个) false
risk_level int 风险等级(只返回最高风险等级) false
finger_print str 对应的设备的指纹 false
device_name str 设备名称 false
strategy_code list 规则返回码 false

注:集成2.1.0及以上版本SDK,且接入设备指纹功能,在成功获得手机号情况下会同时返回 risk_code/ risk_level/ finger_print/ device_name/ strategy_code 参数

本机号返回示例

{
"status": 200,
"result": "0"
}

非本机号返回示例

{
"status": 200,
"result": "1"
}

风险等级说明:

字段名 等级 说明
risk_level 0 未发现风险,正常用户
risk_level 3 风险较低
risk_level 7 有较高的风险
risk_level 9 高风险,确定是风险用户

风险码说明:

风险码 风险等级 原因
2002 3/7/9 ip击中攻击数据库,威胁等级依据IP本身攻击行为的程度
4001 7 模拟器操作
4003 7 安卓端对设备有改机操作或者安装了改机软件
4004 3 设备越狱或者root
4005 3 设备安装了多开工具或者类似多开类应用
4006 7 设备处于正在被调试状态

规则返回码:

风险信息返回 strategy_code 原因
手机号频次超限 4011 一小时内同一手机号调用OneLogin次数超过限制
IP频次超限 4012 一小时内同一IP调用OneLogin次数超过限制
设备频次超限 4013 一小时内同一设备调用OneLogin次数超过限制
手机号黑名单 4021 调用OneLogin请求的手机号在黑名单里
IP黑名单 4022 调用OneLogin的 IP 在黑名单里
设备指纹黑名单 4023 调用OneLogin的设备在黑名单里
IP账户超限 4032 单IP账户数量超过限制
设备账户超限 4033 单设备指纹账户数量超过限制
新设备限制 3043 本次调用OneLogin的设备为新设备

状态码:

状态码 描述 处理建议
200 请求成功
500 从运营商获取结果失败 提供流水号,结合日志记录查询失败原因
2000 process_id为空 1、用户没有传process_id这个参数;2、请求参数格式非json导致无法识别
2001 sign为空 用户未传该字段
2002 accesscode为空 用户未传该字段
2003 phone为空 用户未传该字段
2004 process_id不合法(32位) process_id不合法,需使用客户端回传process_id
2005 错误的timestamp 按文档入参要求传参
2006 源IP不在报备白名单中 检查应用申请时报备ip白名单列表是否包含当前服务器
2104 sign错误 sha256加密错误,请按照提供文档加密
3001 余额不足 联系商务充值
3101 未查询到对应的app_id 检查当前应用申请app_id是否正确使用
3102 未查询到对应的process_id 需使用客户端本次回传process_id
3105 流水号已经被使用过 process_id重复使用
3200 token失效 运营商token失效,联系客服处理

OnePass API(本机号码认证H5)

1、 接口地址及说明

请求URL:

  • https://onepass.geetest.com/web/check_gateway

请求方式:

  • POST

数据类型:
X-WWW-FORM-URLENCODED

2、 接口请求参数

请求参数:

参数名 必选 类型 说明
process_id string SDK返回的流水号,一次有效
sign string 用户签名,用于账号校验
生成方式:
1.将app_id, 以及当前时间戳(毫秒为单位)通过”&&”连接。(app_id + ‘&&’ + timestamp)
2.使用app_key进行hmac-sha256签名。将结果转换为16进制。
accesscode string 运营商取号的标识,由前端返回
phone string 校验用的手机号
timestamp string 当前时间(单位为毫秒),sign加密所使用的当前时间戳与其相同

请求示例

curl -d "sign=生成的用户签名&process_id=客户端返回的流水号&timestamp=当前时间&phone=校验用的手机号" https://onelogin.geetest.com/web/check_gateway

3、 接口返回参数

返回参数说明:

参数名 类型 说明
status int 状态码
data obj 请求成功时,为返回数据
+ result str 0表示为本机号,1表示为非本机号
error_msg str 请求失败时,返回对应状态码的描述

本机号返回示例

{
"status": 200,
"data": {
"result": "0"
}
}

非本机号返回示例

{
"status": 200,
"data": {
"result": "1"
}
}

状态码:

状态码 描述 处理建议
200 请求成功
500 从运营商获取结果失败 提供流水号,结合日志记录查询失败原因
21002 余额不足 联系商务充值
21003 process_id为空 用户没有传process_id这个参数
21004 process_id没有对应的记录 需使用客户端本次回传process_id
21005 已经使用过的process_id process_id重复使用
21006 加密时间戳已经过期 1、检查时间戳是否符合文档要求;2、检查服务器本地时间是否有偏差
21007 源IP不在报备白名单中 检查应用申请时报备ip白名单列表是否包含当前服务器
21008 没有运营商的accesscode 按文档入参要求传参
21009 缺少参数phone 按文档入参要求传参
21010 校验手机号异常 检查sdk版本并联系客服详细处理
22001 sign参数校验失败 sha256加密错误,请按照提供文档加密
22002 sign参数为空 按文档入参要求传参

Sign生成和手机号加密说明

1、 Sign生成方式说明

1.将app_id, 以及当前时间戳(毫秒为单位)通过”&&”连接。(app_id + ‘&&’ + timestamp)

2.使用app_key进行hmac-sha256签名。将结果转换为16进制。

注:app_id、app_key在极验后台查看,服务端使用的app_id必须与客户端使用的相对应

示例:

app_id: ‘zoekwui1hnmg49x5fwzf5la0ml5dziwn’
app_key: ‘gywzffojtnzl0vd6kcut8fcgyud5wg49’
时间戳: ‘1542355862990’

签名结果为:

6ef12cd35800607896a0e82b2a53955d679f97ff63e2a17954ddfbd3f7647501

demo下载:

Java, Python, JS, PHP

2、 手机号加密方式说明

直接对手机号使用AES(密钥app_key)加密,结果转换为16进制。

示例:

手机号:13333333333

app_key: ‘gywzffojtnzl0vd6kcut8fcgyud5wg49’

加密结果:’be28dea08ee543320b1ef9e1bceb51e4’

demo下载:

Java, Python, JS, PHP