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://verify.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). Hantar tepat satu pengecam: verdict_id (daripada keputusan yang diterima halaman) atau cid (id klik, untuk trafik token klik).

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 memberitahu sama ada keputusan ditemui. Apabila ia true, data memegang medan keputusan yang diterangkan dalam Verdict Reference:

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

Apabila tiada padanan, respons ialah {"found": false}. Permintaan tanpa verdict_id mahupun cid ditolak dengan HTTP 400.

TIP

Keputusan disimpan beberapa saat selepas ia dihasilkan, jadi carian yang dibuat sejurus selepas lawatan boleh mengembalikan found: false. Untuk menyemak lawatan secara masa nyata, gunakan Sahkan token keputusan.

Sahkan token keputusan

Semak verdict_token yang diterima halaman anda daripada Web SDK. Gunakan ini untuk mengawal akses kandungan pada pelayan anda (lihat Pengesahan sebelah pelayan). Semakan dijawab serta-merta dan tidak bergantung pada data tersimpan.

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 }

Parameter	Wajib	Penerangan
`token`	ya	`verdict_token` daripada keputusan.
`ip`	tidak	Alamat IP pelawat seperti yang dilihat oleh pelayan anda. Apabila diberi, token mesti datang daripada rangkaian yang sama dengan lawatan. Disyorkan.
`consume`	tidak	`true` = token hanya boleh digunakan sekali; semakan kedua mengembalikan `already_used`. Lalai `false`: token boleh disemak semula sehingga tamat tempoh.

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

Medan	Penerangan
`valid`	`true` apabila token tulen, milik aplikasi anda, belum tamat tempoh, sepadan dengan `ip` (jika diberi) dan, dengan `consume`, belum digunakan. `valid` hanya menyatakan token itu tulen. Ia tidak menyatakan pelawat ialah manusia, jadi semak juga `verdict`.
`error`	`null`, atau sebab token tidak sah: `malformed`, `bad_signature`, `expired`, `ip_mismatch`, `already_used`, `unavailable` (semakan sekali guna tidak dapat diselesaikan; cuba semula).
`expired` / `expires_at`	Status tamat tempoh dan masa tamat tempoh (saat Unix).
`ip_match`	`true` / `false` apabila `ip` diberi, jika tidak `null`.
`verdict`	Keputusan yang ditandatangani: `is_bot`, `level`, `action`, `score`, `degraded`, `reasons`, `issued_at`. `null` apabila token tidak dapat dibaca.

Kawalan biasa menyampaikan kandungan apabila valid ialah true dan verdict.is_bot ialah false. Tentukan sendiri cara mengendalikan verdict.degraded dan permintaan yang langsung tiada token. Jika anda memilih untuk membenarkan (fail open), pelawat sebenar masih dapat masuk semasa gangguan. Jika anda memilih untuk menolak (fail closed), tiada apa yang dapat masuk tanpa token yang sah.

Token tamat tempoh selepas 10 minit secara lalai. Jalankan semula SDK (contohnya pada pemuatan halaman seterusnya) untuk mendapatkan token baharu.

Statistik teragregat

Tarik kiraan sepanjang julat masa (jumlah, bot, dan pecahan mengikut level dan mengikut hari) untuk papan pemuka dan laporan kualiti.

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 lalai kepada 7 hari terakhir.

Eksport

Eksport baris keputusan per lawatan untuk satu julat masa, untuk penyelarasan luar talian. Baris dikembalikan bermula dengan yang terbaharu, dalam halaman.

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

Parameter	Penerangan
`from` / `to`	Julat tarikh (`YYYY-MM-DD`). Pilihan.
`limit`	Baris setiap halaman, 1–5000 (lalai 1000).
`cursor`	Hantar `next_cursor` halaman sebelumnya untuk mendapatkan halaman seterusnya.

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
}

Setiap baris membawa pengecam lawatan, cap masa, dan medan keputusan, supaya anda boleh mencantumkannya semula kepada log anda sendiri. next_cursor ialah null pada halaman terakhir.

Angka yang dibersihkan

Statistik dan eksport dilaporkan atas dasar dibersihkan secara lalai: trafik yang kemudiannya dikenal pasti sebagai tidak sah dinilai semula secara berterusan dan dikeluarkan daripada angka. Ini berlaku secara tak segerak, jadi angka bagi tetingkap yang sangat baharu mungkin masih berubah sedikit. Hantar ?raw=1 untuk melihat angka yang belum dibersihkan; dalam export, setiap baris juga membawa bendera rescored.

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). Setiap cid dilindungi daripada main semula: pelawat yang sama memuat semula halaman tidak mengapa, tetapi token yang digunakan semula di tempat lain akan ditanda. 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)}`

Postback (pelayan ke pelayan)

Daripada meninjau Data API, anda boleh meminta keputusan ditolak ke titik akhir anda sendiri sebaik sahaja ia berlaku — berguna untuk penjejak afiliasi dan backend pengiklan yang ingin merekod atau menyelaraskan setiap lawatan secara masa nyata.

Dayakannya

Dalam papan pemuka, buka aplikasi anda → Fraud Prevention → tetapkan Postback URL (bot_postback_url). Setelah ditetapkan, setiap keputusan di-POST ke URL tersebut sejurus selepas ia dihasilkan. Penghantaran adalah tak segerak dan terasing — titik akhir yang perlahan atau gagal tidak sekali-kali menjejaskan keputusan yang telah dikembalikan kepada SDK halaman.

Bila ia dicetuskan

Pada setiap pengesahan yang menghasilkan keputusan untuk aplikasi. Penghantaran adalah atas dasar usaha terbaik dengan beberapa cubaan semula automatik; anggap ia sebagai sekurang-kurangnya sekali dan nyahduplikasi berdasarkan verdict_id.

Permintaan

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

Badan (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"
}

field	description
`cid`	kunci penyelarasan untuk lawatan (mungkin `null` jika tiada token klik)
`verdict_id`	id keputusan; nilai yang sama yang diterima oleh halaman
`is_bot`	`1` / `0`
`score`	skor risiko
`level`	`low` / `medium` / `high` / `critical`
`action`	tindakan berautoriti pelayan (`record_only` / `flag` / `challenge` / `deny`)
`advertiser_app_id`	id aplikasi tempat pengesahan dijalankan
`provider_app_id`	id penyedia trafik apabila dikaitkan melalui token klik, jika tidak `null`
`created_at`	masa keputusan (UTC)

Sahkan tandatangan

Pengepala X-Bot-Signature membolehkan anda mengesahkan bahawa permintaan itu benar-benar datang daripada kami. Formatnya t=<unix_ts>,v=<hex> dengan:

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

bot_hmac_secret ialah rahsia penandatanganan yang sama yang anda keluarkan di bawah Fraud Prevention → Issue signing key. Untuk mengesahkan, kira semula HMAC ke atas badan mentah yang anda terima (jangan sirikan semula JSON) dan bandingkan dalam masa malar. Secara pilihan, tolak permintaan yang t-nya terlalu jauh daripada jam anda untuk mengehadkan main semula.

// Express example
const [tsPart, vPart] = req.get('X-Bot-Signature').split(',')
const ts = tsPart.slice(2)             // "t=" prefix
const v  = vPart.slice(2)              // "v=" prefix
const expected = crypto
  .createHmac('sha256', BOT_HMAC_SECRET)
  .update(ts + '.' + rawBody)          // rawBody is the unparsed request body
  .digest('hex')
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v))

Langkah seterusnya

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

Fraud Prevention Data API ​

URL asas ​

Pengesahan ​

Titik akhir ​

Dapatkan keputusan ​

Sahkan token keputusan ​

Statistik teragregat ​

Eksport ​

Rujukan token klik (untuk penyedia trafik) ​

Dapatkan kelayakan penandatanganan anda ​

Format token ​

Medan payload ​

Tambahkannya pada pautan ​

Contoh (pseudo-kod) ​

Postback (pelayan ke pelayan) ​

Dayakannya ​

Bila ia dicetuskan ​

Permintaan ​

Sahkan tandatangan ​

Langkah seterusnya ​

Fraud Prevention Data API

URL asas

Pengesahan

Titik akhir

Dapatkan keputusan

Sahkan token keputusan

Statistik teragregat

Eksport

Rujukan token klik (untuk penyedia trafik)

Dapatkan kelayakan penandatanganan anda

Format token

Medan payload

Tambahkannya pada pautan

Contoh (pseudo-kod)

Postback (pelayan ke pelayan)

Dayakannya

Bila ia dicetuskan

Permintaan

Sahkan tandatangan

Langkah seterusnya