二次校验接口

2024.11.01 11:59:35

    用户每完成一次验证码验证,易盾验证码服务会记录该次请求相关的验证信息,以确保该次验证是有效并且是最近完成的,并且会对这些验证信息做衰减失效处理(默认为20分钟),针对用户验证行为和提交行为设置个性化的超时时间,有效防止批量定时恶意验证的风险

    接口说明

    用户提交表单(post-form)到产品应用后台,会携带一个验证码相关的参数,参数名为 NECaptchaValidate,产品应用需要将该参数传给易盾验证码后台做二次校验,是否验证成功,以服务端二次校验接口返回true还是false为准
    详情可参考接入流程图

    鉴权说明

    易盾验证码服务使用签名方法对接口进行鉴权,所有接口每一次请求都需要包含签名信息(signature参数),以验证用户身份,防止信息被恶意篡改。目前支持MD5,SHA1,SHA256,SM3, HMAC_SHA256几种加密算法,详细信息,请参见接口鉴权

    请求说明

    请求地址

    基本
    HTTP URL https://c.dun.163.com/api/v2/verify
    HTTP Method POST

    请求头

    名称 类型 必填 描述
    Content-Type string 固定值:"application/x-www-form-urlencoded"

    请求参数

    部分产品相关参数请用账号登陆易盾官网控制台获取参考image title

    请求参数由公用参数私有参数两部分组成,公用参数如下:

    名称 类型 必填 描述
    version String 版本信息,固定值v2
    nonce String 用于防重放。最长32个字符
    timestamp Number 发起此查询操作的时间。UNIX时间戳,单位:毫秒
    secretId String 产品密钥id,由易盾验证码服务分配
    signature String 此次请求的签名,用来验证请求的合法性。具体算法见 接口鉴权

    私有参数如下:

    名称 类型 必填 最大长度 描述
    captchaId string 32 验证码id
    validate string 不限制长度,建议1024 提交二次校验的验证数据,即NECaptchaValidate值。
    只能校验成功一次,重复校验会返回校验不通过。有效时长默认20分钟,可在官网配置为1~20分钟
    clientIp string 64 用户IP信息, 非必传,用于验证用户进行二次验证时是否更换过网络
    clientUa string 512 用户UA信息, 非必传, 用户验证用户进行二次验证时是否更换过浏览器设备
    user string 32 用户信息,该字段必传,值可为空
    user字段必传,可以填空值或一个定值,建议传用户账户便于后续定位数据!

    请求体示例

    captchaId=xxx&validate=xxx&signature=xxx&secretId=xxx&version=v2&timestamp=xxx&nonce=xxx
    

    响应结果

    响应结果内容如下,响应返回码已省略,详细见响应返回码

    名称 类型 必填 描述
    result boolean 验证码最终判定结果,以此字段为准:true:校验通过,false:校验不通过
    error int 错误码
    msg string 错误描述信息
    phone string 仅限于短信上行验证码类型,返回用户发送上行短信成功后的手机号
    captchaType int 用于返回验证码类型,需要联系易盾技术人员配置是否返回
    token string 用于返回验证流程token,需要联系易盾技术人员配置是否返回
    sdkReduce boolean 用于标识是否走降级策略,需要联系易盾技术人员配置是否返回
    clientIp string 用于返回用户Ip,需要联系易盾技术人员配置是否返回
    clientUa string 用于返回用户Ua,需要联系易盾技术人员配置是否返回
    extraData string 返回业务方在初始化时传入的extraData内容,详见web接入参数配置

    响应体示例

    {
        "result": true,
        "error": 0,
        "msg": "ok",
        "phone": "",
        "extraData": "",
        "captchaType": 2,
        "token": "xxx",
        "sdkReduce": false
    }
    

    错误描述信息列表

    msg内容 msg含义
    ok 请求成功
    WRONG_DATA token非法或过期:请求参数中,validate使用了过期值,validate默认有效期20分钟
    SDK UNAVAILABLE 降级validate:请求参数中,validate使用了SDK降级validate
    ID_NOT_MATCHED ID不匹配:服务端与前端(客户端)使用的captchaid不一致
    TOKEN DECRYPT ERROR validate解密失败或者解密的token不存在:verify入参的validate不合法

    接入示例代码

    服务端 SDK 接入

    推荐使用我们提供的服务端 SDK 进行接入(目前支持 Java 和 Go 两种语言),不但可以节省接入成本,实现更快速的集成,并享有灵活的请求配置选项,同时 SDK 内置了错误重试、熔断降级等功能,提升服务可用性。点击 服务端 SDK 接入指引 了解更多。

    Github Demo 地址

    Online Chat Tel:95163223 Free trial