RESTful API
# RESTful API
本文档详细介绍行为验证码的三个核心 API 接口。
## 通用约定
### HTTP 状态码
| 状态码 | 含义 |
|--------|------|
| 200 | 请求成功,业务结果见 `response.code` |
| 400 | 参数校验失败(必填字段缺失、值超限等) |
| 401 | API-Key 无效 |
| 403 | 票据无效、过期或不匹配 |
| 500 | 内部错误(签发票据失败等) |
| 502 | 内部错误(依赖的数据库、缓存等服务不可用) |
### 业务响应码(response.code)
| code | 含义 |
|------|------|
| 0 | 成功 |
| 1001 | 参数错误(缺少必填字段、长度超限、格式非法等) |
| 1002 | 频率封禁(`E_BANNED`,IP/设备触发限流) |
| 1003 | 不支持的验证码类型 |
| 1004 | 验证码不存在或已过期 |
| 1005 | 系统内部错误 |
| 1006 | 禁止访问(来源限制、IP白名单等) |
| 1007 | 服务不可用(下游超时、网络异常) |
| 1008 | 验证失败(坐标/序列不匹配) |
### 故障策略
平台支持两种全局故障策略,调用方可根据业务需求在 SDK 初始化时配置:
- **严格阻断(fail-close)**:平台服务不可用时,阻断业务流程,拒绝登录/注册
- **降级放行(fail-open)**:平台服务不可用时,记录风险日志并允许放行(等价于未接入验证码)
> ⚠️ **重要约束**:`fail-open` 仅在「开放平台 服务不可用」时触发(网络异常、超时、5xx)。`E_BANNED`(频率封禁)属于业务封禁结果,不属于服务不可用,**必须按失败处理,不可降级放行**。
### 鉴权方式
所有需要认证的接口(Generate、Verify)通过 HTTP 请求头传递 `X-API-Key`,**不放在 POST Body 或 Query 参数中**:
```http
POST /saas/api/v1/recaptcha/secure/generate
X-API-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
{"type": "text", "width": 320}
```
Click 接口由前端直连,通过 `verify_ticket` 鉴权,无需 `X-API-Key` 头。
---
## 1. POST/GET /saas/api/v1/recaptcha/secure/generate
生成验证码。**必须由调用方后端使用 `X-API-Key` 请求头发起**,返回 `captcha_id` 和短效 `verify_ticket`。
### 输入参数
> **POST 请求必须使用 JSON Body**(`Content-Type: application/json`),不支持 form-data / multipart。Body 和 Query 参数同名时 Query 优先。
| 参数 | 位置 | 必填 | 说明 |
|------|------|------|------|
| `X-API-Key` | Header | ✅ | API 密钥,前缀 `sk_` |
| `X-Log-Id` | Header | 否 | 链路追踪 ID,未传时自动生成 |
| `site_id` | JSON Body / Query | ✅ | 站点标识,用于区分不同接入场景 |
| `type` | JSON Body / Query | 否 | 验证码类型,默认 `text` |
| `width` | JSON Body / Query | 否 | 图片宽度,范围 200-320,默认 320 |
| `image_format` | JSON Body / Query | 否 | 图片格式,可选 `jpeg_q85` / `png` |
| `device_fingerprint` 等 | JSON Body / Query | 否 | 额外参数(如设备指纹),单值最长 128 字符 |
### 响应格式
```json
{
"code": 0,
"message": "ok",
"data": {
"captcha_id": "6a5e3a97f2e038b87b000007",
"verify_ticket": "cc23785c59...",
"ticket_expire_at": 1784560369,
"site_id": "test_code_name",
"type": "secure_text",
"image_data": "...",
"image_width": 320,
"image_height": 180,
"image_format": "jpeg_q85",
"bucket_level": "L1",
"is_threshold_reached": false
},
"trace": {
"http_status": 200,
"step": "generate",
"x_log_id": "6a5ec722f2e038411e0001bf"
}
}
```
> **字段说明**:
>
> - `data.is_threshold_reached`:当月用量是否达到报警阈值(默认 90%),调用方可据此提前预警。
> - `data.bucket_level`:设备标识精度等级(L1-L4),`L1` 为调用方通过 JS SDK 传入的设备指纹(推荐,可精确定位恶意设备),`L2` 为 HTTP 头组合,`L3` 为客户端自定义 ID,`L4` 为无信号兜底。不同 bucket 的频控封禁互不影响,实现按设备粒度隔离。
### 响应语义矩阵
| 场景 | HTTP Status | response.code | 典型字段 | fail-close 处理 | fail-open 处理 |
|------|-------------|---------------|----------|----------------|---------------|
| 正常生成成功 | 200 | 0 | `captcha_id` `verify_ticket` | 正常进入 click/verify | 正常进入 click/verify |
| 参数错误 | 200 | 非 0 | `message` | 阻断并提示修正参数 | 阻断并提示修正参数 |
| 服务不可用 | 5xx | 内部错误码 | `x_log_id` | 阻断主流程 | 降级放行(等价免验证码),打审计日志 |
| 频率封禁 | 200 | 1002 | `E_BANNED` `ban_blocked=true` | 阻断 | 阻断(不放行) |
---
## 2. POST/GET /saas/api/v1/recaptcha/secure/click
提交点击坐标。**由前端直连开放平台**,通过 `verify_ticket` 鉴权(无需 `X-API-Key`),结果仅用于交互提示,不作为最终验证依据。
### 输入参数
> **POST 请求必须使用 JSON Body**(`Content-Type: application/json`),不支持 form-data / multipart。
| 参数 | 位置 | 必填 | 说明 |
|------|------|------|------|
| `captcha_id` | JSON Body / Query | ✅ | 验证码 ID |
| `x` | JSON Body / Query | ✅ | 点击 X 坐标 |
| `y` | JSON Body / Query | ✅ | 点击 Y 坐标 |
| `verify_ticket` | JSON Body / Header | ✅ | Generate 返回的短效票据 |
### 响应语义矩阵
| 场景 | HTTP Status | response.code | 典型字段 | fail-close 处理 | fail-open 处理 |
|------|-------------|---------------|----------|----------------|---------------|
| 点击有效 | 200 | 0 | `hit` | 继续交互,等待 verify | 继续交互,等待 verify |
| 跨域未放行 | 200/浏览器拦截 | 40301 | `E_CORS_BLOCKED` | 提示配置跨域并阻断当前链路 | 提示配置跨域;可继续兜底策略 |
| 服务不可用 | 5xx | 内部错误码 | `E_NETWORK` | 阻断后续 verify | 可降级继续流程 |
| 频率封禁 | 200 | 1002 | `E_BANNED` `ban_blocked=true` | 阻断后续 verify | 阻断后续 verify(不放行) |
---
## 3. POST/GET /saas/api/v1/recaptcha/secure/verify
最终验证。**必须由调用方后端使用 `X-API-Key` + `verify_ticket` 发起**,以此次结果为最终依据。
### 输入参数
> **POST 请求必须使用 JSON Body**(`Content-Type: application/json`),不支持 form-data / multipart。
| 参数 | 位置 | 必填 | 说明 |
|------|------|------|------|
| `X-API-Key` | Header | ✅ | API 密钥,前缀 `sk_` |
| `X-Log-Id` | Header | 否 | 链路追踪 ID,未传时自动生成 |
| `captcha_id` | JSON Body / Query | ✅ | 验证码 ID |
| `clicks` | JSON Body / Query | ✅ | 点击坐标数组,格式 `[{"x":1,"y":2},...]` |
| `verify_ticket` | JSON Body / Header | ✅ | Generate 返回的短效票据 |
| `device_fingerprint` | JSON Body / Query | 否 | 设备指纹,最长 128 字符 |
### 响应语义矩阵
| 场景 | HTTP Status | response.code | 典型字段 | fail-close 处理 | fail-open 处理 |
|------|-------------|---------------|----------|----------------|---------------|
| 验证通过 | 200 | 0 | `verify_passed=true` | 放行业务 | 放行业务 |
| 验证失败 | 200 | 非 0 | `verify_passed=false` | 拒绝并提示重试 | 拒绝并提示重试 |
| 服务不可用 | 5xx | 内部错误码 | `degraded=true` | 阻断业务 | 降级放行:`code=0` `degraded=true` `bypass_verify=true` `verify_passed=true` |
| 频率封禁 | 200 | 1002 | `E_BANNED` `ban_blocked=true` | 阻断 | 阻断(不放行) |
### 响应格式
```json
{
"code": 0,
"data": {
"bucket_level": "L1",
"is_threshold_reached": false,
"result": "验证码验证通过",
"verify_receipt": "eyJjYXB0Y2hhX2lkIjoiNmE1ZWM3MjJmMmUwMzhiODdiMDAwMDA5IiwicmVzdWx0X2NvZGUiOjAsInZlcmlmaWVkX2F0IjoxNzg0NTk2Mjg2LCJ4X2xvZ19pZCI6IjZhNWVjNzNkZjJlMDM4NDExZTAwMDFjNyJ9.A1pF7XHMRpRH06YEJCsimQ6yJL-o5FDIROm_H15i2F4"
},
"message": "验证成功",
"trace": {
"http_status": 200,
"step": "verify",
"x_log_id": "6a5ec73df2e038411e0001c7"
}
}
```
---
## 降级边界(强约束)
- `fail-open` **只在**「SAAS 服务不可用」触发(网络异常、超时、5xx)
- `E_BANNED` 属于业务封禁结果,不属于服务不可用,必须按失败处理
- 即使存在高频攻击并触发阈值封禁,也**不能**把 `E_BANNED` 扩大解释为可降级放行