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://verify.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). Kirim tepat satu identifier: verdict_id (dari verdict yang diterima halaman) atau cid (click id, untuk trafik dengan 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 menunjukkan apakah verdict ditemukan. Jika bernilai true, data berisi field verdict yang dijelaskan di Referensi Verdict:

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

Jika tidak ada yang cocok, responsnya adalah {"found": false}. Permintaan tanpa verdict_id maupun cid ditolak dengan HTTP 400.

TIP

Verdict disimpan beberapa detik setelah dihasilkan, sehingga pencarian tepat setelah kunjungan dapat mengembalikan found: false. Untuk memeriksa kunjungan secara real time, gunakan Memverifikasi verdict token.

Memverifikasi verdict token

Periksa verdict_token yang diterima halaman Anda dari Web SDK. Gunakan ini untuk membatasi akses konten di server Anda (lihat Verifikasi sisi server). Pemeriksaan dijawab seketika dan tidak bergantung pada data yang 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	Deskripsi
`token`	ya	`verdict_token` dari verdict.
`ip`	tidak	Alamat IP pengunjung seperti yang dilihat server Anda. Jika diberikan, token harus berasal dari jaringan yang sama dengan kunjungan. Direkomendasikan.
`consume`	tidak	`true` = token hanya dapat dipakai sekali; pemeriksaan kedua mengembalikan `already_used`. Default `false`: token dapat diperiksa lagi hingga kedaluwarsa.

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

Field	Deskripsi
`valid`	`true` jika token asli, milik aplikasi Anda, belum kedaluwarsa, cocok dengan `ip` (jika diberikan) dan, dengan `consume`, belum pernah dipakai. `valid` hanya menyatakan token itu asli. Ini tidak menyatakan pengunjung adalah manusia, jadi periksa juga `verdict`.
`error`	`null`, atau alasan token tidak valid: `malformed`, `bad_signature`, `expired`, `ip_mismatch`, `already_used`, `unavailable` (pemeriksaan sekali pakai tidak dapat diselesaikan; coba lagi).
`expired` / `expires_at`	Status kedaluwarsa dan waktu kedaluwarsa (detik Unix).
`ip_match`	`true` / `false` jika `ip` diberikan, selain itu `null`.
`verdict`	Verdict yang ditandatangani: `is_bot`, `level`, `action`, `score`, `degraded`, `reasons`, `issued_at`. `null` jika token tidak dapat dibaca.

Gerbang yang umum menyajikan konten ketika valid bernilai true dan verdict.is_bot bernilai false. Tentukan sendiri cara menangani verdict.degraded dan permintaan yang sama sekali tidak membawa token. Jika Anda memilih fail open, pengunjung asli tetap bisa masuk saat terjadi gangguan. Jika Anda memilih fail closed, tidak ada yang bisa masuk tanpa token valid.

Token kedaluwarsa setelah 10 menit secara default. Jalankan ulang SDK (misalnya pada pemuatan halaman berikutnya) untuk mendapatkan token baru.

Statistik teragregasi

Tarik jumlah pada rentang waktu (total, bot, dan rincian berdasarkan level dan per hari) untuk dashboard dan laporan kualitas.

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 default ke 7 hari terakhir.

Ekspor

Ekspor baris verdict per-kunjungan untuk rentang waktu, untuk rekonsiliasi offline. Baris dikembalikan dari yang terbaru, secara berhalaman.

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	Deskripsi
`from` / `to`	Rentang tanggal (`YYYY-MM-DD`). Opsional.
`limit`	Baris per halaman, 1–5000 (default 1000).
`cursor`	Kirim `next_cursor` dari halaman sebelumnya untuk mendapatkan halaman berikutnya.

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 identifier kunjungan, timestamp, dan field verdict, sehingga Anda dapat menggabungkannya kembali dengan log Anda sendiri. next_cursor bernilai null di halaman terakhir.

Angka yang dibersihkan

Statistik dan ekspor secara default dilaporkan atas dasar yang dibersihkan: trafik yang belakangan teridentifikasi tidak valid terus dievaluasi ulang dan dikeluarkan dari angka. Proses ini berjalan secara asinkron, sehingga angka untuk jendela waktu yang sangat baru mungkin masih sedikit berubah. Berikan ?raw=1 untuk melihat angka yang belum dibersihkan; di export, setiap baris juga membawa flag rescored.

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). Setiap cid dilindungi dari replay: pengunjung yang sama memuat ulang halaman tidak masalah, tetapi token yang dipakai ulang di tempat lain akan ditandai. 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)}`

Postback (server-ke-server)

Alih-alih melakukan polling ke Data API, Anda dapat meminta verdict dikirim (push) ke endpoint Anda sendiri saat terjadi — berguna untuk affiliate tracker dan back-end pengiklan yang ingin mencatat atau merekonsiliasi setiap kunjungan secara real time.

Mengaktifkannya

Di dashboard, buka aplikasi Anda → Fraud Prevention → atur Postback URL (bot_postback_url). Setelah diatur, setiap verdict dikirim via POST ke URL tersebut sesaat setelah dihasilkan. Pengiriman bersifat asinkron dan terisolasi — endpoint yang lambat atau gagal tidak pernah memengaruhi verdict yang sudah dikembalikan ke SDK halaman.

Kapan dipicu

Pada setiap verify yang menghasilkan verdict untuk aplikasi. Pengiriman bersifat best-effort dengan beberapa percobaan ulang otomatis; perlakukan sebagai at-least-once dan lakukan deduplikasi berdasarkan 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"
}

field	deskripsi
`cid`	kunci rekonsiliasi untuk kunjungan (bisa `null` jika tidak ada click token)
`verdict_id`	id verdict; nilai yang sama dengan yang diterima halaman
`is_bot`	`1` / `0`
`score`	skor risiko
`level`	`low` / `medium` / `high` / `critical`
`action`	action otoritatif di server (`record_only` / `flag` / `challenge` / `deny`)
`advertiser_app_id`	id aplikasi tempat verify dijalankan
`provider_app_id`	id penyedia trafik bila diatribusikan melalui click token, jika tidak `null`
`created_at`	waktu verdict (UTC)

Memverifikasi signature

Header X-Bot-Signature memungkinkan Anda memastikan request benar-benar berasal dari kami. Nilainya t=<unix_ts>,v=<hex> dengan:

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

bot_hmac_secret adalah secret penandatanganan yang sama yang Anda terbitkan di Fraud Prevention → Issue signing key. Untuk memverifikasi, hitung ulang HMAC atas body mentah yang Anda terima (jangan serialisasi ulang JSON-nya) dan bandingkan dalam waktu konstan. Secara opsional, tolak request yang nilai t-nya terlalu jauh dari jam Anda untuk membatasi replay.

// 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 berikutnya

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

API Data Pencegahan penipuan ​

Base URL ​

Autentikasi ​

Endpoint ​

Mengambil verdict ​

Memverifikasi verdict token ​

Statistik teragregasi ​

Ekspor ​

Referensi click token (untuk penyedia trafik) ​

Dapatkan kredensial penandatanganan Anda ​

Format token ​

Field payload ​

Tambahkan ke link ​

Contoh (pseudo-code) ​

Postback (server-ke-server) ​

Mengaktifkannya ​

Kapan dipicu ​

Request ​

Memverifikasi signature ​

Langkah berikutnya ​

API Data Pencegahan penipuan

Base URL

Autentikasi

Endpoint

Mengambil verdict

Memverifikasi verdict token

Statistik teragregasi

Ekspor

Referensi click token (untuk penyedia trafik)

Dapatkan kredensial penandatanganan Anda

Format token

Field payload

Tambahkan ke link

Contoh (pseudo-code)

Postback (server-ke-server)

Mengaktifkannya

Kapan dipicu

Request

Memverifikasi signature

Langkah berikutnya