Fraud Prevention Data API

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

Базовый URL

https://verify.captcha.la

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

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

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

WARNING

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

Эндпоинты

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

Получите вердикт для одного визита (например, чтобы сверить конкретный визит). Передайте ровно один идентификатор: verdict_id (из вердикта, который получила страница) или cid (click id, для трафика с click-токеном).

bash

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

found показывает, найден ли вердикт. Когда он равен true, data содержит поля вердикта, описанные в Справочнике по вердиктам:

json

{
  "found": true,
  "data": {
    "cid": null,
    "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
    "is_bot": true,
    "score": 87,
    "level": "high",
    "action": "flag",
    "reasons": ["automation", "network"],
    "consistency": { "ok": false },
    "degraded": false,
    "created_at": "2026-06-25 00:00:00"
  }
}

Если ничего не найдено, ответ — {"found": false}. Запрос без verdict_id и без cid отклоняется с HTTP 400.

TIP

Вердикты сохраняются через несколько секунд после их создания, поэтому запрос сразу после визита может вернуть found: false. Чтобы проверить визит в реальном времени, используйте Проверку токена вердикта.

Проверить токен вердикта

Проверьте verdict_token, который ваша страница получила от Web SDK. Используйте это, чтобы закрывать доступ к контенту на своём сервере (см. Серверную проверку). Ответ приходит сразу и не зависит от сохранённых данных.

bash

POST /v1/bot/verdict/verify
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "token": "vt1.eyJ2Ijoi...", "ip": "203.0.113.7", "consume": false }

Параметр	Обязателен	Описание
`token`	да	`verdict_token` из вердикта.
`ip`	нет	IP-адрес посетителя, каким его видит ваш сервер. Если передан, токен должен прийти из той же сети, что и визит. Рекомендуется.
`consume`	нет	`true` = токен можно использовать только один раз; повторная проверка вернёт `already_used`. По умолчанию `false`: токен можно проверять повторно, пока не истечёт срок.

json

{
  "valid": true,
  "error": null,
  "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
  "expired": false,
  "expires_at": 1767225600,
  "ip_match": true,
  "verdict": {
    "is_bot": false,
    "level": "low",
    "action": "record_only",
    "score": 12,
    "degraded": false,
    "reasons": [],
    "issued_at": 1767225000
  }
}

Поле	Описание
`valid`	`true`, когда токен подлинный, принадлежит вашему приложению, не истёк, соответствует `ip` (если передан) и, при `consume`, ещё не использовался. `valid` говорит лишь о подлинности токена. Он не означает, что посетитель — человек, поэтому проверяйте и `verdict`.
`error`	`null` или причина недействительности токена: `malformed`, `bad_signature`, `expired`, `ip_mismatch`, `already_used`, `unavailable` (одноразовую проверку не удалось выполнить; повторите).
`expired` / `expires_at`	Истёк ли токен и время истечения (Unix-секунды).
`ip_match`	`true` / `false`, если передан `ip`, иначе `null`.
`verdict`	Подписанный вердикт: `is_bot`, `level`, `action`, `score`, `degraded`, `reasons`, `issued_at`. `null`, если токен не удалось прочитать.

Типичный шлюз отдаёт контент, когда valid равно true, а verdict.is_bot — false. Как обрабатывать verdict.degraded и запросы совсем без токена, решаете вы. Если вы пропускаете при сбое (fail open), реальные посетители проходят и во время сбоя. Если блокируете (fail closed), без действительного токена не проходит никто.

По умолчанию токены истекают через 10 минут. Чтобы получить новый, снова запустите SDK (например, при следующей загрузке страницы).

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

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

bash

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

json

{
  "from": "2026-06-01",
  "to": "2026-06-30",
  "cleaned": true,
  "total": 124500,
  "bots": 18230,
  "by_level": { "low": 100300, "medium": 16900, "high": 6200, "critical": 1100 },
  "by_day": [
    { "date": "2026-06-01", "total": 4100, "bots": 590 }
  ]
}

По умолчанию from / to — последние 7 дней.

Экспорт

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

bash

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

Параметр	Описание
`from` / `to`	Диапазон дат (`YYYY-MM-DD`). Необязательно.
`limit`	Строк на страницу, 1–5000 (по умолчанию 1000).
`cursor`	Передайте `next_cursor` предыдущей страницы, чтобы получить следующую.

json

{
  "rows": [
    {
      "id": 1042, "cid": null, "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
      "is_bot": false, "score": 12, "level": "low", "action": "record_only",
      "reasons": [], "consistency": { "ok": true }, "degraded": false,
      "created_at": "2026-06-25 00:00:00", "rescored": false
    }
  ],
  "next_cursor": 1042
}

Каждая строка несёт идентификаторы визита, временную метку и поля вердикта, так что вы можете связать её со своими логами. На последней странице next_cursor равен null.

Очищенные показатели

По умолчанию статистика и экспорт формируются на очищенной основе: трафик, который позже признаётся недействительным, постоянно переоценивается и исключается из показателей. Это происходит асинхронно, поэтому значения за самые недавние периоды ещё могут немного уточняться. Передайте ?raw=1, чтобы увидеть неочищенные показатели; в export каждая строка также содержит флаг rescored.

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

Для сценариев платного трафика отдельный визит может быть привязан обратно к конкретному доставленному клику, чтобы две стороны могли по нему рассчитаться. Это использует 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)}`

Postback (server-to-server)

Вместо опроса Data API вы можете получать вердикты push-уведомлениями на свой эндпоинт по мере их появления — это удобно для партнёрских трекеров и бэкендов рекламодателей, которым нужно фиксировать или сверять каждый визит в реальном времени.

Включение

В панели управления откройте ваше приложение → Fraud Prevention → задайте Postback URL (bot_postback_url). После этого каждый вердикт отправляется POST-запросом на этот URL вскоре после его формирования. Доставка асинхронная и изолированная — медленный или неработающий эндпоинт никогда не влияет на вердикт, уже возвращённый SDK на странице.

Когда срабатывает

При каждой проверке, которая формирует вердикт для приложения. Доставка выполняется по принципу best-effort с несколькими автоматическими повторами; рассматривайте её как at-least-once и устраняйте дубликаты по verdict_id.

Запрос

POST <your bot_postback_url>
Content-Type: application/json
X-Bot-Signature: t=<unix_ts>,v=<hex>

Тело (JSON):

json

{
  "cid": "CID_OF_THE_VISIT",
  "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
  "is_bot": 1,
  "score": 87,
  "level": "high",
  "action": "flag",
  "advertiser_app_id": 12,
  "provider_app_id": 34,
  "created_at": "2026-06-25 00:00:00"
}

поле	описание
`cid`	ключ сверки для визита (может быть `null`, если click token отсутствовал)
`verdict_id`	идентификатор вердикта; то же значение, что получила страница
`is_bot`	`1` / `0`
`score`	оценка риска
`level`	`low` / `medium` / `high` / `critical`
`action`	действие, определяемое сервером (`record_only` / `flag` / `challenge` / `deny`)
`advertiser_app_id`	идентификатор приложения, для которого выполнялась проверка
`provider_app_id`	идентификатор поставщика трафика при атрибуции через click token, иначе `null`
`created_at`	время вердикта (UTC)

Проверка подписи

Заголовок X-Bot-Signature позволяет убедиться, что запрос действительно пришёл от нас. Он имеет вид t=<unix_ts>,v=<hex>, где:

hex = HMAC_SHA256( "<unix_ts>." + raw_request_body , bot_hmac_secret )

bot_hmac_secret — тот же секрет подписи, который вы выпускаете в Fraud Prevention → Выпустить ключ подписи. Для проверки заново вычислите HMAC над сырым полученным телом (не сериализуйте JSON повторно) и сравните значения за постоянное время. При желании отклоняйте запросы, у которых t слишком далеко от ваших часов, чтобы ограничить повторное воспроизведение.

// Express example
const [tsPart, vPart] = req.get('X-Bot-Signature').split(',')
const ts = tsPart.slice(2)             // "t=" prefix
const v  = vPart.slice(2)              // "v=" prefix
const expected = crypto
  .createHmac('sha256', BOT_HMAC_SECRET)
  .update(ts + '.' + rawBody)          // rawBody is the unparsed request body
  .digest('hex')
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v))

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

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

Fraud Prevention Data API ​

Базовый URL ​

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

Эндпоинты ​

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

Проверить токен вердикта ​

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

Экспорт ​

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

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

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

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

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

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

Postback (server-to-server) ​

Включение ​

Когда срабатывает ​

Запрос ​

Проверка подписи ​

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

Fraud Prevention Data API

Базовый URL

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

Эндпоинты

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

Проверить токен вердикта

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

Экспорт

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

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

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

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

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

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

Postback (server-to-server)

Включение

Когда срабатывает

Запрос

Проверка подписи

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