用户每完成一次验证码验证，易盾验证码服务会记录该次请求相关的验证信息，以确保该次验证是有效并且是最近完成的，并且会对这些验证信息做衰减失效处理（默认为20分钟），针对用户验证行为和提交行为设置个性化的超时时间，有效防止批量定时恶意验证的风险 ## 接口说明 用户提交表单（post-form）到产品应用后台，会携带一个验证码相关的参数，参数名为 NECaptchaValidate，产品应用需要将该参数传给易盾验证码后台做二次校验，是否验证成功，以服务端二次校验接口返回true还是false为准 详情可参考接入流程图 (https://support.dun.163.com/documents/15588062143475712?docId=150401879704260608) ## 鉴权说明 易盾验证码服务使用签名方法对接口进行鉴权，所有接口每一次请求都需要包含签名信息（signature参数），以验证用户身份，防止信息被恶意篡改。目前支持MD5，SHA1，SHA256，SM3, HMAC_SHA256几种加密算法，详细信息，请参见接口鉴权 (https://support.dun.163.com/documents/15588062143475712?docId=271068087004090368) ## 请求说明 ### 请求地址 基本 | HTTP URL | http://c.dun.163.com/api/v2/verify HTTP Method | POST ### 请求头 名称 | 类型 | 必填 | 描述 Content-Type | string | 是 | 固定值："application/x-www-form-urlencoded" ### 请求参数 部分产品相关参数请用账号登陆易盾官网控制台获取参考image title (https://nos.netease.com/yidun/06f160dcf8307222f34c079a263eb990.png) 请求参数由公用参数和私有参数两部分组成，公用参数如下： 名称 | 类型 | 必填 | 描述 version | String | 是 | 版本信息，固定值v2 nonce | String | 是 | 用于防重放。最长32个字符 timestamp | Number | 是 | 发起此查询操作的时间。UNIX时间戳，单位：毫秒 secretId | String | 是 | 产品密钥id，由易盾验证码服务分配 signature | String | 是 | 此次请求的签名，用来验证请求的合法性。具体算法见 接口鉴权 (https://support.dun.163.com/documents/15588062143475712?docId=271068087004090368) 私有参数如下： 名称 | 类型 | 必填 | 最大长度 | 描述 captchaId | string | 是 | 32 | 验证码id validate | string | 是 | 不限制长度，建议1024 | 提交二次校验的验证数据，即NECaptchaValidate值。只能校验成功一次，重复校验会返回校验不通过。有效时长默认20分钟，可在官网配置为1~20分钟 clientIp | string | 否 | 64 | 用户IP信息， 非必传，用于验证用户进行二次验证时是否更换过网络 clientUa | string | 否 | 512 | 用户UA信息， 非必传， 用户验证用户进行二次验证时是否更换过浏览器设备 user | string | 是 | 32 | 用户信息，该字段必传，值可为空 user字段必传，可以填空值或一个定值，建议传用户账户便于后续定位数据！ ### 请求体示例 Code: captchaId=xxx&validate=xxx&signature=xxx&secretId=xxx&version=v2×tamp=xxx&nonce=xxx ### 响应结果 响应结果内容如下，响应返回码已省略，详细见响应返回码 (https://support.dun.163.com/documents/15588062143475712?docId=715301388541607936)。 名称 | 类型 | 必填 | 描述 result | boolean | 是 | 验证码最终判定结果，以此字段为准：true：校验通过，false：校验不通过 error | int | 是 | 错误码 (https://support.dun.163.com/documents/15588062143475712?docId=715301388541607936) msg | string | 是 | 错误描述信息 (#2.1) tokenTimeStamp | Long | 是 | 该参数表示生成validate的时间戳 phone | string | 否 | 仅限于短信上行验证码类型，返回用户发送上行短信成功后的手机号 captchaType | int | 否 | 用于返回验证码类型，需要联系易盾技术人员配置是否返回 token | string | 否 | 用于返回验证流程token，需要联系易盾技术人员配置是否返回 sdkReduce | boolean | 否 | 用于标识是否走降级策略，需要联系易盾技术人员配置是否返回 clientIp | string | 否 | 用于返回用户Ip，需要联系易盾技术人员配置是否返回 clientUa | string | 否 | 用于返回用户Ua，需要联系易盾技术人员配置是否返回 extraData | string | 否 | 返回业务方在初始化时传入的extraData内容，详见web接入参数配置 (http://support.dun.163.com/documents/15588062143475712?docId=150442915877015552)。 ### 响应体示例 Code (json): { "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，前端若因为网络等原因多次加载验证码失败会产生固定的降级token，业务侧可以暂时通过这类用户，做其他方式降级处理。 ID_NOT_MATCHED | ID不匹配：服务端与前端（客户端）使用的captchaid不一致 TOKEN DECRYPT ERROR | validate解密失败或者解密的token不存在：verify入参的validate不合法 ## 接入示例代码 ### 服务端 SDK 接入 推荐使用我们提供的服务端 SDK 进行接入（目前支持 Java 和 Go 两种语言），不但可以节省接入成本，实现更快速的集成，并享有灵活的请求配置选项，同时 SDK 内置了错误重试、熔断降级等功能，提升服务可用性。点击 服务端 SDK 接入指引 (https://support.dun.163.com/documents/15588062143475712?docId=682781209345695744) 了解更多。 #### Github Demo 地址 - Java SDK Demo (https://github.com/yidun/yidun-java-sdk/blob/main/yidun-java-sdk-demo/src/main/java/com/netease/yidun/sdk/captcha/v2/CaptchaVerifyDemo.java) - Golang SDK Demo (https://github.com/yidun/yidun-golang-sdk/tree/main/yidun/demo/captcha/verify)