Referensi API
CaptchaLa menyediakan RESTful API untuk semua integrasi sisi server.
Base URL
https://apiv1.captcha.laHanya 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_SECRETWARNING
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.
Parameter Request
| Parameter | Wajib | Deskripsi |
|---|---|---|
pass_token | Ya | Token yang dikembalikan oleh SDK frontend |
client_ip | Tidak | IP pengguna akhir dari request masuk Anda |
keep_token | Tidak | true = periksa tanpa mengonsumsi token (default false) |
expected_action | Tidak | Action yang Anda harapkan untuk endpoint ini, mis. login. Jika diatur dan token diterbitkan untuk action lain, responsnya valid: false dengan error: "action_mismatch". Pencocokan persis, peka huruf besar/kecil. |
expected_hostname | Tidak | Hostname (web) atau package / bundle id aplikasi (native) yang Anda harapkan, mis. www.example.com. Menerima string yang dipisahkan koma atau array; *.example.com cocok dengan subdomain mana pun (bukan apex). Tidak peka huruf besar/kecil. Jika diatur dan token diselesaikan di tempat lain — atau asalnya tidak dapat ditentukan — responsnya valid: false dengan error: "hostname_mismatch". |
Tanpa expected_action / expected_hostname, perilaku tetap persis seperti sebelumnya. Saat terjadi mismatch, token tetap dikonsumsi (kecuali keep_token bernilai true), sehingga tidak dapat di-replay.
{
"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
},
"hostname": "your-site.com",
"challenge_ts": "2025-06-15T15:06:40Z",
"risk_level": "low",
"risk_labels": []
}
}TIP
Validasi bahwa data.valid === true dan data.action cocok dengan skenario yang Anda harapkan (tolak jika token dari alur pay dipakai di /login) — atau cukup kirim expected_action / expected_hostname dan biarkan API yang memeriksanya. Token hanya sekali pakai.
Field tambahan
Ditambahkan ke respons yang berhasil (semua field yang ada tidak berubah):
hostname— hostname halaman tempat challenge diselesaikan (web), atau package / bundle id aplikasi (native).nulljika tidak diketahui.challenge_ts— waktu challenge diselesaikan, ISO 8601 dalam UTC.nulljika tidak diketahui.risk_level— tingkat risiko saat penyelesaian:low/medium/high/critical.risk_labels— kategori risiko umum yang teramati untuk sesi ini, mis.automation,proxy,velocity,ip_reputation,device,inconsistency. Array kosong jika tidak ada yang menonjol. Label baru dapat ditambahkan seiring waktu — perlakukan nilai yang tidak dikenal sebagai informasi.
Ini adalah sinyal lunak untuk logging dan keputusan risiko Anda sendiri; token sudah diterima.
Respons mismatch:
{ "code": 0, "data": { "valid": false, "error": "action_mismatch" } }captcha_args
captcha_args mengembalikan konteks yang tercatat saat penyelesaian — untuk logging / penilaian risiko Anda sendiri:
platform—web/android/ios/flutter/windows/ …user_ip— IP pengguna akhir yang terlihat saat challenge diselesaikanreferer— URL halaman penyelesaian (web);nulldi nativepkg— package / bundle id aplikasi (native);nulldi websolved_at— waktu penyelesaian (unix seconds)risk_score— skor risiko saat penyelesaian (0-100, makin tinggi = makin berisiko)
Jenis Token
SDK dapat memberikan jenis token yang berbeda ke frontend Anda tergantung kondisi layanan. Prefiksnya menjelaskan semuanya:
| Prefiks | Diterbitkan saat | /v1/validate mengembalikan | Penanganan yang disarankan |
|---|---|---|---|
pt_ | Verifikasi lolos secara normal | valid: true (sekali pakai) | Terima |
dg_ | Kuota paket habis (mode degraded) | valid: false, degraded: true, reason | Keputusan Anda — lihat di bawah |
offline_ | API utama tidak dapat dijangkau; diterbitkan oleh bypass worker | Diverifikasi otomatis ke API cadangan saat menggunakan server SDK | Terima setelah verifikasi cadangan |
co_ | API utama dan cadangan tidak dapat dijangkau; dibuat di sisi klien | Tidak dapat diverifikasi di sisi server | Terapkan kontrol risiko Anda sendiri (rate limit, dll.) |
Mode Degraded (kuota habis)
Saat sebuah aplikasi telah menghabiskan kuota bulanannya (dan penagihan overage tidak tersedia), widget tidak menghentikan alur pengguna akhir Anda. Alih-alih menampilkan error, SDK langsung selesai dengan token dg_:
- Pengguna akhir tidak melihat error — formulir Anda terkirim seperti biasa.
/v1/validatedi server Anda mengembalikan:
{
"code": 0,
"data": {
"valid": false,
"degraded": true,
"reason": "quota_exhausted",
"expired": false
}
}Properti utama:
validselalufalseuntuk token degraded — aman secara default. Jika kode Anda hanya memeriksavalid, tidak ada yang berubah bagi Anda.- Mengizinkan request atau tidak adalah keputusan Anda: terima
valid || degradedagar konversi tetap berjalan sambil Anda meningkatkan paket, atau tolak dan tampilkan fallback Anda sendiri. - Token
dg_ditandatangani HMAC per aplikasi dan kedaluwarsa setelah 5 menit. Penerbitannya tidak memakai kuota dan tidak pernah ditagih. - Server SDK menyediakannya sebagai
isDegraded()/getDegradedReason()(PHP) danresult.Degraded/result.DegradedReason(Go).
INFO
Langganan yang kedaluwarsa tidak pernah memicu mode degraded — otomatis kembali ke paket Free dan tetap melayani dalam kuota gratis. Mode degraded hanya mencakup penggunaan di atas kuota paket Anda.
Test key
Gunakan pasangan key publik ini untuk menguji penanganan /v1/validate di server Anda — di CI, staging, atau pengembangan lokal — tanpa membuat aplikasi atau menyelesaikan CAPTCHA. Key ini bekerja dengan server SDK persis seperti App Key / App Secret sungguhan.
| Perilaku | X-App-Key | X-App-Secret |
|---|---|---|
| Selalu lolos | test_pass_7f3c9a2e5b18d4f6 | test_secret_pass_c41e8b0d27a95f3e |
| Selalu gagal | test_fail_2d9e6b4a0c7f1835 | test_secret_fail_9b5f03e7d1a46c28 |
- Selalu lolos —
pass_tokenapa pun yang tidak kosong mengembalikanvalid: true. Respons memiliki field yang sama dengan keberhasilan sungguhan, ditambahtest: true, sehingga kode parsing Anda ikut teruji:
{
"code": 0,
"data": {
"valid": true,
"test": true,
"challenge_id": null,
"action": "test",
"uid": null,
"captcha_args": {
"platform": "web",
"user_ip": null,
"referer": null,
"pkg": null,
"solved_at": 1750000000,
"risk_score": 0
},
"hostname": null,
"challenge_ts": "2025-06-15T15:06:40Z",
"risk_level": "low",
"risk_labels": []
}
}- Selalu gagal —
pass_tokenapa pun yang tidak kosong mengembalikan:
{ "code": 0, "data": { "valid": false, "error": "test_always_fail", "test": true } }Catatan:
- Secret harus cocok dengan key-nya; secret yang salah atau tertukar mengembalikan
invalid_app_secret, danpass_tokenkosong mengembalikanmissing_token, sama seperti aplikasi sungguhan. keep_token,expected_action, danexpected_hostnamediabaikan untuk test key.- Test key tidak pernah membuat catatan, tidak pernah dihitung ke kuota mana pun, dan tidak pernah ditagih. Key ini tidak dapat digunakan sebagai kredensial untuk aplikasi sungguhan.
- Periksa
data.testdi produksi dan tolak — atau cukup pastikan test key tidak pernah dikonfigurasi di produksi. - Saat ini hanya sisi server. Key ini menguji panggilan validasi di backend Anda; ini bukan sitekey frontend dan tidak dapat digunakan untuk merender widget. Sitekey uji frontend akan disediakan kemudian.
- Token yang diawali
pt_test_dicadangkan untuk pengujian dan selalu ditolak oleh aplikasi sungguhan (valid: false,error: "token_invalid").
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 |
token_invalid | /v1/validate: token tidak valid untuk aplikasi ini (mis. test token pt_test_ yang dikirim ke aplikasi sungguhan). |
test_always_fail | /v1/validate: dikembalikan oleh test key yang selalu gagal. |
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. |
action_mismatch | /v1/validate: expected_action diatur dan token milik action lain. |
hostname_mismatch | /v1/validate: expected_hostname diatur dan token diselesaikan pada hostname / package yang berbeda (atau tidak diketahui). |
service_online | Request masuk ke layanan fallback offline padahal API utama sedang online. Gunakan https://apiv1.captcha.la — lihat Endpoint fallback offline. |