Skip to content

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:

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.

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 bersifat opsional tetapi disarankan — IP pengguna akhir dari request masuk Anda, dipakai untuk pemeriksaan risiko tambahan; aman untuk dihilangkan.

Parameter Request ​

ParameterWajibDeskripsi
pass_tokenYaToken yang dikembalikan oleh SDK frontend
client_ipTidakIP pengguna akhir dari request masuk Anda
keep_tokenTidaktrue = periksa tanpa mengonsumsi token (default false)
expected_actionTidakAction 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_hostnameTidakHostname (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.

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
    },
    "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). null jika tidak diketahui.
  • challenge_ts — waktu challenge diselesaikan, ISO 8601 dalam UTC. null jika 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:

json
{ "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 diselesaikan
  • referer — URL halaman penyelesaian (web); null di native
  • pkg — package / bundle id aplikasi (native); null di web
  • solved_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:

PrefiksDiterbitkan saat/v1/validate mengembalikanPenanganan yang disarankan
pt_Verifikasi lolos secara normalvalid: true (sekali pakai)Terima
dg_Kuota paket habis (mode degraded)valid: false, degraded: true, reasonKeputusan Anda — lihat di bawah
offline_API utama tidak dapat dijangkau; diterbitkan oleh bypass workerDiverifikasi otomatis ke API cadangan saat menggunakan server SDKTerima setelah verifikasi cadangan
co_API utama dan cadangan tidak dapat dijangkau; dibuat di sisi klienTidak dapat diverifikasi di sisi serverTerapkan 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/validate di server Anda mengembalikan:
json
{
  "code": 0,
  "data": {
    "valid": false,
    "degraded": true,
    "reason": "quota_exhausted",
    "expired": false
  }
}

Properti utama:

  • valid selalu false untuk token degraded — aman secara default. Jika kode Anda hanya memeriksa valid, tidak ada yang berubah bagi Anda.
  • Mengizinkan request atau tidak adalah keputusan Anda: terima valid || degraded agar 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) dan result.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.

PerilakuX-App-KeyX-App-Secret
Selalu lolostest_pass_7f3c9a2e5b18d4f6test_secret_pass_c41e8b0d27a95f3e
Selalu gagaltest_fail_2d9e6b4a0c7f1835test_secret_fail_9b5f03e7d1a46c28
  • Selalu lolos — pass_token apa pun yang tidak kosong mengembalikan valid: true. Respons memiliki field yang sama dengan keberhasilan sungguhan, ditambah test: true, sehingga kode parsing Anda ikut teruji:
json
{
  "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_token apa pun yang tidak kosong mengembalikan:
json
{ "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, dan pass_token kosong mengembalikan missing_token, sama seperti aplikasi sungguhan.
  • keep_token, expected_action, dan expected_hostname diabaikan 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.test di 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.

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

Body Parameters (form-urlencoded) ​

FieldDeskripsi
actionScene bisnis, mis. login, register, pay. Harus cocok dengan action yang digunakan di inisialisasi verifikasi.
ttlMasa berlaku token dalam detik. Default 300, maksimum 900.
max_usesMaksimal jumlah token dapat dikonsumsi. Default 10.
bind_ipIkat token ke IP client. Inisialisasi dari IP lain akan ditolak.
bind_device_idIkat token ke device id tertentu.
bind_fingerprintIkat 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.

FieldDeskripsi
app_keyApp Key publik Anda.
actionScene bisnis. Harus cocok dengan action yang digunakan saat menerbitkan server_token.
server_tokenOpsional; 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:

HostDipanggil olehFungsi
bypass.captchala.com · bypass.captcha-cdn.netSDK web / native (sisi pengguna akhir)Menjalankan verifikasi offline dan menerbitkan pass token offline_ selama API utama down
fallbackapiv1.captchala.com · fallbackapiv1.captcha-cdn.netSDK serverMemvalidasi 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) ​

json
{ "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:

PenyebabPerbaikan
Opsi SDK apiServer diarahkan ke host bypassKembalikan ke https://apiv1.captcha.la, atau hapus opsinya dan biarkan SDK memilih
bypassServers ditimpa manualHapus 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 APIArahkan 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 ​

KodeDeskripsi
invalid_app_keyApp Key tidak valid
invalid_app_secretApp Secret tidak valid
challenge_expiredChallenge kedaluwarsa
challenge_not_foundChallenge tidak ditemukan
invalid_answerJawaban tidak valid
token_expiredToken kedaluwarsa
token_already_usedToken sudah digunakan
token_not_foundToken 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_exceededKuota terlampaui
rate_limitedTerkena rate limit
rate_limit_exceededTerlalu 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_onlineRequest masuk ke layanan fallback offline padahal API utama sedang online. Gunakan https://apiv1.captcha.la — lihat Endpoint fallback offline.

MIT-licensed examples · CaptchaLa is operated independently