Капча для форм: свои задания без внешних сервисов, Яндекс SmartCaptcha и Google reCAPTCHA

Сначала подключите одну форму на тестовой копии

Установка модуля и включение записи в реестре сами по себе не защищают произвольный обработчик. Ниже приведены отдельные способы подключения для веб-форм Битрикса, регистрации, main.feedback, Intec Startshop, topman.callbackform и собственного PHP-кода. Для нестандартной формы потребуется разработчик.

1. Сделайте резервную копию сайта и установите решение через штатный список партнёрских модулей Битрикс. Для установки нужны права администратора.
   
2. Откройте «Top Man Digital → Капча» и выберите сайт. После новой установки модуль и защита форм выключены. Штатная страница «Настройки модулей → Top Man Digital: Капча» содержит права доступа и ссылку на этот экран.
   
3. На вкладке «Капча» выберите вид проверки. Настройте задание, срок ответа, число попыток и срок запоминания успеха. Для пазла нужен GD. Для внешнего сервиса заполните ключи и разрешите домен у поставщика. Google v2 и v3 используют разные типы ключей; в модуле хранится одна пара для выбранной версии. Пустое поле секрета при сохранении не стирает сохранённый секрет.
   
4. На вкладке «Формы» добавьте постоянный ключ формы и включите запись. Для веб-формы Битрикс используется form_НОМЕР, для регистрации — main_register. Для своей формы ключ должен совпадать с id, name, data-tmc-form или data-tab-form.
   
5. Подключите серверную проверку по разделам ниже. HTML-метка подключает окно в браузере, но не защищает произвольный обработчик от прямого POST.
   
6. Если нужна замена старой капчи, сначала подключите её серверную замену. Только после этого разрешите скрытие старых полей через Forms::bind(..., true). Сохраните исходные настройки для возврата штатной капчи при отключении модуля.
   
7. Включите модуль и защиту форм. Проверьте отсутствие ответа, неверный ответ и успех: при отказе не должно быть результатов или писем, при успехе должно выполниться одно предусмотренное действие.
   

Для настройки прав откройте штатную страницу настроек модуля. Чтение и изменение разделены; выдавайте право изменения только ответственным администраторам.

Код ниже ставится в фактический обработчик отправки после штатного пролога, собственной CSRF-проверки и валидации полей, перед первым сохранением или письмом. Замените request на постоянный ключ вашей формы. Сайт и ключ задаются в коде обработчика, а не берутся из POST. Пример возвращает JSON; для HTML-формы выведите сообщение в её существующем блоке ошибок.

$loaded = \Bitrix\Main\Loader::includeSharewareModule('topman.captcha');
if (!in_array($loaded, [\Bitrix\Main\Loader::MODULE_INSTALLED, \Bitrix\Main\Loader::MODULE_DEMO], true)) {
    http_response_code(503);
    echo \Bitrix\Main\Web\Json::encode(['ok' => false, 'message' => 'Проверка формы недоступна. Повторите позже.']);
    return;
}
$check = \Topman\Captcha\Forms::check(SITE_ID, 'request');
if ($check['required']) {
    \Topman\Captcha\Table\LogTable::record(SITE_ID, 'request', $check['allowed'] ? 'allowed' : 'blocked', $check['allowed'] ? '' : 'challenge_required');
}
if (!$check['allowed']) {
    http_response_code(403);
    echo \Bitrix\Main\Web\Json::encode(['ok' => false, 'message' => $check['message']]);
    return;
}
// Далее существующие сохранение и письмо — по одному вызову.

Forms::check() возвращает required, allowed и message; сам не отправляет ответ и не выполняет бизнес-действия. Для своего обработчика запись журнала добавляется на реальной отправке, как в примере. Встроенные ранние события записывают результат сами.

При подготовке страницы можно привязать другой селектор:

\Topman\Captcha\Forms::bind(SITE_ID, 'request', ['#request-modal form']);

При отправке через событие submit модуль получает допуск и один раз повторяет requestSubmit() с исходной кнопкой. Для AJAX по click и низкоуровневого form.submit() до существующего запроса нужно дождаться проверки:

const result = await TopmanCaptchaForms.ensure(form);
if (!result.ok) return;
// Далее существующий AJAX-запрос сайта.

ensure() сам заявку не отправляет. Не вызывайте бизнес-обработчик ещё раз из callback капчи. Динамические экземпляры поддерживаются, если их ключи уже включены в начальную конфигурацию страницы. Для динамической замены старых полей вызовите bind(..., true) при подготовке исходной страницы. Если форма добавляется и отправляется в одном JS-вызове, сначала нужен ensure(form).

В проверенных версиях нет подходящего раннего события до целевого действия. Добавьте проверку в вызывающий код сайта перед IncludeComponent, не меняя компонент поставщика.

1. Сохраните исходные параметры компонента, в том числе USE_CAPTCHA=Y для возврата штатной капчи.
   
2. Подключите доступный модуль через includeSharewareModule(). При недоступности передайте исходный компонент со штатной капчей. Если безопасной штатной проверки нет, остановите действие с ошибкой.
   
3. Определите реальную отправку своей формы и вызовите Forms::check(SITE_ID, фиксированныйКлюч). При отказе выведите ошибку и не вызывайте компонент.
   
4. У main.feedback только при required=true передайте в локальную копию параметров USE_CAPTCHA=N. Эта проверка нужна и для авторизованного посетителя.
   
5. Startshop 1.0.3 читает настройку капчи из БД и игнорирует параметр компонента. Только при required=true && allowed=true вызовите Forms::nativeCaptcha(SITE_ID, ключ, 'CAPTCHA_SID', 'CAPTCHA_CODE'). При false остановите действие; при required=false мост не вызывайте. Настройку формы в БД не меняйте.
   
6. Для поддерживаемой замены вызовите Forms::bind(SITE_ID, ключ, [селектор], true) и выполните исходный компонент один раз.
   

У Startshop проверенное действие — action=send, штатные поля — CAPTCHA_SID и CAPTCHA_CODE; номер формы фиксируется на сервере. У main.feedback используются штатные submit и PARAMS_HASH. Перехват одного почтового события Startshop недостаточен: к этому моменту результат уже сохранён.

Для веб-форм используется ключ form_ЧИСЛО и событие form:onBeforeResultAdd, для регистрации — main_register и main:OnBeforeUserRegister. Включите нужную запись реестра. Регистрация с этим ключом охватывает публичные вызовы события сайта, включая CUser::Register() из другого кода.

Для замены штатной modern CAPTCHA перед компонентом проверьте реальную отправку через Forms::check(). У веб-формы задайте фиксированный WEB_FORM_ID. Только при required=true && allowed=true вызовите Forms::nativeCaptcha(SITE_ID, ключ). Если результат false, не запускайте сохранение. Затем включите скрытие старых полей через bind(..., true).

Старый режим CAPTCHA_COMPATIBILITY не поддерживается, даже если константа определена как false: ядро выбирает legacy-ветку по самому факту её определения. Не скрывайте старую капчу в таком режиме. Глобальные настройки регистрации и веб-формы не меняются.

Для прямого CUser::Register() передайте созданные captcha_word и captcha_sid в соответствующие аргументы. CUser::Add() не вызывает событие регистрации и требует отдельной проверки до вызова. Прямой CFormResult::Add() защищается событием; произвольный SQL — нет.

Нужны исходный topman.callbackform и собственный шаблон компонента в коде сайта. Ключ реестра должен совпадать с серверным FORM_ID. В исходные параметры компонента добавьте TOPMAN_CAPTCHA_SITE_ID => SITE_ID. В шаблоне перед существующим new JCCallbackForm(...) подготовьте параметры браузера:

$browserParams = $arParams;
$loaded = \Bitrix\Main\Loader::includeSharewareModule('topman.captcha');
if (in_array($loaded, [\Bitrix\Main\Loader::MODULE_INSTALLED, \Bitrix\Main\Loader::MODULE_DEMO], true)) {
    $browserParams = \Topman\Captcha\Forms::callbackParameters(SITE_ID, $arParams['FORM_ID'], $arParams);
}
$browserParams = array_intersect_key($browserParams, array_flip([
    'FORM_ID', 'FORM_SUBMIT', 'SEND_AJAX', 'SHOW_MODAL', 'USE_HYSTMODAL', 'USE_CAPTCHA',
    'USE_FORMVALIDATION_JS', 'USE_FORM_MASK_JS', 'CAPTCHA_KEY', 'COMPONENT_NAME', 'SIGNED_PARAMS', '_CALLBACKS',
]));
// Передайте $browserParams в существующий JCCallbackForm вместо $arParams.

Адаптер сохраняет исходную подпись параметров внутри собственной и проверяет капчу перед действием. Только для прошедшего посетителя штатная капча отключается в локальных параметрах вызова. Исходное подписанное USE_CAPTCHA=Y оставьте для возврата при отключении модуля. Старые страницы с прежними подписями обновите.

Сохраните штатный AJAX-контракт исходника: Engine, signedParameters, sessid, FIELDS, FORM_ID и заголовок X-Requested-With: XMLHttpRequest. Не отправляйте в браузер все $arParams или $arResult. Секреты внешних капч исходного модуля храните в его настройках, не в inline-параметрах компонента: подпись не шифрует данные.

Лимит ответов на вкладке «Капча» учитывается по адресу соединения, сайту и форме. Сброс cookie его не обнуляет. Посетители с общим IP делят лимит; значение 0 отключает только этот предел ответов.

Выдача новых заданий ограничена отдельно: до 60 за 60 секунд для одного адреса, сайта и формы. Успешный ответ не сбрасывает этот бюджет. В состоянии хранится HMAC адреса. Используется REMOTE_ADDR; настройки доверенного прокси в журнале на лимиты не влияют. За прокси веб-сервер должен передавать в REMOTE_ADDR корректный адрес посетителя.

Истёкшие записи состояния удаляются ограниченными порциями при выдаче заданий. Отдельного фонового агента нет.

Доступны режимы «Выключен», «Только блокировки» и «Все события». Срок хранения применяется при следующей записи, отдельного фонового агента очистки нет. Журнал не содержит полей заявки, токенов и ответов капчи. При включённом маскировании хранится сеть /24 для IPv4 и /64 для IPv6; это маскирование, а не обещание анонимности. Доверенные прокси настраивайте только при наличии такого прокси: это влияет на адрес в журнале.

При недоступности модуля вызывающий код сайта должен вернуть штатную капчу либо остановить действие до сохранения и письма. Эта проверка должна оставаться вне файлов модуля и выполняться на каждом фактическом входе отправки, включая отдельный AJAX. Одних ранних событий или реестра недостаточно, если модуль перестал подключаться.

Отключите защиту и проверьте штатное поведение форм. На уже открытой странице при следующей перехваченной отправке или ensure() исходные поля восстанавливаются и проверяются заново. После повторного включения обновите страницу либо явно вызовите ensure() перед своим AJAX. При недоступном endpoint отправка останавливается с ошибкой.

Удаление предлагает сохранить собственные данные или удалить их. При сохранении остаются настройки, реестр и журнал; повторная установка возвращает прежние собственные настройки. Чужие файлы и настройки не удаляются. Проверьте состояние защиты перед открытием сайта.

Если рядом установлен topman.antibot, для одной формы оставьте одну открытую капчу. Настройки второго модуля меняются вручную.

На тестовой копии выполните прямой POST без ответа и отправку с неверным ответом: результат и уведомление не должны создаваться. При успехе должно выполняться одно предусмотренное действие. Проверьте обычную, AJAX- и динамическую отправку, повторное открытие модального окна и авторизованного посетителя. Запоминаемый допуск не запрещает отдельные повторные заявки уже прошедшего посетителя.

При ошибке проверьте выбранный сайт, активность реестра, постоянный серверный ключ и формат AJAX. Технический отказ внешнего сервиса не разрешает отправку; посетителю предлагается повторить проверку. Для диагностики нужны версии PHP, Битрикс и компонента, ключ формы и код ошибки журнала. Не передавайте секретные ключи, cookie и содержимое заявок.

Требуются PHP 8.2+, MySQL/MariaDB с InnoDB, JavaScript и cookie; для пазла — GD. Проверенные сценарии относятся к Bitrix main 26.150.0, form 26.0.0, Intec Startshop 1.0.3 и topman.callbackform 1.0.3 на PHP 8.3.36. Другие версии требуют отдельной проверки.