跳到主要内容

验证图片验证码

POST 
/auth/v1/captcha/data/verify

接口说明​

验证图片验证码接口，用于验证用户输入的验证码是否正确，验证成功后返回captcha_token，用于后续业务接口的人机验证。

入参要求​

必需参数​

  • token: 验证码token（必填，从获取图片验证码接口获取）
  • key: 验证码内容（必填，用户识别图片后输入的验证码文本）

前置条件​

  • 必须先调用获取图片验证码接口获取验证码
  • token未过期（默认有效期300秒）
  • 验证码未被使用过

出参说明​

成功响应​

  • captcha_token: 验证码令牌（必填，用于后续业务接口的人机验证）
  • expires_in: 过期时间（必填，单位为秒，默认300秒）

请求示例​

验证图片验证码请求示例​

{
  "token": "aC_raGNycHQOSR7w0V7U0Ble-edJud_-AJofUvLFga8v59WsZVRI_RUBxC9Tk5eUoBNrdPhqA0M_ZkT0V0le909Z7YmWHVT4Yead026_",
  "key": "AB12"
}

响应示例​

验证成功响应示例​

{
  "captcha_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS5leGFtcGxlLmNvbSIsInN1YiI6Ijk4NzY1NDMyMTAxMjM0NTY3ODkiLCJhdWQiOiJkZW1vLWFwcC0yZjhhOWMzZTFiNGQiLCJleHAiOjE3MzQ2NzU4ODksImlhdCI6MTczNDY2ODY4OSwic2NvcGUiOiJ1c2VyIn0.dGhpc19pc19hX2Zha2Vfc2lnbmF0dXJlX2Zvcl9leGFtcGxlX3B1cnBvc2VzX29ubHlfZG9fbm90X3VzZV9pbl9wcm9kdWN0aW9uX2Vudmlyb25tZW50X3RoaXNfaXNfbm90X3JlYWxfdG9rZW5fZGF0YQ",
  "expires_in": 300
}

验证失败响应示例​

{
  "error": "invalid_captcha",
  "error_code": 4001,
  "error_description": "验证码错误"
}

验证码过期响应示例​

{
  "error": "captcha_expired",
  "error_code": 4002,
  "error_description": "验证码已过期，请重新获取"
}

验证码已使用响应示例​

{
  "error": "captcha_used",
  "error_code": 4003,
  "error_description": "验证码已被使用，请重新获取"
}

字段说明​

请求参数​

字段名类型必填说明
tokenstring是验证码token，从/auth/v1/captcha/data接口获取
keystring是用户识别图片后输入的验证码文本，不区分大小写

响应参数​

字段名类型必填说明
captcha_tokenstring是验证码令牌，用于后续业务接口的人机验证
expires_ininteger是过期时间，单位为秒，默认300秒

使用流程​

1. 获取验证码​

2. 用户输入验证码​

  • 用户识别图片中的验证码
  • 在输入框中输入验证码

3. 验证验证码​

  • 调用本接口验证用户输入
  • 传入token和用户输入的key
  • 获取captcha_token

4. 使用captcha_token​

  • 在需要验证码保护的业务接口中
  • 添加请求头：x-captcha-token: xxx
  • 完成人机验证

关键特性​

验证规则​

  • 不区分大小写
  • 验证码长度为4-6位
  • 支持数字和字母
  • 验证失败不影响token有效期

安全性​

  • 验证码使用后立即失效
  • 限制验证失败次数
  • 防止暴力破解
  • 记录验证日志

使用场景​

登录保护​

  • 登录失败次数过多时要求验证码
  • 验证通过后允许登录
  • 防止暴力破解

注册保护​

  • 注册时要求验证码
  • 防止批量注册
  • 保护系统资源

敏感操作保护​

  • 找回密码时验证
  • 修改密码时验证
  • 修改绑定信息时验证
  • 删除账号时验证

注意事项​

验证码输入​

  • 不区分大小写
  • 去除首尾空格
  • 验证失败可重试
  • 过期后需重新获取

错误处理策略​

  • 验证码错误：允许重试，超过次数后重新获取
  • 验证码过期：自动刷新验证码
  • 验证码已使用：自动刷新验证码
  • 网络错误：重试机制

相关接口​

Request​

Body

    token 验证码验证token (string)required

    从/auth/v1/captcha/data接口获取

    key 验证码中识别出的文本内容 (string)required

Responses​

Response Headers
    Schema
      captcha_token 验证码token (string)required
      expires_in 过期时间，默认600秒 (integer)required
    Loading...