API Referansı

CaptchaLa, tüm sunucu tarafı entegrasyonlar için RESTful API sağlar.

Temel URL

https://apiv1.captcha.la

Kimlik Doğrulama

Tüm API istekleri kimlik doğrulama başlıkları gerektirir:

X-App-Key:    YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET

WARNING

X-App-Secret yalnızca sunucu tarafıdır. Asla tarayıcılara, mobil uygulamalara veya genel depolara açmayın.

Sunucu Tarafı Doğrulama API'si

💡 Standart kodu atlamak için bir sunucu SDK'sı kullanın. Uç noktayı sarar, yeniden denemeleri yönetir, tipli hataları yüzeye çıkarır:

• PHP — Captcha-La/captchala-php (中文)
• Go — go get github.com/Captcha-La/captchala-go · README

Kullanıcı frontend CAPTCHA'yı geçtikten sonra sunucunuzun, SDK tarafından döndürülen token'ı doğrulaması gerekir. Aşağıda sunucu tarafı doğrulama uç noktaları yer alır.

Sunucu Tarafı Token Doğrulama

Frontend SDK'dan gelen pass_token'ı (pt_ ön ekli) doğrular. X-App-Key ve X-App-Secret başlıklarını gerektirir.

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

data.valid === true olduğunu ve data.action değerinin beklediğiniz senaryoyla eşleştiğini doğrulayın (bir pay akışına ait token /login adresinde sunulursa reddedin). Token'lar tek kullanımlıktır.

Sunucu Tarafından Düzenlenen Challenge Token'ı

Backend'inizden kısa ömürlü bir server_token düzenleyin. Tarayıcı, bir challenge başlatırken bu token'ı ileterek isteğin güvenilir sunucunuzdan kaynaklandığını kanıtlar.

Sunucu Token'ı Düzenle

Bu uç noktayı yalnızca kendi sunucunuzdan çağırın. X-App-Key + X-App-Secret gerektirir. Yanıt, frontend'in challenge başlatma çağrısına ileteceği bir server_token (sct_ ön ekli) içerir.

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

Gövde Parametreleri (form-urlencoded)

Alan	Açıklama
action	İş senaryosu, örn. login, register, pay. Challenge başlatmada kullanılan action ile eşleşmelidir.
ttl	Token'ın saniye cinsinden ömrü. Varsayılan 300, maksimum 900.
max_uses	Token'ın tüketilebileceği maksimum sayı. Varsayılan 10.
bind_ip	Token'ı bir istemci IP'sine bağlar. Başka bir IP'den başlatma reddedilir.
bind_device_id	Token'ı belirli bir cihaz id'sine bağlar.
bind_fingerprint	Token'ı belirli bir tarayıcı parmak izine bağlar.

Challenge Başlat

CAPTCHA challenge'ı başlatmak için SDK tarafından çağrılır. /v1/server/challenge/issue tarafından düzenlenen isteğe bağlı bir server_token kabul eder.

Alan	Açıklama
app_key	Genel App Key'iniz.
action	İş senaryosu. server_token düzenlenirken kullanılan action ile eşleşmelidir.
server_token	İsteğe bağlı; uygulamada server_token_required = true olduğunda gereklidir.

INFO

Bu uygulama için panelde server_token_required etkinleştirilmişse, challenge başlatma geçerli bir server_token taşımayan istekleri reddeder.

Hata Kodları

Kod	Açıklama
invalid_app_key	Geçersiz App Key
invalid_app_secret	Geçersiz App Secret
challenge_expired	Challenge süresi doldu
challenge_not_found	Challenge bulunamadı
invalid_answer	Geçersiz yanıt
token_expired	Token süresi doldu
token_already_used	Token zaten kullanıldı
token_not_found	Token bulunamadı
quota_exceeded	Kota aşıldı
rate_limited	Hız sınırına ulaşıldı
rate_limit_exceeded	Bu uygulama için çok fazla düzenleme isteği. Geri çekilip yeniden deneyin.