---
title: Rujukan API
---

# Rujukan API

CaptchaLa menyediakan antara muka RESTful API, menyokong panggilan pelayan untuk semua ciri.

## URL Asas API

```
https://apiv1.captcha.la
```

## Kaedah Pengesahan

Semua permintaan API memerlukan header pengesahan:

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

::: warning
`X-App-Secret` is server-side only. Never expose it to browsers, mobile apps, or public repos.
:::

## API Pengesahan Sisi Pelayan

> 💡 **Gunakan SDK server untuk skip boilerplate.** Bungkus endpoint, retry, ralat bertaip:
> - **PHP** — [`Captcha-La/captchala-php`](https://github.com/Captcha-La/captchala-php)
> - **Go** — `go get github.com/Captcha-La/captchala-go`

Selepas pengguna melepasi CAPTCHA di frontend, pelayan anda perlu mengesahkan token yang dikembalikan oleh SDK. Berikut ialah endpoint pengesahan sisi pelayan.

### Pengesahan Token Sisi Pelayan

Sahkan pass_token yang dikembalikan oleh SDK frontend (awalan pt_). Memerlukan header X-App-Key dan X-App-Secret.

```bash
POST /v1/validate
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "pass_token": "pt_xxx", "client_ip": "1.2.3.4" }
```

`client_ip` adalah pilihan tetapi disyorkan — IP pengguna akhir daripada permintaan masuk anda, digunakan untuk pemeriksaan risiko tambahan; selamat untuk ditinggalkan.

```json
{
  "code": 0,
  "data": {
    "valid": true,
    "challenge_id": "ch_xxx",
    "action": "login",
    "uid": null,
    "captcha_args": {
      "platform": "web",
      "user_ip": "1.2.3.4",
      "referer": "https://your-site.com/login",
      "pkg": null,
      "solved_at": 1750000000,
      "risk_score": 12
    }
  }
}
```

`captcha_args` ialah data bermaklumat (untuk pengelogan / penilaian risiko anda): `platform`, `user_ip` (IP semasa challenge diselesaikan), `referer`, `pkg`, `solved_at`, `risk_score`.

::: tip
Validate `data.valid === true` **and** that `data.action` matches the scene you expected
(reject if a token from a `pay` flow is presented at `/login`). Tokens are single-use.
:::

## Token Cabaran Dikeluarkan Pelayan {#server-token}

Keluarkan server_token jangka pendek dari backend anda. Pelayar kemudian menghantar token ini semasa memulakan cabaran.

### Keluarkan server_token

Panggil endpoint ini dari pelayan anda sahaja. Memerlukan X-App-Key + X-App-Secret.

```bash
POST /v1/server/challenge/issue
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/x-www-form-urlencoded

action=login&ttl=300&max_uses=1&bind_ip=1.2.3.4
```

```json
{
  "code": 0,
  "data": {
    "server_token": "sct_xxxxxxxxxxxx",
    "expires_in": 300,
    "issued_at": 1713600000
  }
}
```

#### Parameter Badan (form-urlencoded)

| Medan | Penerangan |
| --- | --- |
| `action` | Senario perniagaan (login, register, pay). |
| `ttl` | Tempoh sah token (saat). Lalai 300, maksimum 900. |
| `max_uses` | Bilangan penggunaan maksimum. Lalai 10. |
| `bind_ip` | Ikat token kepada IP pelanggan tertentu. |
| `bind_device_id` | Ikat token kepada ID peranti tertentu. |
| `bind_fingerprint` | Ikat token kepada cap jari pelayar tertentu. |

### Inisialisasi Cabaran

Dipanggil oleh SDK untuk memulakan cabaran CAPTCHA. Menerima server_token pilihan yang dikeluarkan oleh /v1/server/challenge/issue.

| Medan | Penerangan |
| --- | --- |
| `app_key` | App Key awam anda. |
| `action` | Senario perniagaan, mesti sepadan dengan yang digunakan untuk mengeluarkan server_token. |
| `server_token` | Pilihan; diperlukan apabila aplikasi mempunyai server_token_required = true. |

::: info
Jika server_token_required diaktifkan, inisialisasi pengesahan akan menolak permintaan tanpa server_token yang sah.
:::

## Kod Ralat

| Kod | Penerangan |
| --- | --- |
| `invalid_app_key` | App Key tidak sah |
| `invalid_app_secret` | App Secret tidak sah |
| `challenge_expired` | Challenge telah tamat tempoh |
| `challenge_not_found` | Challenge tidak ditemui |
| `invalid_answer` | Jawapan tidak sah |
| `token_expired` | Token telah tamat tempoh |
| `token_already_used` | Token telah digunakan |
| `token_not_found` | Token tidak ditemui |
| `quota_exceeded` | Kuota telah habis |
| `rate_limited` | Terkena had kadar |
| `rate_limit_exceeded` | Terlalu banyak permintaan penerbitan untuk aplikasi ini. Undur dan cuba lagi. |