Rujukan API

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

URL Asas API

https://apiv1.captcha.la

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

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

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.

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.