RU-CAPTCHA.RU
Получить ключ

Документация API

Добро пожаловать в документацию RU-CAPTCHA.RU. Наш сервис позволяет легко и быстро добавить надежную текстовую капчу на любой сайт. Интеграция состоит всего из двух шагов: добавления виджета на клиентской стороне и проверки токена на вашем сервере.

Базовый URL API

https://ru-captcha.ru/api/v1

Аутентификация

Для работы с API вам потребуется API_KEY. Вы можете получить его бесплатно в личном кабинете после регистрации.

Ключ передается в заголовке Authorization при запросах с вашего сервера (Backend валидация), а также указывается в data-атрибуте виджета на Frontend.

Интеграция в Aurora OS

Для Aurora OS подключите WebView-страницу SDK. Она принимает API-ключ в query и отдаёт cf_token через JavaScript-мост.

CaptchaPage.qml
import QtQuick 2.15
import Sailfish.Silica 1.0

Page {
    WebView {
        id: captchaWebView
        anchors.fill: parent
        url: "https://ru-captcha.ru/sdk/captcha-webview.html?key=YOUR_API_KEY"
        onLoadFailed: console.log("CAPTCHA load failed")
    }
}

Frontend интеграция

Добавьте скрипт виджета на страницу с вашей формой. Затем разместите контейнер для капчи внутри тега <form>.

Скрипт виджета

Подключите этот скрипт на ваш сайт для работы капчи. URL скрипта зависит от домена, на котором развёрнут сервис.

https://ru-captcha.ru/widget.js
index.html
<!-- Подключите скрипт в head или перед закрывающим body -->
<script src="https://ru-captcha.ru/widget.js"></script>

<form action="/your-endpoint" method="POST">
  <!-- Ваши поля -->
  <input type="email" name="email" />

  <!-- Виджет капчи -->
  <div id="ru-captcha-widget" data-key="YOUR_API_KEY" data-api-base="https://ru-captcha.ru"></div>

  <button type="submit">Отправить</button>
</form>

Перед подключением добавьте домен вашего сайта в личном кабинете (раздел API ключ → Сайты) — укажите адрес без https://, как в браузере, например example.com. Поддомены подключаются автоматически.

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

Backend валидация

Когда форма отправлена на ваш сервер, извлеките значение cf_token и отправьте POST-запрос к нашему API для проверки.

POST/api/v1/public/captcha/verify
cURL Пример
curl -X POST https://ru-captcha.ru/api/v1/public/captcha/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token": "TOKEN_FROM_FRONTEND"}'

Успешный ответ

{
  "success": true,
  "data": {
    "valid": true,
    "score": 0.9,
    "timestamp": "2026-05-17T10:30:00Z"
  }
}

Справочник API

Публичные методы используются виджетом и сайтом клиента. Методы кабинета требуют Bearer-токен пользователя.

Публичные методы

МетодЭндпоинтНазначение
GET/api/v1/public/captcha/allowedПроверяет домен, активность услуги и решение правил отображения (параметры: key, host, query, sf).
GET/api/v1/public/captcha/widget-themeВозвращает настройки вида и правила отображения (параметры: key, host).
GET/api/v1/public/captcha/hostsВозвращает список подключённых доменов или приложений для API-ключа (параметр: key).
POST/api/v1/public/captcha/recordСохраняет результат прохождения. Тело: key, host, event, token, score.
POST/api/v1/public/captcha/verifyСерверная проверка токена. Authorization: Bearer API_KEY, тело: { token }.
POST/api/v1/public/captcha/errorСохраняет ошибку виджета. Тело: key, host, source, code, message.
GET/api/v1/public/statusВозвращает состояние API, базы данных и число подключённых проектов.

Методы личного кабинета

МетодЭндпоинтНазначение
GET/api/v1/user/apikey/sites/:id/statsСтатистика сайта за период. Параметры: date_from, date_to (YYYY-MM-DD).
GET|PUT/api/v1/user/widget/sites/:id/themeЧтение и сохранение настроек виджета конкретного сайта или приложения.
PUT/api/v1/user/security/2faВключение или отключение 2FA. Тело: { enabled: boolean }.
GET/api/v1/user/activityВыгрузка действий пользователя для аудита и интеграций.

Жизненный цикл токена

cf_token одноразовый и действует 10 минут. После успешной проверки помечается использованным; повторная проверка возвращает invalid_token.

Статус сервиса

Публичный статус API проверяет соединение с базой данных и показывает версию API. Используйте его для мониторинга и информирования о сбоях.

GET/api/v1/public/status
{
  "status": "ok",
  "database": "ok",
  "api_version": "v1",
  "active_sites_count": 42
}

Интеграция на Java

Для Android-приложений отобразите виджет капчи во встроенном WebView, затем передайте полученный cf_token на ваш backend и проверьте его через API RU-CAPTCHA.RU.

Виджет во WebView

Загрузите HTML со скриптом widget.js и контейнером ru-captcha-widget. Укажите ваш API-ключ в data-key и домен сервиса в data-api-base.

CaptchaWebView.java
WebView webView = findViewById(R.id.captcha_webview);
webView.getSettings().setJavaScriptEnabled(true);

String html = "<!DOCTYPE html><html><head>"
    + "<script src=\"https://ru-captcha.ru/widget.js\"></script>"
    + "</head><body>"
    + "<div id=\"ru-captcha-widget\" data-key=\"YOUR_API_KEY\" "
    + "data-api-base=\"https://ru-captcha.ru\"></div>"
    + "</body></html>";

webView.loadDataWithBaseURL("https://ru-captcha.ru", html, "text/html", "UTF-8", null);
// После прохождения капчи получите cf_token из DOM (JavascriptInterface)

Проверка токена (сервер)

На backend отправьте POST на /captcha/verify с заголовком Authorization: Bearer API_KEY и телом {"token": "..."}.

CaptchaVerify.java
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;

public boolean verifyCaptcha(String apiKey, String token) throws Exception {
    HttpURLConnection conn = (HttpURLConnection)
        new URL("https://ru-captcha.ru/api/v1/public/captcha/verify").openConnection();
    conn.setRequestMethod("POST");
    conn.setRequestProperty("Authorization", "Bearer " + apiKey);
    conn.setRequestProperty("Content-Type", "application/json; charset=utf-8");
    conn.setDoOutput(true);

    String json = "{\"token\":\"" + token + "\"}";
    conn.getOutputStream().write(json.getBytes(StandardCharsets.UTF_8));

    int status = conn.getResponseCode();
    // Разберите JSON: success == true и data.valid == true
    return status == 200;
}

Web SDK

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

index.js
const { RuCaptcha } = window;

const token = await RuCaptcha.mount("#captcha", {
  key: "YOUR_API_KEY"
});

// Send token with your form to your backend and verify it there
// with POST /api/v1/public/captcha/verify using your secret server-side key.

Правила отображения

Правила задаются в кабинете в настройке виджета. Можно скрыть капчу при совпадении или показывать её только при совпадении по query, IP, региону или HTTP-заголовку.

rules.json
{
  "effect": "hide",
  "query": "preview=1",
  "ip": "203.0.113.10, 198.51.100.0/24",
  "region": "RU",
  "header": "x-bot-group",
  "header_value": "monitoring, automation"
}

Безопасность и аудит

Капча проверяется на стороне сервиса. Персональные данные обрабатываются по размещённым правовым документам.

В личном кабинете можно включить 2FA: после пароля сервис запрашивает 6-значный код из письма.

Регистрация выполняется по корпоративной почте; публичные почтовые домены блокируются.

Действия пользователя доступны для выгрузки через GET /api/v1/user/activity с Bearer-токеном.

Интеграция на Kotlin

В Android на Kotlin используйте WebView для показа виджета и OkHttp (или Ktor) для серверной проверки токена cf_token.

Виджет во WebView

Подключите widget.js через loadDataWithBaseURL — так корректно загрузятся скрипты и словари капчи с домена ru-captcha.ru.

CaptchaWebView.kt
val webView: WebView = findViewById(R.id.captcha_webview)
webView.settings.javaScriptEnabled = true

val html = """
    <!DOCTYPE html>
    <html>
    <head><script src="https://ru-captcha.ru/widget.js"></script></head>
    <body>
      <div id="ru-captcha-widget"
           data-key="YOUR_API_KEY"
           data-api-base="https://ru-captcha.ru"></div>
    </body>
    </html>
""".trimIndent()

webView.loadDataWithBaseURL("https://ru-captcha.ru", html, "text/html", "UTF-8", null)
// После прохождения капчи считайте cf_token через evaluateJavascript

Проверка токена (сервер)

POST-запрос к https://ru-captcha.ru/api/v1/public/captcha/verify с Bearer-токеном и JSON {"token": "TOKEN_FROM_CLIENT"}.

CaptchaVerify.kt
val client = OkHttpClient()

val body = """{"token":"$token"}"""
    .toRequestBody("application/json".toMediaType())

val request = Request.Builder()
    .url("https://ru-captcha.ru/api/v1/public/captcha/verify")
    .post(body)
    .addHeader("Authorization", "Bearer $apiKey")
    .build()

client.newCall(request).execute().use { response ->
    // Проверьте response.isSuccessful и поле data.valid в JSON
}

Интеграция на Swift

В iOS-приложениях покажите капчу в WKWebView, получите cf_token после прохождения и проверьте его на сервере через URLSession.

Виджет в WKWebView

Загрузите HTML с widget.js и div#ru-captcha-widget. Базовый URL loadHTMLString должен указывать на https://ru-captcha.ru.

CaptchaWebView.swift
import WebKit

let webView = WKWebView(frame: .zero)
let html = """
<!DOCTYPE html>
<html>
<head><script src="https://ru-captcha.ru/widget.js"></script></head>
<body>
  <div id="ru-captcha-widget"
       data-key="YOUR_API_KEY"
       data-api-base="https://ru-captcha.ru"></div>
</body>
</html>
"""
webView.loadHTMLString(html, baseURL: URL(string: "https://ru-captcha.ru"))
// После прохождения капчи получите cf_token через evaluateJavaScript

Проверка токена (сервер)

Асинхронный POST к /captcha/verify: заголовок Authorization и JSON с полем token. Успех — HTTP 200 и data.valid == true.

CaptchaVerify.swift
var request = URLRequest(
    url: URL(string: "https://ru-captcha.ru/api/v1/public/captcha/verify")!
)
request.httpMethod = "POST"
request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = try JSONSerialization.data(withJSONObject: ["token": token])

let (data, response) = try await URLSession.shared.data(for: request)
// Проверьте HTTP 200 и поле data.valid в JSON

Коды ошибок

КодОписание
invalid_tokenТокен недействителен, просрочен или уже был использован.
unauthorizedНеверный API_KEY или ключ не передан.
rate_limit_exceededПревышен лимит запросов для вашего ключа.