快速接入

Corptcha 是免安装、无侵入的人机验证服务：在你的网页中放置一个容器、引入 SDK 并初始化，用户完成验证后回调会返回一次性验证令牌（token）。将 token 随表单提交给后端，由后端向验证服务确认后即可放行。

第 1 步：创建站点，获取 Site ID

在控制台的「站点管理」中创建站点，即可获得 Site ID（形如 cpt_xxxxxxxxxxxx）。

Site ID 是公开的，可以安全地出现在前端代码里；请勿泄露密钥 Secret。

第 2 步：引入 SDK

在页面中引入 SDK 文件（仅一个脚本，无任何其它依赖），SDK 托管于国内静态资源 CDN。

<!-- 放在 </body> 之前，或使用 defer 属性 -->
<script src="https://res.25y.cn/corptcha/corptcha.iife.js"></script>

SDK 文件名固定不变，接入方无需因升级而改动代码。每次发版上传新文件后，请在 CDN 控制台刷新该 URL 的缓存（或将其缓存时间设短，如 no-cache / max-age=60）。自建部署时可改用验证服务自带的 /widget/corptcha.iife.js，或通过 npm install @corptcha/widget-sdk 本地打包引入。

第 3 步：渲染验证码

准备一个容器节点并调用 Corptcha.render() 初始化。

<div id="corptcha-widget"></div>
<input type="hidden" id="captcha-token" name="captchaToken" />

const widget = Corptcha.render(document.querySelector('#corptcha-widget'), {
  apiBaseUrl: 'https://cpt-api.25y.cn',     // 验证服务 API 地址
  siteKey: '你的 Site ID',                  // 形如 cpt_xxxxxxxxxxxx
  purpose: 'login',                         // 场景标识：login / register / comment 等
  language: 'zh-CN',
  theme: { mode: 'auto' },                  // light / dark / auto，可自定义 accentColor
  onSuccess: (token) => {
    // 验证通过：把 token 写入表单，随请求提交给后端
    document.querySelector('#captcha-token').value = token;
  },
  onError: (error) => {
    console.error(error.errorCode, error.message);
  },
  onExpired: () => {
    // token 过期，需要重新验证
    widget.execute();
  },
});

第 4 步：后端校验 token

前端获取的验证令牌是一次性的，请连同业务请求一起提交给后端。后端调用验证服务核验令牌通过后再执行业务逻辑，不要信任前端传递的任何布尔值。

// 后端示例（Node.js / 其它语言同理）：核验前端提交的 token
const response = await fetch('https://cpt-api.25y.cn/v1/verify', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    'authorization': 'Bearer 你的 Secret',   // 控制台「站点管理」中的站点密钥
  },
  body: JSON.stringify({
    token: '前端提交的 verificationToken',
    purpose: 'login',
    siteKey: '你的 Site ID',                  // 形如 cpt_xxxxxxxxxxxx
  }),
});

const result = await response.json();
if (!response.ok || result.success !== true) {
  // 拒绝请求（令牌无效、已使用或已过期）
  throw new Error(`人机验证未通过：${result.errorCode ?? 'UNKNOWN'}`);
}
// result.siteId / result.purpose / result.riskLevel 可用于审计或风控

token 只能被成功核验一次：重复使用同一个 token 会返回 TOKEN_NOT_FOUND。