---
title: 不正対策 — Data API
---

# 不正対策 Data API

Data API は [Web SDK](./web-sdk) のサーバーサイド版です。判定の取得、統計の集計、そして
**レポーティングと突き合わせ** のためのデータエクスポートに使います——あなた自身のシステムが
合意できる数字を取り出すためのものです。

## ベース URL

```
https://apiv1.captcha.la
```

## 認証

すべての Data API リクエストは、不正対策アプリケーションの認証情報をヘッダーとして送信して
認証します。

```
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 クリック単位の突き合わせ
有料トラフィックのシナリオでは、単一のアクセスを特定の配信済みクリックに紐づけ、2 者が
それで精算できます。これはクリックトークンを使うもので、[広告不正](./scenarios/ad-fraud)
ガイドで扱います。
:::

## 次のステップ

- [Verdict リファレンス](./verdict-reference) — これらのエンドポイントが返すフィールド
- [Web SDK](./web-sdk) — ページ上で判定を収集する