Быстрый старт

Это руководство поможет вам интегрировать CAPTCHA CaptchaLa за 5 минут.

Посмотрите работу за 30 секунд

demo-v1.captcha.la — чистый HTML + PHP, лицензия MIT, исходный код доступен на каждой странице.

• popup.html — режим всплывающего окна
• float.html — плавающий виджет
• bind.html — привязка к кнопке
• inline.html — встраивание inline
• server-token.html — Token, выданный сервером (защита от повторов)

1. Создание аккаунта

Зарегистрируйте бесплатный аккаунт в панели управления

Зарегистрироваться сейчас →

2. Создание приложения

Создайте приложение в панели управления, чтобы получить ваш App Key

3. Установка SDK

Выберите предпочтительный метод установки

<!-- CDN loader (recommended): auto-fallback CDN, ~6 KB gzip -->
<script src="https://cdn.captcha-cdn.net/captchala-loader.js"></script>

# or via npm
npm install captchala

4. Инициализация CAPTCHA

Инициализируйте компонент CAPTCHA на вашей странице

<button id="login-btn">Sign in</button>

<script>
loadCaptchala(function () {
  Captchala.init({
    appKey: 'YOUR_APP_KEY',
    product: 'bind',          // popup | float | bind | embed
    action: 'login',
    lang: 'auto',
  })
  .onSuccess(function (res) {
    // res.token starts with pt_ — POST it to your backend
    submitLogin(res.token);
  })
  .onError(function (err) { console.error(err.message); })
  .bindTo('#login-btn');     // popup/bind use bindTo; float/embed use appendTo
});
</script>

5. Серверная проверка

Проверьте Token на вашем сервере

POST https://apiv1.captcha.la/v1/validate
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "pass_token": "<from onSuccess>", "client_ip": "<end-user IP>" }

{
  "code": 0,
  "data": {
    "valid": true,
    "action": "login",
    "challenge_id": "ch_xxx",
    "uid": null,
    "client_ip": "1.2.3.4",
    "risk_score": 12
  }
}

WARNING

Всегда проверяйте data.valid === true и что data.action соответствует ожидаемому сценарию. Pass Token одноразовые; один и тот же pt_xxx нельзя проверить дважды.

Режим Token, выданного сервером (рекомендуется для production)

Для чувствительных действий (вход, регистрация, оплата) мы рекомендуем поток Token, выданного сервером: ваш backend сначала запрашивает короткоживущий server_token, который браузер затем использует для инициализации CAPTCHA. Это предотвращает злоупотребления при утечке app_key.

Когда использовать

• Рекомендуется: регистрация, вход, сброс пароля, оплата, обмен баллов и любые endpoint, которые злоумышленник может атаковать скриптом.
• Опционально: обычные публичные формы, поля поиска и низкоценные взаимодействия, где удобство важнее.

1. Backend выдаёт server_token

Вызовите /v1/server/challenge/issue с вашего сервера, используя заголовки X-App-Key и X-App-Secret. Никогда не передавайте эти заголовки в браузер.

# Server-side only — never call this from a browser
curl -X POST https://apiv1.captcha.la/v1/server/challenge/issue \
  -H "X-App-Key: YOUR_APP_KEY" \
  -H "X-App-Secret: YOUR_APP_SECRET" \
  -d "action=login&ttl=300&max_uses=1&bind_ip=1.2.3.4"

# → { "code": 0, "data": { "server_token": "sct_...", "expires_in": 300 } }

2. Frontend отрисовывает CaptchaLa с server_token

Передайте Token в ваш компонент CaptchaLa. SDK перешлёт его при инициализации запроса.

// Browser fetches the token from YOUR backend, not from CaptchaLa directly
const { serverToken } = await fetch('/api/captcha/issue').then(r => r.json());

Captchala.init({
  appKey: 'YOUR_APP_KEY',
  serverToken,             // single-use, short-lived
  product: 'popup',
  action: 'login',
})
.appendTo('#captcha-container')
.onSuccess(res => submitForm(res.token));

Замечания по безопасности

• Никогда не размещайте app_secret в коде frontend, мобильных приложениях или публичных репозиториях. Он должен оставаться только на сервере.
• Включите "Require server-issued challenge token" в панели управления, чтобы отклонять любые попытки без server_token.
• Держите ttl коротким (по умолчанию 300 с, максимум 900 с) и предпочитайте max_uses=1, чтобы снизить влияние утечки Token.

Дальнейшие шаги

• Web SDK
• Справочник API