---
title: 反欺诈 — 数据 API
---

# 反欺诈数据 API

数据 API 是 [Web SDK](./web-sdk) 的服务端搭档。用它来拉取裁决、汇总统计、导出数据,
用于**计费、结算与对账**——也就是广告主与流量服务商最终达成一致的那些数字。

## 基础 URL

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

## 鉴权

所有数据 API 请求都用你的反欺诈应用凭据鉴权,以请求头形式发送:

```
X-App-Key:    YOUR_AD_APP_KEY
X-App-Secret: YOUR_AD_APP_SECRET
```

::: warning
`X-App-Secret` **仅限服务端**。绝不要把它暴露给浏览器、移动端或公开仓库。
落地页 SDK 始终只使用公开的 `appKey`。
:::

## 端点

### 获取单条裁决

获取某一次访问的裁决(例如用于对账某个具体点击)。

```bash
GET /v1/bot/verdict?click_token=ct_xxx
X-App-Key: YOUR_AD_APP_KEY
X-App-Secret: YOUR_AD_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_AD_APP_KEY
X-App-Secret: YOUR_AD_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_AD_APP_KEY
X-App-Secret: YOUR_AD_APP_SECRET
```

每一行携带该次访问的 `click_token`(若存在)、时间戳,以及裁决字段
(`is_bot`、`score`、`level`、`action`),你可据此与自己的点击日志关联。

## 点击 token {#click-tokens}

**点击 token(click token)**把流量服务商投递的某次点击,与该次访问最终收到的裁决
关联起来。正是它让广告主与服务商能就一份独立的、逐点击的真人/机器人结论达成一致。

流程:

1. **签发** —— 流量服务商在把访客路由到广告主落地页时,获取一个已签名的点击 token
   (每次点击一个)。
2. **拼接到目标 URL** —— 把签发的 token 作为查询参数拼到落地 URL 上:

   ```
   https://advertiser.example/lp?click_token=ct_xxxxxxxx
   ```

3. **在页面读取** —— [Web SDK](./web-sdk) 会自动从 URL 读取该 token。若你使用不同的
   参数名,设置 `tokenParam`:

   ```js
   BotSignal.init({ appKey: 'YOUR_AD_APP_KEY', tokenParam: 'click_token' });
   ```

4. **对账** —— 之后通过 `GET /v1/bot/verdict?click_token=…` 或在 `export` 中查回该点击,
   并与服务商的投递报表关联。

::: info
该 token 在签发给你时就已签名——你只需把它**透传到落地 URL** 即可。你这边无需做任何
签名或计算。
:::

## 下一步

- [裁决字段参考](./verdict-reference) —— 这些端点返回的字段
- [Web SDK](./web-sdk) —— 在落地页收集裁决