Referensi API

CaptchaLa menyediakan RESTful API untuk semua integrasi sisi server.

Base URL

https://apiv1.captcha.la

Hanya ada satu base URL

Semua endpoint di halaman ini berada di apiv1.captcha.la. Host cadangan (bypass.*, fallbackapiv1.*) adalah target failover yang dihubungi SDK sendiri saat terjadi gangguan — mengarahkan integrasi Anda ke sana akan mengembalikan service_online.

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

client_ip bersifat opsional tetapi disarankan — IP pengguna akhir dari request masuk Anda, dipakai untuk pemeriksaan risiko tambahan; aman untuk dihilangkan.

{
  "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 adalah data informasional (untuk logging / analisis risiko Anda): platform, user_ip (IP saat tantangan 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.

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.

Endpoint fallback offline

CaptchaLa menjalankan layanan cadangan di host terpisah agar verifikasi tetap berjalan saat API utama tidak dapat dijangkau:

Host	Dipanggil oleh	Fungsi
bypass.captchala.com · bypass.captcha-cdn.net	SDK web / native (sisi pengguna akhir)	Menjalankan verifikasi offline dan menerbitkan pass token offline_ selama API utama down
fallbackapiv1.captchala.com · fallbackapiv1.captcha-cdn.net	SDK server	Memvalidasi token offline_ (POST /api/validate)

Ini target failover, bukan API alternatif. SDK berpindah ke sana sendiri, hanya setelah API utama benar-benar gagal, lalu kembali otomatis begitu pulih. Tidak ada bagian konfigurasi Anda yang boleh menunjuk ke host ini.

service_online (HTTP 503)

{ "code": -1, "error": "service_online", "message": "Main API is online, please use main API" }

Error ini muncul saat API utama sedang online: layanan cadangan hanya melayani ketika terjadi gangguan. Request masuk ke bypass.*, bukan ke https://apiv1.captcha.la — perbaiki URL-nya, retry tidak membantu.

Penyebab umum:

Penyebab	Perbaikan
Opsi SDK apiServer diarahkan ke host bypass	Kembalikan ke https://apiv1.captcha.la, atau hapus opsinya dan biarkan SDK memilih
bypassServers ditimpa manual	Hapus penimpaan, kecuali kami memang memberi Anda host khusus
HTTP client buatan sendiri menyalin URL bypass (mis. dari devtools saat insiden)	Panggil https://apiv1.captcha.la dan serahkan failover ke SDK — layanan cadangan tidak menerima trafik challenge normal
Load balancer / proxy / DNS menulis ulang host API	Arahkan upstream kembali ke apiv1.captcha.la

TIP

Validasi sisi server juga tidak butuh host fallback: cukup POST /v1/validate di apiv1.captcha.la, dan SDK server PHP / Go menangani token offline_ lewat API cadangan secara otomatis.

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.
service_online	Request masuk ke layanan fallback offline padahal API utama sedang online. Gunakan https://apiv1.captcha.la — lihat Endpoint fallback offline.