Fraud Prevention Data API

Data API ialah pasangan bahagian pelayan kepada Web SDK. Gunakannya untuk menarik keputusan, mengagregat statistik, dan mengeksport data untuk pelaporan dan penyelarasan — menarik angka yang sistem anda sendiri persetujui.

URL asas

https://apiv1.captcha.la

Pengesahan

Semua permintaan Data API disahkan dengan kelayakan aplikasi Fraud Prevention anda, dihantar sebagai pengepala:

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

WARNING

X-App-Secret adalah bahagian pelayan sahaja. Jangan sekali-kali dedahkannya kepada pelayar, aplikasi mudah alih, atau repositori awam. SDK halaman hanya menggunakan appKey awam.

Titik akhir

Dapatkan keputusan

Dapatkan keputusan untuk satu lawatan (cth. untuk menyelaras lawatan tertentu).

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

data respons ialah objek BotVerdict:

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

Statistik teragregat

Tarik kiraan berbaldi sepanjang julat masa — jumlah, bahagian bot, dan pecahan mengikut action/level — untuk papan pemuka dan laporan kualiti.

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

Eksport

Eksport baris keputusan per lawatan untuk satu julat masa, untuk penyelarasan luar talian.

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

Setiap baris membawa pengecam lawatan, cap masa, dan medan keputusan (is_bot, score, level, action), supaya anda boleh mencantumkannya semula kepada log anda sendiri.

Penyelarasan per klik

Untuk senario trafik berbayar, satu lawatan boleh diikat semula kepada klik tertentu yang dihantar supaya dua pihak boleh menyelesaikannya. Itu menggunakan token klik dan diliputi dalam panduan Ad fraud.

Rujukan token klik (untuk penyedia trafik)

Penyedia trafik menandatangani token klik pada pelayannya sendiri dan menambahkannya pada URL destinasi, supaya verdict bagi lawatan yang terhasil dikaitkan semula kepada penyedia tersebut. Penandatanganan dilakukan secara luar talian — tiada panggilan API.

Dapatkan kelayakan penandatanganan anda

Dalam papan pemuka, buka aplikasi anda → Fraud Prevention → Issue signing key. Anda akan menerima:

• bot_kid — id kunci awam anda (dimasukkan ke dalam token sebagai pkid).
• bot_hmac_secret — rahsia penandatanganan anda, dipaparkan sekali sahaja. Simpan ia di sebelah pelayan.

Format token

ct.<base64url(payload)>.<base64url(HMAC_SHA256(body, bot_hmac_secret))>

body ialah base64url bagi payload JSON; tandatangan dikira ke atas rentetan body tersebut.

Medan payload

field	required	description
pkid	ya	bot_kid anda; backend menggunakannya untuk mencari rahsia anda dan mengesahkan tandatangan
cid	ya	id unik untuk klik ini; kunci penyelarasan. Jana nilai baharu yang unik bagi setiap klik
aud	tidak	app_key bagi pengiklan sasaran. Apabila ditetapkan, token hanya dihormati pada halaman pengiklan tersebut. Tinggalkan kosong untuk membenarkan mana-mana halaman pengiklan menerimanya
click_ts	tidak	unix saat ketika klik berlaku
exp	tidak	unix saat tamat tempoh; token yang tamat tempoh ditolak

Tambahkannya pada pautan

Tambahkan token sebagai parameter pertanyaan _ctk pada URL destinasi pengiklan:

https://advertiser.example/lp?_ctk=ct.<...>.<...>

SDK pengiklan membaca _ctk secara automatik (boleh dikonfigurasi melalui tokenParam). Satu cid hanya boleh dituntut sekali sahaja (dilindungi daripada main semula). Lihat Model keselamatan.

Contoh (pseudo-kod)

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

Langkah seterusnya

• Verdict Reference — medan yang dikembalikan oleh titik akhir ini
• Web SDK — kumpul keputusan pada halaman anda