> >

SDK内部与极验监控交互接口

重点备注

接口路径	说明	重点
/v1/bypass_status.php	极验监控接口	1、该接口是独立于行为验证现有通讯流程之外的服务可用性监控接口，可以通过轮询机制请求该接口，通过接口返回的状态标识确认当前验证服务可用性。 2、当向极验监控接口发送请求出现返回的状态码为非200或出现请求超时的情况时，请将验证服务可用性状态标识字段置为fail。

当能够提供数据存储条件时
在sdk的demo中通过轮询机制向极验监控接口(bypass接口)发送请求，将获取的bypass状态存入数据库中(demo示例中使用的是redis，可自行设计存储架构)。当客户端向SDK服务器发起请求时，从数据库中取出状态标识字段，根据状态标识字段来决定后续向极验发起请求还是进入宕机模式不与极验发生任何交互。当获取到监控接口返回的状态为fail时，也可以选择直接放弃加载验证码，保证原有的业务流程不被阻塞。
当无法提供数据存储条件时
当实际部署环境无法满足 bypass 状态标识字段存储条件时，可以在sdk每次向极验发送请求之前，先向极验监控接口发送请求获取当前验证服务的可用性，再根据验证服务的可用性来判断后续将向极验发起请求还是进入宕机模式不与极验发生任何交互。当获取到监控接口返回的状态为fail时，也可以选择直接放弃加载验证码，保证原有的业务流程不被阻塞。

API文档概述

条目	监控接口
说明	1.该接口用于检测极验服务运行是否正常，检测范围覆盖极验服务提供的所有 API 接口; 2.该接口传入用户验证 ID，针对性检测该用户是否能正常访问极验服务，用户通过此接口的返回状态控制业务是否进入 bypass 模式; 3.可针对用户验证 ID 对该用户访问 bypass 接口后的返回状态进行配置，保证突发情况下能使业务立即切换到 bypass 模式;
域名	bypass.geetest.com
接口路径名	/v1/bypass_status.php
完整地址示例	http://bypass.geetest.com/v1/bypass_status.php
请求方式	GET/POST
请求头	(POST)Content-Type: application/x-www-form-urlencoded
请求参数格式	GET: 键值对, urlEncode POST: 表单, urlEncode
响应头	Content-Type: application/json;charset=UTF-8
响应结果类型	json格式

bypass 请求参数

名称	类型	必填	说明
gt	string	Y	向极验申请的验证id

请求参数示例

gt=c9c4facd1a6feeb80802222cbb74ca8e

bypass 响应参数

名称	类型	必填	说明
status	string	Y	success: 极验云服务正常 fail: 极验云服务异常

响应结果示例

请求响应正常时：
{"status": "success"}  表示当前极验服务状态正常
{"status": "fail"}  表示当前极验服务状态异常

请求响应异常时：
如果发送请求后出现请求超时或者返回状态码为非 200 时，请将极验服务状态标识为异常

客户端与SDK服务器交互接口

API文档概述

条目	验证初始化接口	二次验证接口
接口路径名	/register	/validate
完整地址示例	http://localhost:8080/register	http://localhost:8080/validate
请求方式	GET	POST
请求头		Content-Type: application/x-www-form-urlencoded
请求参数格式	键值对，urlEncode	表单，urlEncode
响应头	Content-Type: application/json;charset=UTF-8	Content-Type: application/json;charset=UTF-8
响应结果类型	json格式	json格式

/register 验证初始化请求参数

名称	类型	必填	说明
t	string	Y	时间戳

请求参数示例

t=1592814394125

/register 验证初始化响应参数

名称	类型	必填	说明
success	int	Y	流程状态标识(1表示正常模式，0表示宕机模式)
new_captcha	bool	Y	新版验证码标识，固定不变
challenge	string	Y	流水号，一次完整验证流程的唯一标识
gt	string	Y	向极验申请的账号id

响应结果示例

{
    "success": 1,
    "new_captcha": true,
    "challenge": "2b36836f0b4ec6e6e0225e1da4ccdeb2",
    "gt": "c9c4facd1a6feeb80802222cbb74ca8e"
}

/validate 二次验证请求参数

名称	类型	必填	说明
geetest_challenge	string	Y	流水号，一次完整验证流程的唯一标识
geetest_validate	string	Y	待校验的核心数据，客户端向极验请求的http://api.geetest.com/ajax.php 接口返回得到
geetest_seccode	string	Y	待校验的核心数据，geetest_validate加上\|jordan组成的字符串

请求参数示例

geetest_challenge=31eb57657ac6746f78c4b544a1cd5147k8
&geetest_validate=580ebd155b1283c016fad1928aeff536
&geetest_seccode=580ebd155b1283c016fad1928aeff536%7Cjordan

/validate 二次验证响应参数

名称	类型	必填	说明
result	string	Y	success表示通过；fail表示不通过
version	string	Y	服务端sdk版本
msg	string	N	结果为fail的相关信息

响应结果示例

{
    "result": "fail",
    "version": "jave-servlet:3.1.0",
    "msg": "极验二次验证不通过"
}

SDK内部与极验服务器交互接口

重点备注

在SDK内部每次向极验服务器交互接口发送请求之前，都需要对极验服务器状态进行校验。当校验结果正常时，向极验服务器交互接口发送请求；当校验结果异常时，进入宕机模式不与极验发生任何交互。

API文档概述

条目	验证初始化	二次验证
接口路径名	/register.php	/validate.php
完整地址	http://api.geetest.com/register.php	http://api.geetest.com/validate.php
请求方式	GET	POST
请求头		Content-Type: application/x-www-form-urlencoded
请求参数格式	键值对，urlEncode	表单，urlEncode
响应头	Content-Type: text/javascript;charset=UTF-8	Content-Type: text/javascript;charset=UTF-8
响应结果类型	json格式	json格式

/register.php 请求参数

名称	类型	必填	说明
user_id	string	N	user_id作为终端用户的唯一标识，确定用户的唯一性；作用于提供进阶数据分析服务，可在api1 或 api2 接口传入，不传入也不影响验证服务的使用；若担心用户信息风险，可作预处理(如哈希处理)再提供到极验
client_type	string	N	客户端类型，web（pc浏览器），h5（手机浏览器，包括webview），native（原生app），unknown（未知）
ip_address	string	N	客户端请求SDK服务器的ip地址
digestmod	string	Y	生成唯一标识字符串的签名算法，默认暂支持md5
gt	string	Y	向极验申请的账号id
json_format	string	Y	json格式化标识
sdk	string	Y	sdk代码版本号

请求参数示例

user_id=test
&client_type=web
&ip_address=127.0.0.1
&digestmod=md5
&gt=c9c4facd1a6feeb80802222cbb74ca8e
&json_format=1

/register.php 响应参数

名称	类型	必填	说明
challenge	string	Y	生成唯一流水号的参考字符串，为”0”表示传参账号id有误

注意：此challenge字段为极验服务器返回的原始串，不可直接使用，后续需结合密钥进行编码加密才可生成唯一流水号。详见极验官方sdk demo项目代码。
建议拉取极验sdk demo项目代码作参考，api文档无法代表sdk全部业务逻辑。

响应结果示例

{
    "challenge": "b324874b39840757544e33bf4b60cb80"
}

/validate.php 请求参数

名称	类型	必填	说明
user_id	string	N	user_id作为终端用户的唯一标识，确定用户的唯一性；作用于提供进阶数据分析服务，可在api1 或 api2 接口传入，不传入也不影响验证服务的使用；若担心用户信息风险，可作预处理(如哈希处理)再提供到极验
client_type	string	N	客户端类型，web（pc浏览器），h5（手机浏览器，包括webview），native（原生app），unknown（未知）
ip_address	string	N	客户端请求SDK服务器的ip地址
seccode	string	Y	核心校验数据
challenge	string	Y	流水号，一次完整验证流程的唯一标识
json_format	string	Y	json格式化标识
sdk	string	Y	sdk代码版本号
captchaid	string	Y	向极验申请的账号id

请求参数示例

user_id=test
&client_type=web
&ip_address=127.0.0.1
&seccode=f7475f921a41f7ba79ae15e41658627c%7Cjordan
&challenge=5a757e661e70fc8e307326912fee8e2c8u
&json_format=1
&sdk=java-servlet%3A3.1.0
&captchaid=c9c4facd1a6feeb80802222cbb74ca8e

/validate.php 响应参数

名称	类型	必填	说明
seccode	string	Y	验证结果标识，为”false”表示验证不通过

响应结果示例

{
    "seccode": "91f80894e06d04a58b158ad721266b67"
}

引用

服务端常见问题

服务端常见错误码