<!-- Capcat 文档「快速开始」的 Markdown 版本（对应页面 https://capcat.ai/cn/guide/index.html）。全部文档索引：https://capcat.ai/llms.txt -->

# 快速开始

Capcat 是托管人机验证服务：你不需要部署或维护任何服务端，在控制台创建站点获得密钥，页面里放入**前端组件**，业务后端调一个**校验接口**即可。整个接入过程大约 5 分钟。

[先看在线体验 →](https://capcat.ai/cn/guide/demo.md)

## 1. 创建站点，获取密钥

打开 [console.capcat.ai](https://console.capcat.ai/cn)，用邮箱和密码注册并登录，点「新建站点」。你会得到两把密钥：

- **site key** —— 公开值，写在页面代码里；
- **secret** —— 保密值，只在创建时展示一次，供你的后端调用校验接口。

建好站点后建议顺手[绑定域名](https://capcat.ai/cn/guide/console.md#_3-绑定域名-强烈建议)，防止别人盗用你的 site key。

## 2. 页面加入组件

组件是一个独立的 Web Component，通过一个 `<script>` 引入：

```html
<script src="https://capcat.ai/widget/cap.js" defer></script>
```

放进 `<form>` 里时无需写任何 JavaScript，组件会自动注入隐藏的 `cap-token` 字段并随表单提交：

```html
<form action="/submit" method="POST">
  <!-- 你的表单字段 -->
  <cap-widget data-cap-api-endpoint="https://api.capcat.ai/<site-key>/"></cap-widget>
  <button type="submit">提交</button>
</form>
```

把 `<site-key>` 换成控制台里的 site key 即可。SPA 或自定义流程见[前端组件](https://capcat.ai/cn/guide/widget.md)。

## 3. 服务端校验 token

信任任何提交之前，先把 token 发到 `/siteverify` 校验：

```sh
curl "https://api.capcat.ai/<site-key>/siteverify" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{ "secret": "<secret>", "response": "<captcha_token>" }'
```

校验通过返回：

```json
{ "success": true }
```

token 一次性有效，校验一次后即失效。更多语言示例见[服务端验证 API](https://capcat.ai/cn/guide/siteverify.md)。

> **注意**
>
> `secret` 绝不能出现在前端代码里——它只属于你的服务器。丢失后可在控制台轮换（旧 secret 有 1 小时宽限期）。

## 4. 端到端确认

1. 打开页面，复选框应自动打勾，表单里出现 `cap-token` 字段；
2. 把 token 发给 `/siteverify`，应返回 `{ "success": true }`；
3. 用同一个 token 再发一次，应当失败——说明一次性机制正常。

## 接口与迁移

`/siteverify` 与 reCAPTCHA / hCaptcha 的接口兼容：从它们迁移时，服务端通常只需要改一个 URL，前端把组件换成 `<cap-widget>` 即可。Capcat 基于开源项目 [Cap](https://github.com/tiagozip/cap)（Apache 2.0）构建。
