---
name: corptcha-integration
description: 为用户的 Web 项目接入 Corptcha 人机验证服务。当用户需要在网站、Web 应用、SPA 或表单中添加人机验证、验证码、CAPTCHA、滑块/点击验证，或明确要求接入 Corptcha 时使用。技能涵盖前端 SDK 挂载、一次性验证令牌获取，以及后端多语言（Node.js/Python/Java/Go/PHP）服务端校验的完整流程、接口协议与排错方法。
---

# Corptcha 接入技能

Corptcha 是免安装、无侵入的人机验证服务：前端放置容器并初始化 SDK，用户完成验证后回调返回**一次性验证令牌（token）**；token 随业务表单提交给后端，由后端调用验证服务核验通过后再执行业务逻辑。**后端必须校验，禁止信任前端传来的任何布尔值。**

## 接入前置

先向用户确认（或在其项目中查找）以下两项，缺失则提示用户在控制台创建：

- **Site ID**（`cpt_` 开头，可出现在前端）—— 控制台「站点管理」创建站点获得
- **Secret**（站点密钥，只能出现在后端）—— 同上，与 Site ID 同页面

## 第 1 步：前端引入 SDK

在页面 `</body>` 前或应用入口引入（一个 `<script>`，无其它依赖）：

```html
<script src="https://res.25y.cn/corptcha/corptcha.iife.js"></script>
```

## 第 2 步：挂载验证组件

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

```js
const widget = Corptcha.render(document.querySelector('#corptcha-widget'), {
  apiBaseUrl: 'https://cpt-api.25y.cn',
  siteKey: '你的 Site ID',
  purpose: 'login',                 // 与后端校验时保持一致
  language: 'zh-CN',
  theme: { mode: 'auto' },
  onSuccess: (token) => {
    document.querySelector('#captcha-token').value = token;
  },
  onError: (error) => {
    console.error(error.errorCode, error.message);
  },
  onExpired: () => widget.execute(),
});
```

实例方法：`execute()` / `reset()` / `destroy()`。其余渲染参数见 `references/corptcha-api.md`。

## 第 3 步：后端校验 token（必须）

- **接口**：`POST https://cpt-api.25y.cn/v1/verify`
- **鉴权**：请求头 `Authorization: Bearer {Secret}`
- **请求体**：`{ "token": "...", "purpose": "login", "siteKey": "cpt_xxx" }`
- **成功**：HTTP 200 `{ success: true, siteId, purpose, issuedAt, riskLevel, requestId }`
- **失败**：HTTP 4xx `{ errorCode, message, requestId }`（`TOKEN_NOT_FOUND` / `TOKEN_EXPIRED` / `TOKEN_PURPOSE_MISMATCH` / `UNAUTHORIZED` 等）

按用户后端的语言在 `references/corptcha-api.md` 中选取对应示例（Node.js / Python / Java / Go / PHP），逻辑一致：**非 200 或 `success !== true` 即拒绝请求**。

## 接入检查清单

- SDK 引入无报错；`siteKey` 为真实 Site ID
- 前端 `purpose` 与后端校验 `purpose` 一致
- Secret 只存在于后端，`Bearer` 鉴权调用 `/v1/verify`
- 校验失败（非 200 或 `success !== true`）时中断业务，并提示用户重新验证
- 未信任前端布尔值；token 一次性，重复使用返回 `TOKEN_NOT_FOUND`