Логотип «2Captcha»Перейти на главную страницу
Туториалы по обходу капчи

Эта статья была полезной?

Как сделать настройку автоматического получения ответов через pingback

Катя Пушкаренва

Технический специалист

Введение

Это руководство предназначено для разработчиков, которые интегрируют API 2Captcha и хотят получать результаты решения капч автоматически, без периодических опросов метода getTaskResult. Мы разберём, как настроить pingback (callback), зарегистрировать домен, обработать входящие запросы и избежать типичных ошибок.

Необходимые инструменты:

  • Любой язык программирования с поддержкой HTTP-запросов
  • API-ключ от 2Captcha
  • Публично доступный сервер или веб-хук для приёма POST-запросов
  • Базовые знания работы с FormData и URLencoded-данными

1. Общие сведения о pingback

1.1. Что такое pingback

Pingback (также называемый callback или webhook) — это механизм автоматической доставки результата решения капчи на ваш сервер. Вместо того чтобы постоянно опрашивать https://2captcha.com/res.php, вы указываете URL, на который 2Captcha сам отправит ответ, как только капча будет решена.

1.2. Преимущества перед опросом (polling)

Критерий Polling (getTaskResult) Pingback
Нагрузка на аккаунт Высокая (частые запросы) Минимальная
Задержка получения ответа Зависит от интервала опроса Мгновенно после решения
Риск блокировки Есть при превышении лимитов Отсутствует
Сложность реализации Низкая Средняя (нужен обработчик)
Надёжность Зависит от вашей логики повторов Гарантированная доставка от 2Captcha

1.3. Формат входящего запроса

2Captcha отправляет данные в виде application/x-www-form-urlencoded с двумя параметрами:

  • id — идентификатор задачи, который вы получили при создании капчи
  • code — результат решения (токен, ответ или код ошибки)

Пример тела запроса из документации:

Copy 
id=51555263943&code=ANSWER

2. Подготовка окружения

2.1. Регистрация домена или IP

Перед использованием pingback необходимо зарегистрировать адрес, на который будут приходить ответы. Это можно сделать через веб-интерфейс или с помощью API-запросов к https://2captcha.com/res.php.

Параметры GET-запросов для управления pingback:

Параметр Тип Обязателен Описание
key Строка Да Ваш ключ API
action Строка Да add_pingback, get_pingback или del_pingback
addr Строка Нет Ваш URL для отправки ответа
json Число Нет 0 — простой текст, 1 — формат JSON

Примеры запросов из документации:

Добавить новый адрес:

Copy 
https://2captcha.com/res.php?key=1abc234de56fab7c89012d34e56fa7b8&action=add_pingback&addr=https://mysite.com/test.php

Получить список зарегистрированных адресов:

Copy 
https://2captcha.com/res.php?key=1abc234de56fab7c89012d34e56fa7b8&action=get_pingback&json=1

Удалить все зарегистрированные адреса:

Copy 
https://2captcha.com/res.php?key=1abc234de56fab7c89012d34e56fa7b8&action=del_pingback&addr=all

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

2.2. Получение API-ключа

  1. Зарегистрируйтесь на 2captcha.com
  2. Перейдите в настройки аккаунта
  3. Скопируйте API-ключ
  4. Рекомендуется хранить ключ в переменной окружения

3. Анализ и извлечение параметров

3.1. Определение URL для pingback

Выберите публично доступный эндпоинт, который будет принимать уведомления. Примеры:

  • https://api.yourservice.com/captcha/callback
  • https://123.123.123.123/pingback
  • https://mysite.com/hook?service=2captcha

3.2. Важное ограничение для GET-запросов

Если вы отправляете капчу через GET-запрос к https://api.2captcha.com/in.php, а ваш pingback-URL содержит несколько параметров, например:

Copy 
https://mysite.com/pingback/?myId=1&myCat=2&something_else=test

— то сохранится и будет использован только первый параметр ?myId=1.

Решение: Используйте POST-запросы с multipart/form-data при отправке задач, если ваш callback-URL содержит параметры.

4. Реализация решения

4.1. Отправка задачи с pingback

Добавьте параметр pingback в ваш запрос к https://2captcha.com/in.php. Пример из документации:

Copy 
key=YOUR_API_KEY&method=userrecaptcha&googlekey=SITE_KEY&pageurl=PAGE_URL&pingback=https://mysite.com/pingback

4.2. Обработка входящего запроса

Ваш сервер должен принимать POST-запросы с типом контента application/x-www-form-urlencoded. Запрос содержит два параметра:

  • id — идентификатор капчи
  • code — ответ на капчу

Пример входящего запроса:

Copy 
id=51555263943&code=ANSWER

4.3. Минимальный обработчик (псевдокод)

Copy 
Получить POST-запрос на /pingback
Извлечь параметры id и code из тела запроса
Проверить источник запроса (опционально)
Обработать результат:
  - Сохранить в базу данных
  - Отправить в очередь задач
  - Уведомить пользователя
Вернуть статус 200 OK

5. Пояснения к реализации

Параметр pingback:

  • Передаётся в запросе к in.php как обычный параметр
  • Значение — полный URL вашего обработчика
  • Должен быть предварительно зарегистрирован через add_pingback

Обработка входящих данных:

  • Данные приходят в формате application/x-www-form-urlencoded
  • Всегда проверяйте наличие обоих параметров: id и code
  • Возвращайте статус 200 OK для подтверждения получения

Безопасность:

  • Рекомендуется проверять IP-адрес отправителя
  • Используйте HTTPS для вашего pingback-эндпоинта
  • Не логируйте чувствительные данные (токены, ключи)

Асинхронная обработка:

  • Обработчик должен отвечать быстро (в течение нескольких секунд)
  • Если обработка результата занимает время — отправляйте данные в очередь и отвечайте OK сразу

6. Альтернативные методы и дополнительные настройки

6.1. Гибридный подход: pingback + резервный опрос

Для максимальной надёжности можно комбинировать оба метода: отправлять задачу с pingback, но при необходимости запускать резервный опрос getTaskResult, если ответ не пришёл в ожидаемое время.

6.2. Передача дополнительных параметров

Вы можете добавить свои параметры в URL pingback:

Copy 
https://mysite.com/pingback?user_id=123&session=abc

Помните об ограничении для GET-запросов: если отправляете задачу через GET, сохранится только первый параметр. Для передачи нескольких параметров используйте POST с multipart/form-data.

6.3. Мониторинг времени решения

Для реализации алертов (как в исходном запросе пользователя) замеряйте время между отправкой задачи и получением pingback. Если интервал превышает порог — отправляйте уведомление в вашу систему мониторинга.

7. Требования к обработчику pingback

Требование Описание
Поддержка POST Обработчик должен принимать POST-запросы
Формат данных application/x-www-form-urlencoded
Параметры id и code в теле запроса
Ответ Статус 200 OK для подтверждения получения
Доступность Публичный URL, доступный из интернета
Безопасность Рекомендуется проверка источника и использование HTTPS

8. Типичные ошибки и способы их устранения

Ошибка Возможная причина Решение
Pingback не приходит Адрес не зарегистрирован Добавьте адрес через add_pingback перед отправкой задач
Получены не все параметры URL Отправка задачи через GET с несколькими параметрами в callback Используйте POST с multipart/form-data
Ошибка 403 на обработчике Блокировка по IP или отсутствие проверки источника Настройте фаервол или добавьте проверку IP 2Captcha
Дублирование обработки Одновременная работа pingback и polling Используйте флаги или уникальные идентификаторы задач
Таймаут обработчика Долгая обработка результата Отвечайте 200 OK сразу, обработку вынесите в фоновую задачу

8.1. Отладка pingback

Для анализа проблем включите логирование на стороне обработчика:

  • Логируйте входящие запросы (без чувствительных данных)
  • Проверяйте заголовки Content-Type и User-Agent
  • Тестируйте обработчик локально с помощью инструментов вроде curl или Postman

9. Дополнительные ресурсы

10. Контрольный список перед запуском

  • Зарегистрирован домен или IP для pingback через add_pingback
  • Обработчик принимает POST-запросы с application/x-www-form-urlencoded
  • Обработчик извлекает параметры id и code из тела запроса
  • Обработчик возвращает статус 200 OK после получения данных
  • Используется HTTPS для pingback-эндпоинта
  • Реализована проверка источника запроса (опционально, но рекомендуется)
  • Протестирована отправка задачи с параметром pingback
  • Настроено логирование для отладки
  • Реализована асинхронная обработка результата (если требуется)
  • Проверено ограничение для GET-запросов с несколькими параметрами в URL

Заключение

Pingback — это надёжный способ получать результаты решения капч автоматически, без нагрузки на аккаунт и риска превышения лимитов опросов. Механизм прост в настройке: достаточно зарегистрировать адрес, добавить параметр pingback в запрос и реализовать обработчик POST-запросов.

Для задач мониторинга времени решения (как в исходном запросе) pingback позволяет точно замерять интервалы и оперативно реагировать на задержки. Комбинируйте pingback с резервным опросом для максимальной надёжности.

Если возникнут вопросы по интеграции — обращайтесь в поддержку 2Captcha, команда поможет настроить pingback под ваш сценарий.