---
title: Fraud Prevention — Data API
---

# Fraud Prevention Data API

Data API là phần đối ứng phía máy chủ của [Web SDK](./web-sdk). Dùng nó để kéo phán
quyết, tổng hợp thống kê, và xuất dữ liệu phục vụ **báo cáo và đối soát** — lấy ra
những con số mà hệ thống của riêng bạn đồng thuận.

## URL cơ sở

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

## Xác thực

Mọi yêu cầu tới Data API đều được xác thực bằng thông tin xác thực ứng dụng Fraud
Prevention của bạn, gửi dưới dạng các header:

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

::: warning
`X-App-Secret` **chỉ dùng ở phía máy chủ**. Đừng bao giờ để lộ nó ra trình duyệt, ứng
dụng di động hay kho lưu trữ công khai. SDK trên trang chỉ bao giờ dùng `appKey` công
khai.
:::

## Các điểm cuối

### Lấy một phán quyết

Lấy phán quyết cho một lượt truy cập đơn lẻ (ví dụ để đối soát một lượt truy cập cụ
thể).

```bash
GET /v1/bot/verdict?cid=CID_OF_THE_VISIT
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
```

Trường `data` trong phản hồi là một đối tượng [`BotVerdict`](./verdict-reference):

```json
{
  "code": 0,
  "data": {
    "is_bot": true,
    "score": 87,
    "level": "high",
    "action": "flag",
    "consistency": { "ok": false },
    "degraded": false
  }
}
```

### Thống kê tổng hợp

Kéo các bộ đếm theo nhóm trong một khoảng thời gian — tổng số, tỷ lệ bot, và phần phân
tách theo `action`/`level` — phục vụ bảng điều khiển và báo cáo chất lượng.

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

### Xuất dữ liệu

Xuất các dòng phán quyết theo từng lượt truy cập trong một khoảng thời gian, phục vụ
đối soát ngoại tuyến.

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

Mỗi dòng mang định danh của lượt truy cập, dấu thời gian, và các trường phán quyết
(`is_bot`, `score`, `level`, `action`), nên bạn có thể nối nó trở lại với nhật ký của
chính mình.

::: tip Đối soát theo từng lượt nhấp
Với các kịch bản lưu lượng trả phí, một lượt truy cập có thể được gắn lại với một lượt
nhấp được gửi đến cụ thể để hai bên có thể thanh toán dựa trên nó. Việc đó dùng một
click token và được trình bày trong hướng dẫn
[Chống gian lận quảng cáo](./scenarios/ad-fraud).
:::

## Tham chiếu click token (dành cho nhà cung cấp lưu lượng)

Một nhà cung cấp lưu lượng ký một **click token** trên máy chủ của riêng họ và thêm nó vào URL đích, để phán quyết cho lượt truy cập phát sinh được quy về cho nhà cung cấp. Việc ký diễn ra ngoại tuyến — không cần gọi API.

### Lấy thông tin xác thực để ký
Trong bảng điều khiển, mở ứng dụng của bạn → Chống gian lận → **Phát hành khóa ký**. Bạn sẽ nhận được:
- `bot_kid` — id khóa công khai của bạn (đưa vào token dưới dạng `pkid`).
- `bot_hmac_secret` — bí mật ký của bạn, chỉ hiển thị **một lần**. Hãy giữ nó ở phía máy chủ.

### Định dạng token
```
ct.<base64url(payload)>.<base64url(HMAC_SHA256(body, bot_hmac_secret))>
```
`body` là base64url của payload JSON; chữ ký được tính trên chuỗi `body` đó.

### Các trường của payload
| trường | bắt buộc | mô tả |
|---|---|---|
| `pkid` | có | `bot_kid` của bạn; backend dùng nó để tra cứu bí mật của bạn và xác minh chữ ký |
| `cid` | có | id duy nhất cho lần nhấp này; khóa đối soát. Hãy tạo một giá trị mới, duy nhất cho mỗi lần nhấp |
| `aud` | không | `app_key` của **nhà quảng cáo mục tiêu**. Khi được đặt, token chỉ được chấp nhận trên trang của nhà quảng cáo đó. Bỏ trống để bất kỳ trang nhà quảng cáo nào cũng chấp nhận |
| `click_ts` | không | thời điểm xảy ra lần nhấp tính bằng giây unix |
| `exp` | không | thời điểm hết hạn tính bằng giây unix; token hết hạn sẽ bị từ chối |

### Thêm vào liên kết
Gắn token làm tham số truy vấn `_ctk` trên URL đích của nhà quảng cáo:
```
https://advertiser.example/lp?_ctk=ct.<...>.<...>
```
SDK của nhà quảng cáo tự động đọc `_ctk` (có thể cấu hình qua `tokenParam`). Mỗi `cid` chỉ có thể được sử dụng một lần (chống phát lại). Xem [Mô hình bảo mật](./scenarios/ad-fraud#mo-hinh-bao-mat).

### Ví dụ (mã giả)
```js
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)}`
```

## Bước tiếp theo

- [Tham chiếu phán quyết](./verdict-reference) — các trường mà các điểm cuối này trả về
- [Web SDK](./web-sdk) — thu thập phán quyết trên trang của bạn