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

## 接口说明

用户提交表单（post-form）到产品应用后台，<font color="#dd0000">会携带一个验证码相关的参数，参数名为 NECaptchaValidate，产品应用需要将该参数传给易盾验证码后台做二次校验，是否验证成功</font>，以服务端二次校验接口返回true还是false为准<br>
详情可参考[接入流程图](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)

请求参数由<font color="#dd0000">公用参数</font>和<font color="#dd0000">私有参数</font>两部分组成，公用参数如下：

|名称|类型|必填|描述|
|----|----|----|----|
|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值。</br><font color="#dd0000">只能校验成功一次，重复校验会返回校验不通过。有效时长默认20分钟，可在官网配置为1~20分钟</font> |
| clientIp     | string  | 否   | 64 | 用户IP信息， 非必传，用于验证用户进行二次验证时是否更换过网络
| clientUa     | string  | 否   | 512 | 用户UA信息， 非必传， 用户验证用户进行二次验证时是否更换过浏览器设备
| user      | string | 是   | 32                   | 用户信息，该字段必传，值可为空 <br><font color="#dd0000">user字段必传，可以填空值或一个定值，建议传用户账户便于后续定位数据！</font>     |

### 请求体示例

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

### 响应结果
响应结果内容如下，响应返回码已省略，详细见[响应返回码](https://support.dun.163.com/documents/15588062143475712?docId=715301388541607936)。

| 名称      | 类型    | 必填 | 描述                                                         |
| --------- | ------- | ---- | ------------------------------------------------------------ |
| result    | boolean | 是   | <font color="#dd0000">验证码最终判定结果，以此字段为准：true：校验通过，false：校验不通过</font> |
| 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)。  |

### 响应体示例

```json
{
    "result": true,
    "error": 0,
    "msg": "ok",
    "phone": "",
    "extraData": "",
    "captchaType": 2,
    "token": "xxx",
    "sdkReduce": false
}
```
### <a id=2.1>错误描述信息列表</a>
|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)