行为验证码 API v2 文档

本文档介绍行为验证码产品的票据校验接口。前端只负责取得 ticket（与 Web/App 的 randstr），真正的判定必须由业务服务端调用本平台接口完成—— 仅凭前端回调结果放行会导致验证结果被伪造，失去人机对抗效果。

1. 基础信息

接口地址：https://api.starloft.cn/v2/captcha
请求格式：application/json
鉴权方式：API Key + HMAC-SHA256 签名（与平台其它产品一致，见「请求鉴权」）
可授权接口标识：captcha_verify、captcha_mini_verify、captcha_config （密钥已授权任一票据校验接口时，接入配置自动放行，无需单独勾选）

2. 调用前提

账户已完成个人实名（realname_status ≥ 1）。
已创建 API 密钥，且密钥权限包含要调用的接口标识（或为 all）。
账户有可用资源包或余额（校验前平台会做额度预检，不足时返回 402）。

3. 获取接入配置

GET /v2/captcha/config：按三个组合参数返回前端需要的验证 ID 与 JS 地址（不含任何密钥，免费接口）。上游按「客户端类型 × 应用场景 × 验证方式」分别创建应用，请始终传入与实际前端一致的组合。

参数	类型	必填	说明
`client_type`	string	是	`web` / `app`（共用 Web/APP 应用）/ `mini`（微信小程序）
`scene`	string	是	`account` 账号 / `sms` 短信 / `activity` 活动 / `comment` 评论 / `data_protection` 数据保护 / `other` 其他
`verify_type`	string	是	`slide` 滑动拼图 / `word_click` 文字点选 / `image_click` 图形点选 / `no_sense` 无感验证；微信小程序仅支持 `slide`

GET /v2/captcha/config?client_type=web&scene=account&verify_type=slide

{
  "code": 0,
  "message": "success",
  "data": {
    "client_type": "web",
    "scene": "account",
    "verify_type": "slide",
    "captcha_app_id": "123456789",          // 当前组合的上游验证 ID（CaptchaAppId）
    "web_js_url": "https://service.starloft.cn/service/captcha/js",
    "mini_plugin_version": "2.1.0",
    "price": 0.02,                          // 你的适用单价（元/次）
    "enabled": true
  }
}

4. 票据校验（Web / App）

POST /v2/captcha/verify

参数	类型	必填	说明
`client_type`	string	是	`web` / `app`（共用 Web/APP 应用）
`scene`	string	是	与获取验证 ID 时一致的应用场景
`verify_type`	string	是	与获取验证 ID 时一致的验证方式
`ticket`	string	是	前端验证码回调返回的票据（有效期 5 分钟、仅可校验一次）
`randstr`	string	是	前端验证码回调返回的随机串
`ip`	string	否	终端用户外网 IP；不传则取请求来源 IP（服务端调用时通常需显式传入）

{
  "code": 0,
  "message": "success",
  "data": {
    "biz_no": "83920174651293847561",
    "verified": true,                 // true=人机验证通过
    "captcha_code": "1",              // 平台结果码，1=通过
    "captcha_msg": "OK",
    "evil_level": "0",                // 恶意等级 0-100
    "evil_bitmap": "0",               // 风控标签位图
    "request_id": "984d6957-...",     // 排查问题时提供给平台
    "charge_status": 1,               // 平台是否收费
    "billed": true,                   // 本次是否计费
    "amount": 0.02,                   // 余额计费金额（资源包计费为 0）
    "pay_type": 1,                    // 0=资源包 1=余额
    "pack_count": 0,
    "client_type": "web",
    "scene": "account",
    "verify_type": "slide"
  }
}

5. 票据校验（微信小程序）

POST /v2/captcha/mini/verify：小程序插件只返回 ticket，无需 randstr；仍须传 scene，verify_type 固定为 slide （微信小程序仅支持滑动拼图），平台据此选择小程序验证 ID。

{
  "client_type": "mini",
  "scene": "account",
  "verify_type": "slide",
  "ticket": "<ticket>",
  "ip": "203.0.113.10"
}

6. 结果码（captcha_code）

结果码	含义	建议处理
`1`	验证通过	放行后续业务
`7`	答案或 randstr 不匹配	让用户重新验证
`8`	票据已过期（有效期 5 分钟）	重新验证
`9`	票据被重复校验	重新验证（一次票据仅可使用一次）
`13`	IP 不匹配	检查传入的 `ip` 是否为用户真实外网 IP
`15`	票据解密失败	检查 ticket/randstr 是否来自同一次验证
`16`	验证 ID 不匹配	确认使用平台下发的验证 ID
`21`	票据校验差异（多为前端容灾票据）	按业务风险策略决定是否放行

7. 计费规则

仅当平台确认本次校验收费（charge_status=1）时计 1 次；平台网络异常或接口报错不计费。
计费顺序：先扣行为验证码资源包次数，不足时扣余额；额度不足时接口直接返回 402，不发起核验。
票据校验未通过但平台已收费的，仍按 1 次计费（平台成本已发生）。

8. 前端接入要点

动态引入 https://service.starloft.cn/service/captcha/js（不要下载到本地缓存）。
按组合参数获取 captcha_app_id，用 new TencentCaptcha(captcha_app_id, callback) 后调用 show()；callback.ret=0 时取 ticket/randstr，服务端校验时传同一组三参数。
App 通过 WebView 加载上述 H5，用 JSBridge 把 ticket/randstr 回传原生端，再由业务服务端校验。
小程序在 app.json 声明插件 wx1fe8d9a3cb067a75，使用 <t-captcha> 组件取 ticket。
控制台「行为验证码 → 接入指引」提供可直接复制的完整示例与在线体验。