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

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

Базовый URL API

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

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

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

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

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/captcha/verify

cURL Пример

curl -X POST https://api.ru-captcha.ru/v1/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"
  }
}

Интеграция на 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 на /v1/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://api.ru-captcha.ru/v1/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;
}

Интеграция на 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://api.ru-captcha.ru/v1/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://api.ru-captcha.ru/v1/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 к /v1/captcha/verify: заголовок Authorization и JSON с полем token. Успех — HTTP 200 и data.valid == true.

CaptchaVerify.swift

var request = URLRequest(
    url: URL(string: "https://api.ru-captcha.ru/v1/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	Превышен лимит запросов для вашего ключа.