Fraud Prevention Data API

Data API — это серверный напарник Web SDK. Используйте его для получения вердиктов, агрегирования статистики и экспорта данных для отчётности и сверки — чтобы получать цифры, на которых сходятся ваши собственные системы.

Базовый URL

https://apiv1.captcha.la

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

Все запросы к Data API аутентифицируются учётными данными вашего приложения Fraud Prevention, передаваемыми в заголовках:

X-App-Key:    YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

WARNING

X-App-Secret предназначен только для серверной стороны. Никогда не раскрывайте его браузерам, мобильным приложениям или публичным репозиториям. Страничный SDK всегда использует только публичный appKey.

Эндпоинты

Получить вердикт

Получите вердикт для одного визита (например, чтобы сверить конкретный визит).

GET /v1/bot/verdict?cid=CID_OF_THE_VISIT
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

Поле data в ответе — это объект BotVerdict:

{
  "code": 0,
  "data": {
    "is_bot": true,
    "score": 87,
    "level": "high",
    "action": "flag",
    "consistency": { "ok": false },
    "degraded": false
  }
}

Агрегированная статистика

Получайте подсчёты по корзинам за период времени — итоги, долю ботов и разбивку по action/level — для дашбордов и отчётов о качестве.

GET /v1/bot/stats?from=2026-06-01&to=2026-06-30
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

{
  "code": 0,
  "data": {
    "from": "2026-06-01",
    "to": "2026-06-30",
    "total": 124500,
    "bots": 18230,
    "bot_rate": 0.146,
    "by_action": { "record_only": 102100, "flag": 19800, "challenge": 2600 },
    "by_level":  { "low": 100300, "medium": 16900, "high": 6200, "critical": 1100 }
  }
}

Экспорт

Экспортируйте построчные вердикты по визитам за период времени для офлайн-сверки.

GET /v1/bot/export?from=2026-06-01&to=2026-06-30&format=csv
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

Каждая строка несёт идентификатор визита, временную метку и поля вердикта (is_bot, score, level, action), так что вы можете связать её обратно со своими логами.

Сверка по каждому клику

Для сценариев платного трафика отдельный визит может быть привязан обратно к конкретному доставленному клику, чтобы две стороны могли по нему рассчитаться. Это использует click-токен и описано в руководстве Рекламный фрод.

Справочник по click token (для поставщиков трафика)

Поставщик трафика подписывает click token на своём собственном сервере и добавляет его в целевой URL, чтобы вердикт по итоговому визиту был отнесён обратно к поставщику. Подпись выполняется офлайн — без вызова API.

Получите учётные данные для подписи

В панели управления откройте ваше приложение → Fraud Prevention → Выпустить ключ подписи. Вы получите:

• bot_kid — идентификатор вашего публичного ключа (попадает в токен как pkid).
• bot_hmac_secret — ваш секрет подписи, показывается один раз. Храните его на стороне сервера.

Формат токена

ct.<base64url(payload)>.<base64url(HMAC_SHA256(body, bot_hmac_secret))>

body — это base64url JSON-полезной нагрузки; подпись вычисляется над этой строкой body.

Поля полезной нагрузки

поле	обязательно	описание
pkid	да	ваш bot_kid; бэкенд использует его для поиска вашего секрета и проверки подписи
cid	да	уникальный идентификатор этого клика; ключ сверки. Генерируйте новое уникальное значение для каждого клика
aud	нет	app_key целевого рекламодателя. Если задано, токен принимается только на странице этого рекламодателя. Опустите, чтобы токен принимался на странице любого рекламодателя
click_ts	нет	unix-секунды момента клика
exp	нет	unix-секунды срока действия; просроченные токены отклоняются

Добавьте его в ссылку

Добавьте токен как query-параметр _ctk к целевому URL рекламодателя:

https://advertiser.example/lp?_ctk=ct.<...>.<...>

SDK рекламодателя считывает _ctk автоматически (настраивается через tokenParam). Значение cid можно использовать только один раз (защита от повторного воспроизведения). См. Модель безопасности.

Пример (псевдокод)

const payload = { pkid, cid, aud: advertiserAppKey, click_ts: now, exp: now + 900 }
const body  = base64url(JSON.stringify(payload))
const sig   = base64url(hmacSha256(body, botHmacSecret))
const token = `ct.${body}.${sig}`
const url   = `${destination}?_ctk=${encodeURIComponent(token)}`

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

• Справочник по вердиктам — поля, возвращаемые этими эндпоинтами
• Web SDK — собирайте вердикты на вашей странице