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://verify.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ể). Truyền đúng một định danh: verdict_id (lấy từ phán quyết mà trang nhận được) hoặc cid (click id, cho lưu lượng có click token).

bash

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

found cho biết có tìm thấy phán quyết hay không. Khi nó là true, data chứa các trường phán quyết được mô tả trong Tham chiếu phán quyết:

json

{
  "found": true,
  "data": {
    "cid": null,
    "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
    "is_bot": true,
    "score": 87,
    "level": "high",
    "action": "flag",
    "reasons": ["automation", "network"],
    "consistency": { "ok": false },
    "degraded": false,
    "created_at": "2026-06-25 00:00:00"
  }
}

Khi không có kết quả khớp, phản hồi là {"found": false}. Request không có cả verdict_id lẫn cid sẽ bị từ chối với HTTP 400.

TIP

Phán quyết được lưu vài giây sau khi được tạo ra, nên tra cứu ngay sau lượt truy cập có thể trả về found: false. Để kiểm tra một lượt truy cập theo thời gian thực, hãy dùng Xác minh verdict token.

Xác minh verdict token

Kiểm tra một verdict_token mà trang của bạn nhận được từ Web SDK. Dùng nó để chặn nội dung trên máy chủ của bạn (xem Xác minh phía máy chủ). Kết quả được trả về ngay và không phụ thuộc vào dữ liệu đã lưu.

bash

POST /v1/bot/verdict/verify
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "token": "vt1.eyJ2Ijoi...", "ip": "203.0.113.7", "consume": false }

Tham số	Bắt buộc	Mô tả
`token`	có	`verdict_token` lấy từ phán quyết.
`ip`	không	Địa chỉ IP của khách truy cập mà máy chủ của bạn thấy. Khi được truyền, token phải đến từ cùng mạng với lượt truy cập. Nên truyền.
`consume`	không	`true` = token chỉ dùng được một lần; lần kiểm tra thứ hai trả về `already_used`. Mặc định `false`: token có thể được kiểm tra lại cho đến khi hết hạn.

json

{
  "valid": true,
  "error": null,
  "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
  "expired": false,
  "expires_at": 1767225600,
  "ip_match": true,
  "verdict": {
    "is_bot": false,
    "level": "low",
    "action": "record_only",
    "score": 12,
    "degraded": false,
    "reasons": [],
    "issued_at": 1767225000
  }
}

Trường	Mô tả
`valid`	`true` khi token là thật, thuộc về ứng dụng của bạn, chưa hết hạn, khớp `ip` (nếu có truyền) và, với `consume`, chưa được dùng. `valid` chỉ cho biết token là thật. Nó không cho biết khách truy cập là người, nên hãy kiểm tra cả `verdict`.
`error`	`null`, hoặc lý do token không hợp lệ: `malformed`, `bad_signature`, `expired`, `ip_mismatch`, `already_used`, `unavailable` (không thể hoàn tất lần kiểm tra dùng một lần; hãy thử lại).
`expired` / `expires_at`	Trạng thái hết hạn và thời điểm hết hạn (giây Unix).
`ip_match`	`true` / `false` khi có truyền `ip`, nếu không thì `null`.
`verdict`	Phán quyết đã ký: `is_bot`, `level`, `action`, `score`, `degraded`, `reasons`, `issued_at`. `null` khi không đọc được token.

Một cổng chặn điển hình phục vụ nội dung khi valid là true và verdict.is_bot là false. Bạn tự quyết cách xử lý verdict.degraded và các request hoàn toàn không có token. Nếu chọn cho qua (fail open), khách truy cập thật vẫn vào được khi có sự cố. Nếu chọn chặn (fail closed), không có gì lọt qua nếu thiếu token hợp lệ.

Token mặc định hết hạn sau 10 phút. Chạy lại SDK (ví dụ ở lần tải trang tiếp theo) để lấy token mới.

Thống kê tổng hợp

Kéo các bộ đếm trong một khoảng thời gian (tổng số, số bot, và phần phân tách theo level và theo ngày) 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

{
  "from": "2026-06-01",
  "to": "2026-06-30",
  "cleaned": true,
  "total": 124500,
  "bots": 18230,
  "by_level": { "low": 100300, "medium": 16900, "high": 6200, "critical": 1100 },
  "by_day": [
    { "date": "2026-06-01", "total": 4100, "bots": 590 }
  ]
}

from / to mặc định là 7 ngày gần nhất.

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. Các dòng được trả về theo thứ tự mới nhất trước, theo từng trang.

bash

GET /v1/bot/export?from=2026-06-01&to=2026-06-30&limit=1000
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

Tham số	Mô tả
`from` / `to`	Khoảng ngày (`YYYY-MM-DD`). Tùy chọn.
`limit`	Số dòng mỗi trang, 1–5000 (mặc định 1000).
`cursor`	Truyền `next_cursor` của trang trước để lấy trang tiếp theo.

json

{
  "rows": [
    {
      "id": 1042, "cid": null, "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
      "is_bot": false, "score": 12, "level": "low", "action": "record_only",
      "reasons": [], "consistency": { "ok": true }, "degraded": false,
      "created_at": "2026-06-25 00:00:00", "rescored": false
    }
  ],
  "next_cursor": 1042
}

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

Số liệu đã làm sạch

Thống kê và dữ liệu xuất mặc định được báo cáo theo cơ sở đã làm sạch: lưu lượng về sau được xác định là không hợp lệ sẽ liên tục được đánh giá lại và loại khỏi các con số. Việc này diễn ra bất đồng bộ, nên số liệu của các khoảng thời gian rất gần đây vẫn có thể thay đổi nhẹ. Truyền ?raw=1 để xem số liệu chưa làm sạch; trong export, mỗi dòng cũng mang cờ rescored.

Đố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 được chống phát lại: cùng một khách truy cập tải lại trang thì không sao, nhưng token bị dùng lại ở nơi khác sẽ bị gắn cờ. 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)}`

Postback (máy chủ đến máy chủ)

Thay vì thăm dò Data API, bạn có thể để các phán quyết được đẩy tới endpoint của riêng bạn ngay khi chúng phát sinh — tiện cho các tracker affiliate và back-end của nhà quảng cáo muốn ghi nhận hoặc đối soát từng lượt truy cập theo thời gian thực.

Bật tính năng

Trong bảng điều khiển, mở ứng dụng của bạn → Chống gian lận → đặt Postback URL (bot_postback_url). Khi đã đặt, mỗi phán quyết sẽ được POST tới URL đó ngay sau khi được tạo ra. Việc gửi diễn ra bất đồng bộ và tách biệt — endpoint chậm hoặc lỗi không bao giờ ảnh hưởng tới phán quyết đã trả về cho SDK trên trang.

Khi nào được gửi

Mỗi lần verify tạo ra một phán quyết cho ứng dụng. Việc gửi theo kiểu best-effort với vài lần thử lại tự động; hãy coi nó là ít nhất một lần (at-least-once) và khử trùng lặp theo verdict_id.

Request

POST <your bot_postback_url>
Content-Type: application/json
X-Bot-Signature: t=<unix_ts>,v=<hex>

Body (JSON):

json

{
  "cid": "CID_OF_THE_VISIT",
  "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
  "is_bot": 1,
  "score": 87,
  "level": "high",
  "action": "flag",
  "advertiser_app_id": 12,
  "provider_app_id": 34,
  "created_at": "2026-06-25 00:00:00"
}

trường	mô tả
`cid`	khóa đối soát của lượt truy cập (có thể là `null` nếu không có click token)
`verdict_id`	id của phán quyết; cùng giá trị mà trang đã nhận
`is_bot`	`1` / `0`
`score`	điểm rủi ro
`level`	`low` / `medium` / `high` / `critical`
`action`	hành động có thẩm quyền từ máy chủ (`record_only` / `flag` / `challenge` / `deny`)
`advertiser_app_id`	id của ứng dụng mà lần verify chạy cho
`provider_app_id`	id nhà cung cấp lưu lượng khi được quy về qua click token, nếu không thì `null`
`created_at`	thời điểm phán quyết (UTC)

Xác minh chữ ký

Header X-Bot-Signature cho phép bạn xác nhận request thực sự đến từ chúng tôi. Nó có dạng t=<unix_ts>,v=<hex>, trong đó:

hex = HMAC_SHA256( "<unix_ts>." + raw_request_body , bot_hmac_secret )

bot_hmac_secret chính là bí mật ký bạn phát hành tại Chống gian lận → Phát hành khóa ký. Để xác minh, hãy tính lại HMAC trên body thô mà bạn nhận được (đừng tuần tự hóa lại JSON) và so sánh theo thời gian hằng định. Tùy chọn từ chối các request có t lệch quá xa so với đồng hồ của bạn để giới hạn tấn công phát lại.

// Ví dụ Express
const [tsPart, vPart] = req.get('X-Bot-Signature').split(',')
const ts = tsPart.slice(2)             // tiền tố "t="
const v  = vPart.slice(2)              // tiền tố "v="
const expected = crypto
  .createHmac('sha256', BOT_HMAC_SECRET)
  .update(ts + '.' + rawBody)          // rawBody là body request chưa được phân tích
  .digest('hex')
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v))

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

Fraud Prevention Data API ​

URL cơ sở ​

Xác thực ​

Các điểm cuối ​

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

Xác minh verdict token ​

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

Xuất dữ liệu ​

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

Lấy thông tin xác thực để ký ​

Định dạng token ​

Các trường của payload ​

Thêm vào liên kết ​

Ví dụ (mã giả) ​

Postback (máy chủ đến máy chủ) ​

Bật tính năng ​

Khi nào được gửi ​

Request ​

Xác minh chữ ký ​

Bước tiếp theo ​

Fraud Prevention Data API

URL cơ sở

Xác thực

Các điểm cuối

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

Xác minh verdict token

Thống kê tổng hợp

Xuất dữ liệu

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

Lấy thông tin xác thực để ký

Định dạng token

Các trường của payload

Thêm vào liên kết

Ví dụ (mã giả)

Postback (máy chủ đến máy chủ)

Bật tính năng

Khi nào được gửi

Request

Xác minh chữ ký

Bước tiếp theo