Rujukan API

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

URL Asas API

https://apiv1.captcha.la

Hanya satu URL asas

Semua endpoint pada halaman ini berada di apiv1.captcha.la. Hos sandaran (bypass.*, fallbackapiv1.*) ialah sasaran failover yang dihubungi SDK dengan sendirinya semasa gangguan — menghalakan integrasi anda ke situ akan memulangkan service_online.

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
• 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.

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.

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

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.

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

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.

Endpoint sandaran luar talian

CaptchaLa mengekalkan perkhidmatan sandaran pada hos berasingan supaya pengesahan terus berfungsi apabila API utama tidak dapat dicapai:

Hos	Dipanggil oleh	Tujuan
bypass.captchala.com · bypass.captcha-cdn.net	SDK web / native (sebelah pengguna akhir)	Menjalankan pengesahan luar talian dan mengeluarkan pass token offline_ semasa API utama tumbang
fallbackapiv1.captchala.com · fallbackapiv1.captcha-cdn.net	SDK pelayan	Mengesahkan token offline_ (POST /api/validate)

Ini sasaran failover, bukan API alternatif. SDK bertukar ke situ dengan sendirinya, hanya selepas API utama benar-benar gagal, dan kembali semula sebaik ia pulih. Tiada apa dalam konfigurasi anda patut menghala ke hos ini.

service_online (HTTP 503)

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

Ralat ini muncul semasa API utama masih hidup: perkhidmatan sandaran hanya beroperasi ketika berlaku gangguan. Permintaan sampai ke bypass.* dan bukan ke https://apiv1.captcha.la — betulkan URL, mencuba semula tidak membantu.

Punca biasa:

Punca	Penyelesaian
Pilihan SDK apiServer ditetapkan ke hos bypass	Tetapkan semula kepada https://apiv1.captcha.la, atau buang pilihan itu dan biar SDK memilih
bypassServers ditulis ganti secara manual	Buang tulis ganti tersebut melainkan kami memberi anda hos khusus
Klien HTTP sendiri menyalin URL bypass (cth. dari devtools semasa insiden)	Panggil https://apiv1.captcha.la dan serahkan failover kepada SDK — perkhidmatan sandaran tidak menerima trafik cabaran biasa
Pengimbang beban / proksi / DNS menulis semula hos API	Halakan upstream kembali ke apiv1.captcha.la

TIP

Pengesahan sisi pelayan juga tidak memerlukan hos sandaran: POST /v1/validate pada apiv1.captcha.la sudah memadai, dan SDK pelayan PHP / Go mengendalikan token offline_ melalui API sandaran secara automatik.

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.
service_online	Permintaan sampai ke perkhidmatan sandaran luar talian sedangkan API utama dalam talian. Gunakan https://apiv1.captcha.la — lihat Endpoint sandaran luar talian.