---
title: Pencegahan penipuan — API Data
---

# API Data Pencegahan penipuan

Data API adalah pasangan sisi server dari [Web SDK](./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).

```bash
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`](./verdict-reference):

```json
{
  "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.

```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
{
  "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.

```bash
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.

::: tip 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](./scenarios/ad-fraud).
:::

## 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](./scenarios/ad-fraud#model-keamanan).

### Contoh (pseudo-code)
```js
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](./verdict-reference) — field yang dikembalikan oleh endpoint ini
- [Web SDK](./web-sdk) — kumpulkan verdict pada halaman Anda