Help Center

    二次校验接口

    2025.03.31 09:50:56

      用户每完成一次验证码验证，易盾验证码服务会记录该次请求相关的验证信息，以确保该次验证是有效并且是最近完成的，并且会对这些验证信息做衰减失效处理（默认为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 是 错误描述信息
      tokenTimeStamp string 是 该参数表示生成validate的时间戳
      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 地址

      Comment On The Document:

      If you encounter product-related problems, you can Submit a ticket 或 Online Chat Seek help.

      Online Chat Tel：95163223 Free trial