模块说明
captcha 提供注册与手机验证码登录共用的两步验证码流程：
- 获取图形令牌对（
captcha/token）； - 凭令牌对下发短信/邮件验证码（
captcha/verification），成功后拿到「验证数据」，原样透传给注册/登录提交接口。
完整流程图与 verification_data 的透传约定见《鉴权与会话》。
鉴权级别：可选（匿名可调，且本接口不依赖令牌）。
接口一览
| 方法 | URL | 鉴权 | 说明 |
|---|---|---|---|
| GET | /api/captcha |
可选 | 等价于 captcha/token（兼容入口） |
| GET | /api/captcha/token |
可选 | 颁发验证码表单令牌对 |
| POST | /api/captcha/verification |
可选 | 下发短信/邮件验证码（限流 5 次/300 秒） |
获取令牌对
GET /api/captcha/token{
"code": "OK",
"message": "",
"data": {
"captcha_token": "...",
"storage_captcha_token": "..."
},
"errors": {},
"request_id": "9f2a5c8e1b3d7f40"
}两个令牌必须成对保存与使用，令牌与图形验证流程关联。
下发验证码
POST /api/captcha/verification
Content-Type: application/json
{
"type": "sms", // sms=短信 / email=邮件
"account": "13800000000", // 接收账号（手机号 / 邮箱）
"captcha_token": "...",
"storage_captcha_token": "...",
"check": "no_allow_phone_exist" // 业务策略（见下表）
}| 参数 | 必填 | 说明 |
|---|---|---|
type |
是 | sms（短信）/ email（邮件） |
account |
是 | 手机号或邮箱（与 type 对应） |
captcha_token |
是 | captcha/token 返回 |
storage_captcha_token |
是 | captcha/token 返回 |
check |
否 | 业务策略，默认 no_allow_phone_exist（账号已注册则拒绝，适合注册场景）；登录场景请传空串（允许已存在账号） |
成功响应
{
"code": "OK",
"message": "",
"data": {
"account": "13800000000",
"ontime": 1760000000,
"code": "服务端生成的验证码校验摘要"
},
"errors": {},
"request_id": "9f2a5c8e1b3d7f40"
}data 即「验证数据」（verification_data）：客户端原样保存、原样透传，不要解析或修改。
失败响应
{
"code": "BUSINESS_RULE_VIOLATION",
"message": "该手机号已经存在",
"data": {},
"errors": {},
"request_id": "9f2a5c8e1b3d7f40"
}常见失败原因：令牌对无效/过期、账号格式错误、账号已存在（check 策略）、短信/邮件通道发送失败。
注意事项
- 验证码有效期 5 分钟（提交时服务端校验
ontime）； - 本接口限流 5 次/300 秒（按 IP），客户端应做 60 秒按钮倒计时，避免用户连点触发 429；
- 下发成功后用户收到的验证码需在注册/登录提交时以独立字段（
verification）传入，与verification_data配合校验； - 收到
429时读取Retry-After展示"请 X 秒后再试"。