Hızlı başlangıç

Bu kılavuz, CaptchaLa CAPTCHA'yı 5 dakikada entegre etmenize yardımcı olur.

30 saniyede çalışırken görün

demo-v1.captcha.la — saf HTML + PHP, MIT lisanslı, her sayfada view-source açıktır.

• popup.html — açılır pencere modu
• float.html — kayan widget
• bind.html — butona bağla
• inline.html — satır içi gömme
• server-token.html — sunucu tarafından düzenlenen token (yeniden oynatma engelleme)

1. Hesap Oluşturun

Panelden ücretsiz bir hesap oluşturun

Şimdi Kaydolun →

2. Uygulama Oluşturun

App Key'inizi almak için panelde bir uygulama oluşturun

3. SDK'yı Kurun

Tercih ettiğiniz kurulum yöntemini seçin

<!-- CDN loader (recommended): auto-fallback CDN, ~6 KB gzip -->
<script src="https://cdn.captcha-cdn.net/captchala-loader.js"></script>

# or via npm
npm install captchala

4. CAPTCHA'yı Başlatın

Sayfanızda CAPTCHA bileşenini başlatın

<button id="login-btn">Sign in</button>

<script>
loadCaptchala(function () {
  Captchala.init({
    appKey: 'YOUR_APP_KEY',
    product: 'bind',          // popup | float | bind | embed
    action: 'login',
    lang: 'auto',
  })
  .onSuccess(function (res) {
    // res.token starts with pt_ — POST it to your backend
    submitLogin(res.token);
  })
  .onError(function (err) { console.error(err.message); })
  .bindTo('#login-btn');     // popup/bind use bindTo; float/embed use appendTo
});
</script>

5. Sunucu Doğrulaması

Token'ı sunucunuzda doğrulayın

POST https://apiv1.captcha.la/v1/validate
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "pass_token": "<from onSuccess>", "client_ip": "<end-user IP>" }

{
  "code": 0,
  "data": {
    "valid": true,
    "action": "login",
    "challenge_id": "ch_xxx",
    "uid": null,
    "client_ip": "1.2.3.4",
    "risk_score": 12
  }
}

WARNING

Her zaman data.valid === true olduğunu ve data.action değerinin beklediğiniz senaryoyla eşleştiğini kontrol edin. Pass token'lar tek kullanımlıktır; aynı pt_xxx iki kez doğrulanamaz.

Sunucu Tarafından Düzenlenen Token Modu (üretim için önerilir)

Hassas işlemler (giriş, kayıt, ödeme) için sunucu tarafından düzenlenen token akışını öneririz: backend'iniz önce kısa ömürlü bir server_token ister, ardından tarayıcı bu token'ı kullanarak CAPTCHA'yı başlatır. Bu, sızdırılmış bir app_key'in kötüye kullanımını önler.

Ne zaman kullanılmalı

• Önerilen: kayıt, giriş, parola sıfırlama, ödeme, puan kullanımı ve bir saldırganın script ile çağırabileceği tüm uç noktalar.
• İsteğe bağlı: genel formlar, arama kutuları ve kolaylığın daha önemli olduğu düşük değerli etkileşimler.

1. Backend server_token düzenler

/v1/server/challenge/issue uç noktasını kendi sunucunuzdan, X-App-Key ve X-App-Secret başlıklarıyla çağırın. Bu başlıkları asla tarayıcıya açmayın.

# Server-side only — never call this from a browser
curl -X POST https://apiv1.captcha.la/v1/server/challenge/issue \
  -H "X-App-Key: YOUR_APP_KEY" \
  -H "X-App-Secret: YOUR_APP_SECRET" \
  -d "action=login&ttl=300&max_uses=1&bind_ip=1.2.3.4"

# → { "code": 0, "data": { "server_token": "sct_...", "expires_in": 300 } }

2. Frontend, server_token ile CaptchaLa'yı render eder

Token'ı CaptchaLa bileşeninize iletin. SDK, challenge başlatılırken bunu challenge başlatma çağrısına aktarır.

// Browser fetches the token from YOUR backend, not from CaptchaLa directly
const { serverToken } = await fetch('/api/captcha/issue').then(r => r.json());

Captchala.init({
  appKey: 'YOUR_APP_KEY',
  serverToken,             // single-use, short-lived
  product: 'popup',
  action: 'login',
})
.appendTo('#captcha-container')
.onSuccess(res => submitForm(res.token));

Güvenlik notları

• app_secret'i asla frontend koduna, mobil uygulamalara veya açık depolara koymayın. Sunucu tarafında kalmalıdır.
• Panelde "Sunucu tarafından düzenlenen challenge token'ı zorunlu kıl" seçeneğini etkinleştirerek server_token olmadan denenen tüm challenge'ları reddedin.
• ttl değerini kısa tutun (varsayılan 300 sn, maksimum 900 sn) ve token sızıntısının etkisini azaltmak için max_uses=1 değerini tercih edin.

Sonraki adımlar

• Web SDK
• API Referansı