DOCUMENTATION · V1

把 CAPTCHA 接入
你的关键动作。

浏览器 Widget 可随机展示滑动拼图、顺序点选、障碍躲避，也可使用 PoW 快速验证；你的后端始终负责最终校验和消费。

QUICK START

快速开始

加载 Widget从固定 HTTPS 地址加载 ES Module。
选择挑战策略默认随机轮换 3 种视觉挑战，也可固定题型或切换为 PoW。
服务端终验提交表单后，用 Secret 调用 siteverify，并核对 hostname 与 action。

PUBLIC TEST MODE

公共测试凭据

仅用于本地与集成测试。测试 Key 接受任意 HTTP/HTTPS Origin，返回结果带 test_mode: true。

Site Key: site_test_shareapi_public
Secret: secret_test_shareapi_public

BROWSER

前端 Widget

组件是 form-associated Custom Element，验证成功后会以 name 指定的字段名提交响应令牌。

index.html

<script type="module"
  src="https://captcha.shareapi.ai/captcha.js"></script>

<form method="post" action="/signup">
  <shareapi-captcha
    sitekey="site_test_shareapi_public"
    action="signup"
    mode="visual"
    challenge="random"
    name="captcha-response"
    required>
  </shareapi-captcha>
  <button>注册</button>
</form>

属性	必需	说明
`sitekey`	是	公开 Site Key。
`action`	建议	小写字母开头，最长 64 字符。
`mode`	否	`visual`（默认）或兼容模式 `pow`。
`challenge`	否	`random`（默认）、`puzzle`、`icons` 或 `dodge`。
`name`	否	表单字段名，默认 `captcha-response`。
`language`	否	界面语言，默认读取页面语言。
`api-base`	否	自托管 API Origin；默认与脚本同源。

SERVER

服务端终验

Secret 只能保存在业务服务端。成功响应也必须核对 action 与 hostname 是否符合当前请求。

server.js

const result = await fetch(
  'https://captcha.shareapi.ai/api/v1/siteverify',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      secret: process.env.CAPTCHA_SECRET,
      response: req.body['captcha-response']
    })
  }
).then(r => r.json());

if (!result.success || result.action !== 'signup') {
  return res.status(400).send('CAPTCHA verification failed');
}

一次性语义

同一个响应令牌只有第一次 siteverify 会返回成功。验证失败、网络重试或业务事务失败时，应要求客户端重新完成挑战。

API REFERENCE

接口参考

接口	调用方	用途
`GET /api/v1/challenge`	Widget	签发 5 分钟内有效的来源/action 绑定视觉挑战或 PoW。
`POST /api/v1/verify`	Widget	校验图形答案或 PoW，并换取 2 分钟一次性响应令牌。
`POST /api/v1/siteverify`	业务服务端	用 Secret 校验并消费响应令牌。
`GET /api/v1/health`	监控	检查服务与 PostgreSQL 状态存储是否可用。

ERRORS

错误码

missing-input-secret

未提交 Secret。

invalid-input-secret

Secret 不存在或已停用。

missing-input-response

未提交响应令牌。

invalid-input-response

响应格式或签名无效。

timeout-or-duplicate

已过期或已被消费。

sitekey-secret-mismatch

响应令牌不属于该 Secret。

origin-mismatch

挑战来源与当前浏览器来源不一致。

invalid-solution

图形答案、顺序或躲避路径未通过。

rate-limited

请求超过当前限额。

SECURITY

生产安全要求

永远不要把生产 Secret 写进浏览器、移动 App 或公开仓库。
允许来源使用精确 Origin；不要给生产 Key 配置通配符。
始终核对 siteverify 返回的 action 和 hostname。
把 CAPTCHA 与 WAF、接口限流、账号信誉和业务幂等共同使用。

把 CAPTCHA 接入你的关键动作。