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

Caputchin использует ту же двухчастную модель, что и hCaptcha, виджет на странице, который выдаёт токен, и серверную проверку, которая его подтверждает, так что переход это в основном механическая замена, а не переписывание. Серверный обмен в особенности повторяет форму `siteverify`, которой следует и сам hCaptcha. Это руководство даёт до-и-после для каждой части.

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

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

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

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

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

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

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

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

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

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

Одна заметка про формат: эндпоинт проверки hCaptcha ожидает `application/x-www-form-urlencoded`, а у Caputchin принимает JSON. Если твой существующий код слал поля в form-encoded виде, переключи тело на JSON (`{"secret":"...","response":"..."}`) с `Content-Type: application/json`. Сами поля не меняются. Полный справочник запроса/ответа на странице [проверь токен на своём бэкенде](/docs/integration-guides/verify-on-your-backend); сниппеты по фреймворкам в [примерах бэкенда](/docs/integration-guides/backend-examples).

## 3. Откажись от score, если ты использовал hCaptcha Enterprise

hCaptcha Enterprise возвращает рисковый `score` (где **выше** число означает **больше** риска) и просит тебя выбрать порог. Caputchin работает **не** так: `success` это авторитетное прошёл/не прошёл, потому что проверка действительно была пройдена (проверка proof-of-work или [игровой раунд, перевыведенный на сервере](/docs/understanding-caputchin/gaming-anti-cheat)), а не оценка риска.

Если в твоём коде было `if (data.score < 0.7)`, замени его на `if (data.success)`. Поле `score` у Caputchin никак не связано: оно существует только для игровых раундов и является счётом **игры** (информационным, для твоих собственных таблиц лидеров), никогда не риском или вероятностью бота, так что не привязывай к нему доступ. (Заметь, что направление тоже обратное, счёт hCaptcha растёт с риском; у Caputchin растёт с игровым результатом.)

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

- **Приватность, ради которой ты выбрал hCaptcha, сохранена.** 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_...`) остаётся только на сервере, ровно та же дисциплина, что и у hCaptcha. Не отправляй секрет в браузер.
- **Токен одноразовый.** Как и у hCaptcha, токен проверяется один раз. Не кэшируй и не повторяй его.
- **Поменяй имя поля, которое читает твой бэкенд.** Скрытое поле это `caputchin-token`, а не `h-captcha-response`, частый промах в одну строку.
- **Формат тела.** Шли запрос проверки как JSON, а не form-encoded.

## См. также

- [Добавь виджет](/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): преврати проверку в игру.