Captcha API (Google reCAPTCHA v3): документация и руководство по интеграции для разработчиков

Пожалуйста, ознакомьтесь с условиями использования материалов, размещённых на этом сайте.

Это руководство для разработчиков описывает принцип работы с API Google reCAPTCHA v3: ваш фронтенд получает токен reCAPTCHA, а бэкенд проверяет его через верификационный endpoint Google. В этой статье под «Captcha API» понимается API провайдера CAPTCHA, которое используется для проверки токена CAPTCHA; это не то же самое, что «captcha solver API» — отдельный класс сервисов, предназначенные для автоматического решения капч. Всё ниже основано на официальной документации Google reCAPTCHA (плюс одно упоминание о "solver API").

Как работает reCAPTCHA

Когда reCAPTCHA развёрнута в вашей среде, она взаимодействует с вашим бэкендом и клиентом (веб‑страницами или мобильными приложениями).

Когда конечный пользователь посещает веб‑страницу или использует мобильное приложение, последовательно происходят следующие события:

1. Клиент загружает веб‑страницу с бэкенда или запускает мобильное приложение.
2. Веб‑страница или мобильное приложение инициализирует JavaScript API reCAPTCHA или мобильный SDK, которые начинают собирать сигналы.
3. Когда пользователь инициирует действие, защищённое reCAPTCHA (например, вход в систему), reCAPTCHA JavaScript API или мобильный SDK на клиенте запрашивает вердикт у reCAPTCHA.
4. reCAPTCHA возвращает зашифрованный токен reCAPTCHA клиенту для последующего использования.
5. Клиент отправляет зашифрованный токен reCAPTCHA на бэкенд для оценки.
6. Бэкенд отправляет токен на REST‑endpoint siteverify.
7. reCAPTCHA возвращает вердикт на бэкенд на основе оценки риска для этого запроса. Вердикт включает в себя оценки от 0.0 до 1.0 и коды причин.
8. В зависимости от вердикта вы (как разработчик) определяете, какие последующие шаги предпринять для данного пользовательского запроса или действия.

Следующая диаграмма показывает графическое представление рабочего процесса reCAPTCHA:

См. также диаграммы процессов внедрения: https://docs.cloud.google.com/recaptcha/docs/implementation-workflow

Ключи Captcha API (site key + secret)

Для reCAPTCHA v3 вы регистрируете ключи в Google reCAPTCHA Admin Console и получаете ключ сайта (публичный) и секретный ключ (используемый вашим бэкендом). Относитесь к секретному ключу как к серверным учётным данным: он передаётся в параметре secret при вызове верификационного endpoint, поэтому он никогда не должен попадать в клиентский код.

Интеграция на клиенте (JavaScript)

reCAPTCHA v3 работает без прерывания действий пользователей и возвращает оценку для каждого запроса, где 1.0 — это, скорее всего, живой человек, а 0.0 — скорее бот. Вы вызываете reCAPTCHA для конкретных действий (например, login или signup), и на бэкенде вы должны проверить, что возвращённое поле action соответствует ожидаемому. Google рекомендует немедленно отправлять токен на ваш бэкенд вместе с запросом, который вы хотите защитить.

Вариант A: Привязка к кнопке (адаптировано для JSON‑бэкенда)

Подключите JavaScript API и добавьте атрибуты reCAPTCHA к кнопке. Вызов callback получит токен. 

Примечание: чтобы работать с приведёнными ниже JSON‑бэкенд‑примерами, этот скрипт перехватывает отправку формы и отправляет JSON‑запрос вместо стандартного POST‑запроса формы.

<script src="https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY"></script>
<script>
  function onSubmit(token) {
    // Предотвращаем отправку формы по умолчанию и отправляем JSON на бэкэнд
    const form = document.getElementById("demo-form");
    const formData = new FormData(form);
    const data = Object.fromEntries(formData.entries());
    data.recaptchaToken = token; // Добавляем токен в JSON payload

    fetch("/api/submit", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(data)
    }).then(response => {
      if (response.ok) console.log("Success");
    });
  }
</script>

<form id="demo-form">
  <!-- Поля формы -->
  <button 
    class="g-recaptcha" 
    data-sitekey="YOUR_SITE_KEY" 
    data-callback="onSubmit" 
    data-action="submit" 
    type="button">
    Submit
  </button>
</form>

Вариант B: Программный вызов (рекомендуется для API/AJAX)

Подключите api.js с параметром ?render=YOUR_SITE_KEY, затем вызывайте grecaptcha.execute() для каждого действия, которое вы хотите защитить.

<script src="https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY"></script>
<script>
  async function getTokenAndCallBackend() {
    const token = await new Promise((resolve) => {
      grecaptcha.ready(() => {
        grecaptcha.execute("YOUR_SITE_KEY", { action: "login" }).then(resolve);
      });
    });

    // Отправляем токен методом POST на бэкэнд, который вызовет siteverify
    await fetch("/api/login", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ recaptchaToken: token })
    });
  }
</script>

Проверка Captcha API (REST: siteverify)

Обращение к REST‑endpoint Google для проверки (https://www.google.com/recaptcha/api/siteverify) выполняется методом POST. Отправьте поля secret (обязательный), response (обязательный токен с клиента) и при необходимости remoteip (IP‑адрес пользователя). Каждый токен действителен две минуты и может быть проверен только один раз.

Пример REST‑запроса (curl)

curl -X POST \
  -d "secret=YOUR_SECRET_KEY" \
  -d "response=USER_TOKEN" \
  -d "remoteip=USER_IP_OPTIONAL" \
  https://www.google.com/recaptcha/api/siteverify

Поля REST‑ответа (reCAPTCHA v3)

Успешный ответ — это JSON‑объект, который включает поле success, а также специфичные для reCAPTCHA v3 поля, такие как score и action, и может включать массив error-codes. Также вы увидите challenge_ts (timestamp в формате ISO) и hostname (домен, на котором был решён токен).

Пример структуры (набор полей зависит от сценария):

{
  "success": true,
  "score": 0.7,
  "action": "login",
  "challenge_ts": "2026-02-18T10:00:00Z",
  "hostname": "example.com"
}

Примеры SDK на бэкенде

Все эти примеры делают одно и то же: ваш бэкенд получает токен, вызывает REST‑endpoint siteverify с вашим секретом, затем анализирует JSON‑ответ. Для reCAPTCHA v3 Google прямо указывает, что вы должны валидировать поле action и использовать значение score для принятия решения о дальнейших действиях по запросу.

Node.js (серверная проверка)

// Node.js 18+
import express from "express";

const app = express();

app.use(express.json()); // Анализ запросов application/json

app.post("/api/login", async (req, res) => {
    const token = req.body.recaptchaToken;

    // Подготовка параметров для Google (x-www-form-urlencoded)

    const params = new URLSearchParams();

    params.set("secret", process.env.RECAPTCHA_SECRET);

    params.set("response", token);

    const verifyResp = await fetch("https://www.google.com/recaptcha/api/siteverify", {
        method: "POST",
        headers: {
            "content-type": "application/x-www-form-urlencoded"
        },
        body: params

    });

    const data = await verifyResp.json();

    if (!data.success) {
        return res.status(403).json({
            error: "recaptcha_failed",
            details: data["error-codes"]
        });

    }

    if (data.action !== "login") {
        return res.status(403).json({
            error: "recaptcha_action_mismatch"
        });

    }

    // Выберите свои собственные пороговые значения на основе шаблонов трафика
    if (data.score < 0.5) {
        return res.status(403).json({
            error: "recaptcha_low_score",
            score: data.score
        });

    }

    return res.json({
        ok: true
    });

});

app.listen(3000);

Python (серверная проверка)

import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.post("/api/signup")
def signup():
    token = request.json.get("recaptchaToken")

    r = requests.post(
        "https://www.google.com/recaptcha/api/siteverify",
        data={
            "secret": os.environ["RECAPTCHA_SECRET"],
            "response": token,
            # "remoteip": request.remote_addr,  # optional
        },
        timeout=5,
    )
    data = r.json()

    if not data.get("success", False):
        return jsonify({"error": "recaptcha_failed"}), 403
    if data.get("action") != "signup":
        return jsonify({"error": "recaptcha_action_mismatch"}), 403
    if data.get("score", 0) < 0.5:
        return jsonify({"error": "recaptcha_low_score"}), 403
    return jsonify({"ok": True})

Браузерный JavaScript (создание токена)

Это клиентская часть процесса взаимодействия с Google reCAPTCHA API, при котором происходит передача токена на ваш бэкенд для проверки.

grecaptcha.ready(() => {
  grecaptcha.execute("YOUR_SITE_KEY", { action: "submit" }).then(async (token) => {
    await fetch("/api/contact", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ recaptchaToken: token })
    });
  });
});

Модель аутентификации

POST-параметр secret — это общий ключ между вашим сайтом и reCAPTCHA, который аутентифицирует ваш "сервер‑сервер" запрос к siteverify. Поскольку токен быстро истекает и может быть использован один раз, вам следует проверять его немедленно и избегать повторных проверок с тем же токеном. Если нужен новый токен, Google рекомендует повторно запустить клиентскую часть процесса взаимодействия с reCAPTCHA.

Обработка ошибок и коды ошибок

На уровне API ответ метода проверки siteverify включает поле success и может содержать массив error-codes, описывающий, что пошло не так. Ниже приведены коды ошибок для siteverify:

• missing-input-secret: параметр secret отсутствует
• invalid-input-secret: параметр secret недействителен или имеет неверный формат
• missing-input-response: параметр response (токен) отсутствует
• invalid-input-response: токен недействителен или имеет неверный формат
• bad-request: запрос недействителен или имеет неверный формат
• timeout-or-duplicate: токен больше не действителен (слишком старый) или уже был использован

Обрабатывайте ошибки вида missing/invalid-* как ошибки конфигурации или запроса, а timeout-or-duplicate рассматривайте как ожидаемое рабочее состояние, когда токены истекают или повторно используются.

Интерпретация оценки (0.0–1.0)

В отличие от reCAPTCHA v2, v3 не показывает челлендж (например, «выберите автобусы»). Вместо этого она возвращает оценку.

• 1.0: очень вероятно, что это человек.
• 0.0: очень вероятно, что это бот.

Google не блокирует запросы автоматически; интерпретировать оценку и принимать решение должен ваш бэкенд. Часто в качестве стартового порога используют 0.5.

Рекомендуемые действия в зависимости от оценки

1. Высокая оценка (> 0.5): предоставьте доступ немедленно.
2. Низкая оценка (< 0.5): не просто блокируйте, а добавьте дополнительные испытания:
   • требуйте двухфакторную аутентификацию (2FA);
   • отправляйте письмо с подтверждением;
   • показывайте видимый челлендж (например, reCAPTCHA v2) как запасной вариант;
   • отправляйте транзакцию на ручную проверку.

Чек‑лист по внедрению

• Зарегистрируйте ключи reCAPTCHA v3 и добавьте site key в вашу фронтенд‑интеграцию.
• Генерируйте токены для явных имён action и немедленно отправляйте токен на ваш бэкенд.
• Проверяйте токен через POST https://www.google.com/recaptcha/api/siteverify, используя ваш secret key.
• Соблюдайте ограничения по токенам: проверяйте их в течение двух минут и не используйте один и тот же токен более одного раза.
• Для v3 проверяйте поле action и используйте score для выбора поведения при ответе.
• Обрабатывайте массив error-codes в соответствии с типом ошибки (особенно timeout-or-duplicate).

Captcha Solver API (автоматизация и тестирование)

Примечание: этот раздел раскрывает отличие «solver API», упомянутое во введении.

В то время как под «Captcha API» подразумеваются сервисы защиты сайтов от нежелательного трафика, сервисы "captcha solver API" (такие как CapMonster Cloud) используются разработчиками для автоматизации тестирования или софтом, которому нужно обходить капчи. Эти сервисы часто используют ИИ для генерации валидных токенов, имитирующих реальных пользователей.

Если вы разрабатываете автоматизированный набор тестов или скрапер и вам нужно обойти reCAPTCHA v3, вам необходимо использовать "solver API", чтобы получить токен и затем отправить его на целевой сайт так же, как это сделал бы браузер.

Подробные сведения и примеры интеграции CapMonster Cloud смотрите в официальной документации API.

Также вы можете ознакомиться с подробными инструкциями по решению, интеграции и тестированию капч на нашем сайте:

• reCAPTCHA v2
• reCAPTCHA v3
• reCAPTCHA Enterprise
• и другие типы капч, поддерживаемые нашим сервисом.

Полезные ссылки

• https://docs.cloud.google.com/recaptcha/docs
• https://docs.cloud.google.com/recaptcha/docs/overview
• https://developers.google.com/recaptcha/docs/v3
• https://developers.google.com/recaptcha/docs/verify

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