---
title: Fraud Prevention — Data API
---

# Fraud Prevention Data API

Data API — это серверный напарник [Web SDK](./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`.
:::

## Эндпоинты

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

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

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

Поле `data` в ответе — это объект [`BotVerdict`](./verdict-reference):

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

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

Получайте подсчёты по корзинам за период времени — итоги, долю ботов и разбивку по
`action`/`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
{
  "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 }
  }
}
```

### Экспорт

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

```bash
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`), так что вы можете связать её обратно со своими
логами.

::: tip Сверка по каждому клику
Для сценариев платного трафика отдельный визит может быть привязан обратно к
конкретному доставленному клику, чтобы две стороны могли по нему рассчитаться. Это
использует click-токен и описано в руководстве [Рекламный фрод](./scenarios/ad-fraud).
:::

## Справочник по 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` можно использовать только один раз (защита от повторного воспроизведения). См. [Модель безопасности](./scenarios/ad-fraud#модель-безопасности).

### Пример (псевдокод)
```js
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)}`
```

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

- [Справочник по вердиктам](./verdict-reference) — поля, возвращаемые этими эндпоинтами
- [Web SDK](./web-sdk) — собирайте вердикты на вашей странице