---
type: how-to
title: 服务端集成
summary: 从一次提交里取出 caputchin-token，在信任请求之前用 /siteverify 确认它。
---

组件递给浏览器一个一次性令牌。在你的服务器用 Caputchin 确认它之前，这个令牌什么都证明不了。这是把一个看得见的挑战变成真正防护的那一步，而它只是一个 HTTPS 调用。

你需要一个能发出站请求的后端，以及在那里可用的你站点密钥的密钥（`cpt_sec_...`），绝不放在浏览器里。

## 1. 读取令牌

当表单提交时，你的处理器会在你自己的字段旁收到一个额外字段：`caputchin-token`。访客通过挑战时，组件把它注入到了表单里。

## 2. 用 /siteverify 确认它

POST 这个令牌和你的密钥。请求和响应的形状仿照 reCAPTCHA 的 `siteverify`，所以一个现有的集成几乎不用改就能移植过来：

```http
POST https://verify.caputchin.com/v1/siteverify
Content-Type: application/json

{ "secret": "cpt_sec_...", "response": "<caputchin-token>" }
```

```js
// Node 18+
const verdict = await fetch("https://verify.caputchin.com/v1/siteverify", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    secret: process.env.CAPUTCHIN_SECRET,
    response: token,
  }),
}).then((r) => r.json());

if (!verdict.success) {
  // reject the submission
}
```

同样的调用在其他语言里见 [后端集成示例](/docs/integration-guides/backend-examples)。

## 3. 读取响应

```json
{
  "success": true,
  "error-codes": [],
  "platform": { "game_id": "caputchin/games/leaf-memory", "score": 847, "duration_ms": 4200 }
}
```

- **`success`** 是唯一要据以分支的东西。`true` 意味着一位真实访客通过了挑战；信任该请求。`false` 意味着丢弃它。
- **`error-codes`** 在 `success` 为 `false` 时出现，点明出了什么错（一个缺失的、过期的或已用过的令牌，等等）。
- **`platform`** 是客户端声称的元数据（哪个游戏、分数、时长）。它可为空，并且 **不是安全信号**。你愿意的话可以为分析记录它，但绝不要把信任系在分数上。

## 保护你的那些规则

- **一次性使用。** 一个令牌只核验一次。再次提交同一个会返回 `success: false`，所以你不必自己追踪重放。
- **短时有效。** 一个令牌在签发十分钟后过期，所以在处理这次提交时就核验它，而不要放到一个延迟任务里。
- **密钥留在服务器上。** 它绝不去浏览器，而它正是为这个调用做身份验证的东西。

## 常见错误

- **在客户端核验。** `pass` 事件和令牌的存在只是 UX。每一个信任决定都发生在这里，在服务端，用你的密钥。
- **据 `score` 设关卡。** 它是元数据，不是一个置信度值。

## 常见问题

### 一个令牌有效多久？

签发后十分钟。在你处理这次提交时就核验它，而不要从一个延迟任务、或一个可能稍后才运行的队列里核验。

### 我能对同一个令牌核验两次吗？

不能。令牌是一次性的。再次提交同一个会返回 `success: false`，所以你不必自己追踪重放。

### 我该信任 `score` 或 `game_id` 吗？

不该。`platform` 块（游戏、分数、时长）是客户端声称的元数据，并且可为空。只根据 `success` 分支，绝不要把信任系在分数上。

### 做这个需要 SDK 吗？

不需要。这道检查就是向 `/v1/siteverify` 发一个 HTTPS POST。在 Node、Python、PHP、Go、Ruby、.NET 和 curl 里的同一个调用见 [后端集成示例](/docs/integration-guides/backend-examples)。

## 另见

- [后端集成示例](/docs/integration-guides/backend-examples)，看响应形状和那些规则。
- [托管验证](/docs/hosted-verification/overview)，完全跳过后端。