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.

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