不正対策 Data API

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

ベース URL

https://verify.captcha.la

認証

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

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

WARNING

X-App-Secret は サーバーサイド専用 です。ブラウザ・モバイルアプリ・公開リポジトリに決して露出させないでください。ページ SDK が使うのは公開用の appKey のみです。

エンドポイント

判定を取得する

単一アクセスの判定を取得します（例：特定のアクセスを突き合わせる場合）。識別子はちょうど 1 つだけ渡してください：verdict_id（ページが受け取った判定のもの）または cid （クリックトークン経由のトラフィックの場合のクリック ID）。

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 には Verdict リファレンスで説明する判定フィールドが入ります。

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 が返ることがあります。アクセスをリアルタイムで確認するには、代わりに判定トークンを検証するを使ってください。

判定トークンを検証する

ページが Web SDK から受け取った verdict_token を検証します。サーバー側でコンテンツをゲートする際に使います（サーバーサイド検証を参照）。検証は即座に応答され、保存済みデータには依存しません。

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`	yes	判定に含まれる `verdict_token`。
`ip`	no	あなたのサーバーから見た訪問者の IP アドレス。指定すると、トークンはアクセスと同じネットワークから来ている必要があります。推奨。
`consume`	no	`true` = トークンは 1 回しか使えません。2 回目の検証は `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`	トークンが本物で、あなたのアプリに属し、期限切れでなく、`ip`（指定時）と一致し、`consume` 指定時は未使用である場合に `true`。`valid` はトークンが本物であることだけを示し、訪問者が人間であることは示しません。必ず `verdict` も確認してください。
`error`	`null`、またはトークンが無効な理由：`malformed`、`bad_signature`、`expired`、`ip_mismatch`、`already_used`、`unavailable`（1 回限りのチェックを完了できなかった。再試行してください）。
`expired` / `expires_at`	期限切れ状態と有効期限（Unix 秒）。
`ip_match`	`ip` を指定した場合は `true` / `false`、それ以外は `null`。
`verdict`	署名された判定：`is_bot`、`level`、`action`、`score`、`degraded`、`reasons`、`issued_at`。トークンを読み取れなかった場合は `null`。

典型的なゲートでは、valid が true かつ verdict.is_bot が false のときにコンテンツを提供します。verdict.degraded や、トークンをまったく持たないリクエストをどう扱うかはご自身で決めてください。フェイルオープンにすれば障害時も本物の訪問者は通過できます。フェイルクローズにすれば、有効なトークンなしでは何も通過しません。

トークンはデフォルトで 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 ページあたりの行数、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 フラグも含まれます。

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

有料トラフィックのシナリオでは、単一のアクセスを特定の配信済みクリックに紐づけ、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)}`

Postback(サーバー間通知)

Data API をポーリングする代わりに、判定が発生した時点で自社のエンドポイントへプッシュさせることができます。各アクセスをリアルタイムに記録・突き合わせしたいアフィリエイトトラッカーや広告主のバックエンドに便利です。

有効化する

ダッシュボードでアプリを開き、Fraud Prevention → Postback URL(bot_postback_url)を設定します。設定すると、すべての判定が生成後まもなくその URL へ POST されます。配信は非同期かつ分離されており、エンドポイントが遅い・失敗する場合でも、ページ SDK にすでに返された判定には影響しません。

送信されるタイミング

アプリに対して判定を生成する verify のたびに送信されます。配信はベストエフォートで、自動リトライが数回行われます。at-least-once(少なくとも 1 回) として扱い、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"
}

field	description
`cid`	アクセスの突き合わせキー(click token がなかった場合は `null` になることがあります)
`verdict_id`	判定の ID。ページが受け取った値と同じです
`is_bot`	`1` / `0`
`score`	リスクスコア
`level`	`low` / `medium` / `high` / `critical`
`action`	サーバーが権威を持つアクション(`record_only` / `flag` / `challenge` / `deny`)
`advertiser_app_id`	verify が実行されたアプリの ID
`provider_app_id`	click token で帰属された場合のトラフィックプロバイダー ID、それ以外は `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))

次のステップ

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

不正対策 Data API ​

ベース URL ​

認証 ​

エンドポイント ​

判定を取得する ​

判定トークンを検証する ​

集計統計 ​

エクスポート ​

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

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

トークン形式 ​

ペイロードのフィールド ​

リンクへの付与 ​

例(疑似コード) ​

Postback(サーバー間通知) ​

有効化する ​

送信されるタイミング ​

リクエスト ​

署名を検証する ​

次のステップ ​

不正対策 Data API

ベース URL

認証

エンドポイント

判定を取得する

判定トークンを検証する

集計統計

エクスポート

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

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

トークン形式

ペイロードのフィールド

リンクへの付与

例(疑似コード)

Postback(サーバー間通知)

有効化する

送信されるタイミング

リクエスト

署名を検証する

次のステップ