---
type: how-to
title: Переход с Cloudflare Turnstile
summary: "Замени Cloudflare Turnstile на Caputchin с минимальными изменениями: та же форма клиентский-виджет-плюс-серверная-проверка отображается почти один в один, и, как у Turnstile, результат это чистое прошёл/не прошёл, ниже до-и-после."
---

Caputchin использует ту же двухчастную модель, что и Cloudflare Turnstile, виджет на странице, который выдаёт токен, и серверную проверку, которая его подтверждает, так что переход это в основном механическая замена, а не переписывание. Turnstile из распространённых провайдеров ближе всех к Caputchin, потому что оба возвращают авторитетное прошёл/не прошёл, а не рисковый счёт, так что нет порога для перенастройки. Это руководство даёт до-и-после для каждой части.

Если ты ещё не создал аккаунт Caputchin и ключ сайта, сначала [создай аккаунт](/docs/getting-started/create-your-account); тебе понадобятся **публичный ключ** (`cpt_pub_...`) для страницы и **секрет** (`cpt_sec_...`) для бэкенда, то же разделение, что и у site key и secret key у Turnstile.

## Ментальная модель не меняется

```mermaid
flowchart LR
  A["Виджет на твоей странице"] -->|token| B["Твоя форма / запрос"]
  B -->|token| C["Твой бэкенд"]
  C -->|secret + token| D["эндпоинт siteverify"]
  D -->|success?| C
```

Всё, что ты уже построил вокруг Turnstile, отрендерить виджет, собрать токен, отправить его POST на сервер, проверить, прежде чем довериться запросу, остаётся. Меняются только имена и эндпоинты.

## 1. Замени клиентский сниппет

| | Turnstile | Caputchin |
|---|---|---|
| Скрипт | `<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer>` | `<script src="https://cdn.jsdelivr.net/npm/@caputchin/widget@3/dist/widget.js">` |
| Элемент | `<div class="cf-turnstile" data-sitekey="...">` | `<caputchin-widget sitekey="cpt_pub_...">` |
| Поле токена в форме | `cf-turnstile-response` (авто-вставка) | `caputchin-token` (авто-вставка) |
| Чтение токена в JS | `turnstile.getResponse()` | `detail.token` события [`pass`](/docs/references/widget-methods-and-events) |

Как и Turnstile, виджет Caputchin **авто-вставляет скрытое поле токена** в форму, в которой он сидит, так что если твоя форма уже делала обычный POST, ты меняешь только элемент и имя поля, которое читает твой бэкенд. Смотри [добавь виджет](/docs/getting-started/add-the-widget) для полной клиентской настройки и [выбор CDN или npm](/docs/integration-guides/cdn).

## 2. Замени серверную проверку

Вот где эти двое ближе всего, формы запроса и ответа сходятся почти поле в поле.

| | Turnstile | Caputchin |
|---|---|---|
| Эндпоинт | `POST https://challenges.cloudflare.com/turnstile/v0/siteverify` | `POST https://verify.caputchin.com/v1/siteverify` |
| Поля запроса | `secret`, `response` | `secret`, `response` (идентично) |
| Ответ | `{ success, challenge_ts, hostname, "error-codes", action, cdata }` | `{ success, challenge_ts, hostname, error-codes }` |
| Правило доверия | действуй только если `success === true` | действуй только если `success === true` (идентично) |

В большинстве стеков единственное изменение в твоём коде проверки это URL и значение секрета; оба уже ветвятся на `success`, так что нет порога счёта для переноса. Turnstile тоже принимает JSON для вызова проверки, ровно как Caputchin, так что форма тела переносится без изменений. Полный справочник запроса/ответа, включая коды ошибок, на странице [проверь токен на своём бэкенде](/docs/integration-guides/verify-on-your-backend); сниппеты по фреймворкам в [примерах бэкенда](/docs/integration-guides/backend-examples).

Если твоя интеграция Turnstile читала `action` или `cdata` из ответа, заметь, что у Caputchin нет прямого эквивалента; это специфичные для Turnstile метки, которые ты задаёшь на виджете. Аналогичные метаданные Caputchin (в какую игру играли, её счёт) живут в блоке `platform` ответа и только информационные.

## Что переносится, а что становится лучше

- **По-прежнему чистое прошёл/не прошёл.** Ты сохраняешь простейшее возможное правило доверия, `if (success)`, без вероятности или порога для поддержки.
- **Приватность, ради которой ты выбрал Turnstile, сохранена.** Caputchin не собирает ни IP, ни User-Agent, ни цифровой отпечаток, ни поведенческую телеметрию; протоколу некуда поместить идентификатор посетителя. Смотри [философию](/docs/understanding-caputchin/philosophy).
- **Опциональная игра.** Вместо невидимого или управляемого испытания ты можешь превратить проверку в короткую игру, в которую твои посетители и правда играют, и это та часть, что выстаивает против ИИ-решателей. Смотри [добавь игру](/docs/getting-started/add-a-game).
- **Строгий CSP остаётся строгим.** Caputchin работает под жёсткой Content-Security-Policy; ты разрешаешь несколько источников, а не ослабляешь свою политику. Смотри [как Caputchin изолирует игры в песочнице](/docs/understanding-caputchin/game-sandboxing#the-csp-you-set-on-your-own-page).

## Подводные камни

- **Два ключа, два дома.** Публичный ключ (`cpt_pub_...`) идёт на страницу; секрет (`cpt_sec_...`) остаётся только на сервере, ровно та же дисциплина, что и у Turnstile. Не отправляй секрет в браузер.
- **Токен одноразовый.** Как и у Turnstile, токен проверяется один раз. Не кэшируй и не повторяй его.
- **Поменяй имя поля, которое читает твой бэкенд.** Скрытое поле это `caputchin-token`, а не `cf-turnstile-response`, частый промах в одну строку.
- **Нет `action` / `cdata`.** Если ты ветвился на них, перенеси эту логику в другое место; Caputchin их не несёт.

## См. также

- [Добавь виджет](/docs/getting-started/add-the-widget): полная клиентская настройка.
- [Проверь токен на своём бэкенде](/docs/integration-guides/verify-on-your-backend): авторитетный справочник `siteverify`.
- [Примеры бэкенда](/docs/integration-guides/backend-examples): вызов проверки на каждом языке.
- [Добавь игру](/docs/getting-started/add-a-game): преврати проверку в игру.