不正対策 Data API

Data API は 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 のみです。

エンドポイント

判定を取得する

単一アクセスの判定を取得します（例：特定のアクセスを突き合わせる場合）。

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） を含むので、あなた自身のログに結合できます。

クリック単位の突き合わせ

有料トラフィックのシナリオでは、単一のアクセスを特定の配信済みクリックに紐づけ、2 者が それで精算できます。これはクリックトークンを使うもので、広告不正 ガイドで扱います。

click token リファレンス(トラフィックプロバイダー向け)

トラフィックプロバイダーは自社サーバーで click token に署名し、それを遷移先 URL に付与します。これにより、結果として発生したアクセスの判定がそのプロバイダーに帰属します。署名はオフラインで行われ、API 呼び出しは不要です。

署名用クレデンシャルの取得

ダッシュボードでアプリを開き、Fraud Prevention → 署名キーを発行 を選択します。次の値が得られます。

• bot_kid — 公開鍵 ID(トークン内では pkid として格納されます)。
• bot_hmac_secret — 署名用シークレット。一度だけ表示されます。サーバー側で保管してください。

トークン形式

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

body は JSON ペイロードの base64url です。署名はこの body 文字列に対して計算されます。

ペイロードのフィールド

field	required	description
pkid	yes	あなたの bot_kid。バックエンドはこれを使ってシークレットを検索し、署名を検証します
cid	yes	このクリックの一意な ID。精算用のキーです。クリックごとに新しい一意な値を生成してください
aud	no	対象となる広告主の app_key。設定すると、そのトークンはその広告主のページでのみ受け付けられます。省略するとどの広告主のページでも受け付けられます
click_ts	no	クリックが発生した時刻(unix 秒)
exp	no	有効期限(unix 秒)。期限切れのトークンは拒否されます

リンクへの付与

広告主の遷移先 URL に、トークンを _ctk クエリパラメータとして付与します。

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)}`

次のステップ

• Verdict リファレンス — これらのエンドポイントが返すフィールド
• Web SDK — ページ上で判定を収集する