Fraud Prevention Data API

Data API là phần đối ứng phía máy chủ của 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ể).

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:

{
  "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.

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

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.

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.

Đố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.

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.

Ví dụ (mã giả)

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 — các trường mà các điểm cuối này trả về
• Web SDK — thu thập phán quyết trên trang của bạn