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-токен и описано в руководстве Рекламный фрод.

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

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