Обработка CAPTCHA в собственных автоматизированных workflow

Безопасный scope: Это руководство применимо только к собственным или явно авторизованным QA-, staging- и production-средам. Описаны сценарии диагностики, тестирования и наблюдаемости вашей собственной CAPTCHA-интеграции — не для сторонних сайтов и не для несанкционированных workflow.

Любой автоматизированный сценарий рано или поздно встречает CAPTCHA. В собственных или явно авторизованных workflow корректная обработка — это: правильный таймаут, идемпотентные ретраи, логи и ясный fallback.

Базовая схема

1. Определить тип CAPTCHA и sitekey на собственной странице.
2. Запросить токен у CaptchaAI.
3. Передать токен на собственный backend.
4. Дождаться валидации.
5. Записать pass/fail в журнал прогона.

Минимальная реализация

import os, requests, time

API_KEY = os.environ['CAPTCHAAI_KEY']

def solve(sitekey: str, pageurl: str) -> str:
    r = requests.post('https://ocr.captchaai.com/in.php', data={
        'key': API_KEY, 'method': 'userrecaptcha',
        'googlekey': sitekey, 'pageurl': pageurl, 'json': 1,
    }).json()
    tid = r['request']
    for _ in range(40):
        time.sleep(3)
        res = requests.get('https://ocr.captchaai.com/res.php', params={
            'key': API_KEY, 'action': 'get', 'id': tid, 'json': 1,
        }).json()
        if res['status'] == 1:
            return res['request']
    raise TimeoutError(tid)

Идемпотентность и ретраи

Используйте идемпотентный ключ для каждой логической операции. Это позволяет безопасно ретраить операцию без запроса нового токена для каждой попытки.

Логи и наблюдаемость

Структурированные логи помогают сравнивать поведение CAPTCHA между релизами и быстро находить регрессии в собственных формах:

import json, time, logging

log = logging.getLogger('captcha-qa')

def record(event: str, **fields) -> None:
    payload = {'ts': time.time(), 'event': event, **fields}
    log.info(json.dumps(payload, ensure_ascii=False))

Минимальный набор полей для каждой попытки: slug, captcha_type, task_id, wait_seconds, verify_status, env. Этого достаточно, чтобы построить дашборд медианы / P90 / P99 по типу CAPTCHA и по среде.

Troubleshooting

QA-чек-лист

• Запрос отправляется только на собственные или авторизованные endpoints.
• Тестовые учётные записи, события и платежи помечены как фиктивные.
• CAPTCHA-токен проверяется на собственном backend, а не доверяется клиенту.
• Логи содержат task_id, тип CAPTCHA, время ожидания и pass/fail.
• Скрипт возвращает корректный exit code, чтобы CI мог принять решение.

FAQ

Можно ли использовать этот подход на сторонних сайтах?

Нет. Описанные сценарии применимы только к собственным или явно авторизованным средам. Для чужих ресурсов запрашивайте письменное разрешение владельца.

Что делать, если CaptchaAI вернул ошибку?

Логируйте task_id, тип CAPTCHA и текст ошибки, повторите запрос с экспоненциальной задержкой и фиксируйте долю ошибок в дашборде. Постоянный рост ошибок — повод проверить sitekey и страницу.

Как сравнивать результаты между релизами?

Сохраняйте логи в одном формате и стройте отчёт по медиане, P90 и P99 на одинаковом наборе сценариев. Сравнивайте только сопоставимые выборки в собственной среде.

Безопасные связанные руководства

• Быстрый старт CaptchaAI
• QA-тестирование CAPTCHA в авторизованных средах
• Тестирование CAPTCHA API на собственных формах
• Отладка: браузерный тест падает, API проходит
• reCAPTCHA v2 через API
• Cloudflare Turnstile через API
• GeeTest v3 через API

Готовы обрабатывать CAPTCHA в собственных workflow? Подключите CaptchaAI.