反詐欺資料 API

資料 API 是 Web SDK 的伺服器端搭檔。用它來拉取裁決、彙總統計、匯出資料, 用於報表與對帳——拉取你自己系統據以一致的那些數字。

基礎 URL

https://apiv1.captcha.la

鑑權

所有資料 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),你可據此與自己的日誌關聯。

逐點擊對帳

對於付費流量場景,一次訪問可以回溯到某次具體投遞的點擊,供雙方就此結算。這用到 點擊 token,見廣告反作弊指南。

Click token 參考(給流量方)

流量方在自己的伺服器上簽一枚 click token,加到目標 URL 上,這樣這次造訪的裁決就能歸屬回該流量方。簽名是離線的——不需要呼叫 API。

取得簽名憑證

在 dashboard 裡開啟你的 app → 反詐欺 → 簽發簽名金鑰,會得到:

• bot_kid —— 你的公開 key id(作為 token 裡的 pkid)。
• bot_hmac_secret —— 你的簽名 secret,只顯示一次,務必存在伺服器端。

Token 格式

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

body 是 JSON payload 的 base64url;簽名對該 body 字串計算。

payload 欄位

欄位	必填	說明
pkid	是	你的 bot_kid;後端據此反查你的 secret 驗簽
cid	是	本次點擊的唯一 id,對帳主鍵。每次點擊產生全新唯一值
aud	否	目標廣告主的 app_key。設了之後 token 只在該廣告主頁面被承接;不設則任意廣告主頁面都可承接
click_ts	否	點擊發生的 unix 秒
exp	否	unix 秒過期時間;過期 token 被拒

加到連結上

把 token 作為 _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)}`

下一步

• 裁決欄位參考 —— 這些端點回傳的欄位
• Web SDK —— 在你的頁面收集裁決