Referensi API

CaptchaLa menyediakan RESTful API untuk semua integrasi sisi server.

Base URL

https://apiv1.captcha.la

Autentikasi

Semua request API membutuhkan header autentikasi:

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 Validasi Sisi Server

💡 Gunakan SDK server untuk lewati boilerplate. Membungkus endpoint, retry, error bertipe:

• PHP — Captcha-La/captchala-php
• Go — go get github.com/Captcha-La/captchala-go

Setelah pengguna lulus CAPTCHA di frontend, server Anda perlu memvalidasi token yang dikembalikan SDK. Berikut endpoint validasi sisi server.

Validasi Token Sisi Server

Validasi pass_token yang dikembalikan SDK frontend (prefix pt_). Membutuhkan header X-App-Key dan X-App-Secret.

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

{
  "code": 0,
  "data": {
    "valid": true,
    "challenge_id": "ch_xxx",
    "action": "login",
    "uid": null,
    "client_ip": "1.2.3.4",
    "risk_score": 12
  }
}

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.

Challenge Token yang Diterbitkan Server

Terbitkan server_token berumur pendek dari backend Anda. Browser lalu meneruskan token ini saat menginisialisasi challenge, membuktikan bahwa request berasal dari server tepercaya Anda.

Terbitkan Server Token

Panggil endpoint ini hanya dari server Anda sendiri. Membutuhkan X-App-Key + X-App-Secret. Respons berisi server_token (prefix sct_) yang akan diteruskan frontend ke inisialisasi verifikasi.

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

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

Body Parameters (form-urlencoded)

Field	Deskripsi
action	Scene bisnis, mis. login, register, pay. Harus cocok dengan action yang digunakan di inisialisasi verifikasi.
ttl	Masa berlaku token dalam detik. Default 300, maksimum 900.
max_uses	Maksimal jumlah token dapat dikonsumsi. Default 10.
bind_ip	Ikat token ke IP client. Inisialisasi dari IP lain akan ditolak.
bind_device_id	Ikat token ke device id tertentu.
bind_fingerprint	Ikat token ke fingerprint browser tertentu.

Inisialisasi Challenge

Dipanggil oleh SDK untuk memulai CAPTCHA challenge. Menerima server_token opsional yang diterbitkan oleh /v1/server/challenge/issue.

Field	Deskripsi
app_key	App Key publik Anda.
action	Scene bisnis. Harus cocok dengan action yang digunakan saat menerbitkan server_token.
server_token	Opsional; wajib ketika app memiliki server_token_required = true.

INFO

Jika server_token_required diaktifkan untuk app ini di dashboard, inisialisasi verifikasi akan menolak request yang tidak membawa server_token yang valid.

Error Code

Kode	Deskripsi
invalid_app_key	App Key tidak valid
invalid_app_secret	App Secret tidak valid
challenge_expired	Challenge kedaluwarsa
challenge_not_found	Challenge tidak ditemukan
invalid_answer	Jawaban tidak valid
token_expired	Token kedaluwarsa
token_already_used	Token sudah digunakan
token_not_found	Token tidak ditemukan
quota_exceeded	Kuota terlampaui
rate_limited	Terkena rate limit
rate_limit_exceeded	Terlalu banyak request penerbitan untuk app ini. Lakukan back off dan coba lagi.