API Referansı

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

Temel URL

https://apiv1.captcha.la

Tek bir temel URL

Bu sayfadaki tüm uç noktalar apiv1.captcha.la üzerindedir. Yedek ana makineler (bypass.*, fallbackapiv1.*), kesinti sırasında SDK'ların kendiliğinden yöneldiği devralma hedefleridir — entegrasyonunuzu oraya yöneltirseniz service_online döner.

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.

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 isteğe bağlıdır ancak önerilir — gelen isteğinizdeki son kullanıcının IP'si, ek risk kontrolleri için kullanılır; atlanması güvenlidir.

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

captcha_args bilgilendirme amaçlı verilerdir (günlükleme / risk kullanımınız için): platform, user_ip (çözüm anındaki IP), referer, pkg, solved_at, risk_score.

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.

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

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.

Çevrimdışı yedek uç noktalar

CaptchaLa, ana API'ye ulaşılamadığında doğrulamanın sürmesi için ayrı ana makinelerde bir yedek servis çalıştırır:

Ana makine	Çağıran	Amaç
`bypass.captchala.com` · `bypass.captcha-cdn.net`	Web / native SDK (son kullanıcı tarafı)	Ana API kapalıyken çevrimdışı doğrulamayı yapar ve `offline_` pass token üretir
`fallbackapiv1.captchala.com` · `fallbackapiv1.captcha-cdn.net`	Sunucu SDK'ları	`offline_` token'larını doğrular (`POST /api/validate`)

Bunlar devralma hedefidir, alternatif bir API değildir. SDK'lar yalnızca ana API gerçekten başarısız olduktan sonra kendiliğinden buraya geçer ve ana API toparlanınca geri döner. Kendi yapılandırmanızdaki hiçbir şey bu adresleri göstermemelidir.

`service_online` (HTTP 503)

json

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

Ana API ayaktayken bu hatayı alırsınız: yedek servis yalnızca kesinti sırasında trafik kabul eder. İstek https://apiv1.captcha.la yerine bypass.* adresine gitmiştir — URL'yi düzeltin, yeniden denemek işe yaramaz.

Sık görülen nedenler:

Neden	Çözüm
SDK `apiServer` seçeneği bir bypass adresine ayarlı	`https://apiv1.captcha.la` yapın ya da seçeneği kaldırıp sunucuyu SDK seçsin
`bypassServers` elle geçersiz kılınmış	Size özel adresler vermediysek bu geçersiz kılmayı kaldırın
Kendi HTTP istemciniz bypass URL'sini kopyalamış (ör. olay sırasında devtools'tan)	`https://apiv1.captcha.la` çağırın, devralmayı SDK'ya bırakın — yedek servis normal challenge trafiğini kabul etmez
Yük dengeleyici / proxy / DNS API adresini yeniden yazıyor	Upstream'i yeniden `apiv1.captcha.la` yapın

TIP

Sunucu tarafı doğrulama da yedek adrese ihtiyaç duymaz: apiv1.captcha.la üzerinde POST /v1/validate yeterlidir; offline_ token'larını PHP / Go sunucu SDK'ları yedek API üzerinden otomatik doğrular.

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.
`service_online`	Ana API çalışırken istek çevrimdışı yedek servise ulaştı. Bunun yerine `https://apiv1.captcha.la` kullanın — bkz. Çevrimdışı yedek uç noktalar.

API Referansı ​

Temel URL ​

Kimlik Doğrulama ​

Sunucu Tarafı Doğrulama API'si ​

Sunucu Tarafı Token Doğrulama ​

Sunucu Tarafından Düzenlenen Challenge Token'ı ​

Sunucu Token'ı Düzenle ​

Gövde Parametreleri (form-urlencoded) ​

Challenge Başlat ​

Çevrimdışı yedek uç noktalar ​

service_online (HTTP 503) ​

Hata Kodları ​

API Referansı

Temel URL

Kimlik Doğrulama

Sunucu Tarafı Doğrulama API'si

Sunucu Tarafı Token Doğrulama

Sunucu Tarafından Düzenlenen Challenge Token'ı

Sunucu Token'ı Düzenle

Gövde Parametreleri (form-urlencoded)

Challenge Başlat

Çevrimdışı yedek uç noktalar

`service_online` (HTTP 503)

Hata Kodları