---
title: 反詐欺 — 資料 API
---

# 反詐欺資料 API

資料 API 是 [Web SDK](./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`。
:::

## 端點

### 取得單條裁決

取得某一次訪問的裁決(例如用於對帳某次具體訪問)。

```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 逐點擊對帳
對於付費流量場景,一次訪問可以回溯到某次具體投遞的點擊,供雙方就此結算。這用到
點擊 token,見[廣告反作弊](./scenarios/ad-fraud)指南。
:::

## 下一步

- [裁決欄位參考](./verdict-reference) —— 這些端點回傳的欄位
- [Web SDK](./web-sdk) —— 在你的頁面收集裁決