API Data Pencegahan penipuan

Data API adalah pasangan sisi server dari Web SDK. Gunakan untuk menarik verdict, mengagregasi statistik, dan mengekspor data untuk pelaporan dan rekonsiliasi — menarik angka yang disepakati oleh sistem Anda sendiri.

Base URL

https://apiv1.captcha.la

Autentikasi

Semua permintaan Data API diautentikasi dengan kredensial aplikasi Fraud Prevention Anda, dikirim sebagai header:

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

WARNING

X-App-Secret bersifat hanya sisi server. Jangan pernah mengeksposnya ke browser, aplikasi seluler, atau repositori publik. SDK halaman hanya pernah memakai appKey publik.

Endpoint

Mengambil verdict

Ambil verdict untuk satu kunjungan (mis. untuk merekonsiliasi kunjungan tertentu).

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

Respons data adalah objek BotVerdict:

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

Statistik teragregasi

Tarik jumlah berkelompok pada rentang waktu — total, porsi bot, dan rincian berdasarkan action/level — untuk dashboard dan laporan kualitas.

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

Ekspor

Ekspor baris verdict per-kunjungan untuk rentang waktu, untuk rekonsiliasi offline.

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 identifier kunjungan, timestamp, dan field verdict (is_bot, score, level, action), sehingga Anda dapat menggabungkannya kembali dengan log Anda sendiri.

Rekonsiliasi per-klik

Untuk skenario trafik berbayar, satu kunjungan dapat diikat kembali ke klik tertentu yang dikirim sehingga dua pihak dapat menyelesaikannya. Itu menggunakan click token dan dibahas di panduan Penipuan iklan.

Referensi click token (untuk penyedia trafik)

Penyedia trafik menandatangani click token di servernya sendiri dan menambahkannya ke URL tujuan, sehingga verdict untuk kunjungan yang dihasilkan diatribusikan kembali ke penyedia tersebut. Penandatanganan dilakukan secara offline — tanpa pemanggilan API.

Dapatkan kredensial penandatanganan Anda

Di dashboard, buka aplikasi Anda → Fraud Prevention → Issue signing key. Anda akan menerima:

• bot_kid — id kunci publik Anda (masuk ke dalam token sebagai pkid).
• bot_hmac_secret — secret penandatanganan Anda, ditampilkan satu kali. Simpan di sisi server.

Format token

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

body adalah base64url dari payload JSON; signature dihitung atas string body tersebut.

Field payload

field	wajib	deskripsi
pkid	ya	bot_kid Anda; backend menggunakannya untuk mencari secret Anda dan memverifikasi signature
cid	ya	id unik untuk klik ini; kunci rekonsiliasi. Hasilkan nilai baru yang unik untuk setiap klik
aud	tidak	app_key dari pengiklan target. Bila diisi, token hanya diterima pada halaman pengiklan tersebut. Kosongkan agar halaman pengiklan mana pun dapat menerimanya
click_ts	tidak	unix seconds saat klik terjadi
exp	tidak	unix seconds masa berlaku; token yang kedaluwarsa ditolak

Tambahkan ke link

Tambahkan token sebagai query parameter _ctk pada URL tujuan pengiklan:

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

SDK pengiklan membaca _ctk secara otomatis (dapat dikonfigurasi melalui tokenParam). Sebuah cid hanya dapat diklaim satu kali (terlindung dari replay). Lihat Model keamanan.

Contoh (pseudo-code)

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 berikutnya

• Referensi verdict — field yang dikembalikan oleh endpoint ini
• Web SDK — kumpulkan verdict pada halaman Anda