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` 扩大解释为可降级放行