服务器对接文档 ip校验,geetest-验证-server-sensebot-api

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

请求方式

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

请求方式

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

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

请求方式

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"

}

引用