Güvenli kapsam: Bu rehber yalnızca size ait veya açıkça yetkilendirilmiş QA, staging ve ön üretim ortamları içindir. Ele aldığı konu, kendi CAPTCHA entegrasyonlarınızın tanılanması, test edilmesi ve gözlemlenebilirliğidir — üçüncü taraf siteler veya yetkisiz akışlar kapsam dışıdır.
Kendi uygulamanızın kayıt, giriş ve ödeme adımlarını uçtan uca test ederken çoğu zaman tek bir CAPTCHA değil, her adımda ayrı bir doğrulama çıkar. Bu rehber, o adımları kendi staging ortamınızda CaptchaAI ile nasıl güvenle zincirleyeceğinizi ve her çalıştırmayı tekrarlanabilir tutacağınızı gösterir. Kısa cevap: her adıma bir kimlik verin, CAPTCHA'yı yalnızca widget gerçekten göründüğünde çözün ve token'ı adım kimliğine bağlayarak izleyin.
Çok adımlı bir QA akışı neye benzer?
Türkiye'deki geliştirici pazarı ağırlıklı olarak e-ticaret ve fintech entegrasyonlarına yaslanır; bu yüzden en sık test edilen senaryo genellikle bir satın alma akışının tamamıdır. Tipik bir örnek şöyledir: kullanıcı kaydı → e-posta doğrulaması → ödeme adımı. Bu adımların birden fazlasında reCAPTCHA v2 veya Cloudflare Turnstile devreye girebilir ve her biri bağımsız bir doğrulama üretir.
Amaç, bu zinciri kendi staging kopyanızda gerçekçi biçimde çalıştırmaktır. Test verilerini sentetik tutun: tr-TR yerel ayarı, Europe/Istanbul saat dilimi ve +90 formatında sahte telefon numaraları kod örneklerinizi yerelleştirir. Gerçek kişisel veri kullanmayın — kazınan veya test edilen kişisel veriler KVKK kapsamına girer, bu yüzden yalnızca kendi ürettiğiniz kayıtlarla çalışın.
CAPTCHA'yı yalnızca gerektiğinde çözün
Her adıma iki bilgi iliştirin: hangi senaryoya ait olduğunu belirten bir qa_kasasi ve adımın kendi adim_id değeri. Bu ikisi, sonrasında izlemeyi ve idempotency'yi mümkün kılan anahtarlardır.
En önemli tasarım kararı şudur: CaptchaAI'yi körlemesine her adımda çağırmayın. Önce sayfada bir CAPTCHA widget'ının gerçekten oluşup oluşmadığını kontrol edin; yalnızca göründüğünde çözüm isteği gönderin. Bir ödeme akışında CAPTCHA çoğu zaman yalnızca son adımda çıkar — gereksiz çağrıları elemek hem thread kullanımınızı düşürür hem de testin gerçek kullanıcı davranışına daha yakın kalmasını sağlar. CaptchaAI'nin planları thread bazlıdır (BASIC $15/ay, 5 thread'den başlar), yani eşzamanlı açık CAPTCHA sayısına göre ölçeklenir; boşa çağrı yapmamak doğrudan verimlilik demektir.
Her adımı idempotent tutun
Çok adımlı bir testte asıl kırılganlık, ağ hatası veya zaman aşımı sonrası yeniden denemelerdedir. Bir adım yarıda kalırsa, tüm zinciri baştan çalıştırmak yerine aynı adim_id ile yeniden deneyin. Token hâlâ geçerlilik süresi içindeyse tekrar kullanılabilir; süresi dolmuşsa yalnızca o adım için yeni bir çözüm istenir.
Yeniden deneme stratejinizi üstel geri çekilme (exponential backoff) üzerine kurun: örneğin 1s, 2s, 4s aralıklarıyla ve bir üst sınırla. Ağ hataları, 5xx yanıtları ve geçici ERROR_NO_SLOT_AVAILABLE durumları için yeniden deneme uygundur; kalıcı kimlik doğrulama hataları içinse değildir — onlarda hızlıca durup nedeni raporlayın. reCAPTCHA v2 için token'ı doğru alanı doldurarak nasıl enjekte edeceğinizi reCAPTCHA v2'yi API ile çözme rehberinde, Turnstile için ise Cloudflare Turnstile'ı API ile çözme rehberinde bulabilirsiniz.
Örnek: staging akışında bir CAPTCHA adımını test etmek
Aşağıdaki Python örneği, kendi staging ortamınızdaki bir reCAPTCHA v2 widget'ını CaptchaAI üzerinden test eden minimal akışı gösterir. Görevi gönderip görev kimliğini alır, ardından sonucu ayrı bir çağrıyla sorgular. İlk API çağrınızı henüz yapmadıysanız, önce CaptchaAI hızlı başlangıç rehberiyle anahtarınızı doğrulayın.
import os
import requests
API_KEY = os.environ['CAPTCHAAI_KEY']
QA_PAGE_URL = os.environ['QA_PAGE_URL'] # ör. https://staging.example.com/qa-login
QA_SITE_KEY = os.environ['QA_SITE_KEY']
def submit_qa_recaptcha() -> str:
payload = {
'clientKey': API_KEY,
'task': {
'type': 'NoCaptchaTaskProxyless',
'websiteURL': QA_PAGE_URL,
'websiteKey': QA_SITE_KEY,
},
}
response = requests.post(
'https://api.captchaai.com/createTask',
json=payload,
timeout=30,
)
response.raise_for_status()
return response.json()['taskId']
def fetch_qa_result(task_id: str) -> dict:
payload = {'clientKey': API_KEY, 'taskId': task_id}
response = requests.post(
'https://api.captchaai.com/getTaskResult',
json=payload,
timeout=30,
)
response.raise_for_status()
return response.json()
Aynı desen reCAPTCHA v2, Cloudflare Turnstile ve GeeTest v3 gibi desteklenen türler için de geçerlidir; yalnızca görev tipini ve site anahtarı alanını ilgili türe göre değiştirirsiniz.
Gözlemlenebilirlik ve korelasyon
Her QA çalıştırması için yapılandırılmış (structured) günlükler üretin. Toplam token süresi, HTTP yanıt kodu, görev kimliği ve kuyruk derinliği gibi ölçümler panolarınızı ve uyarılarınızı besler. Ortamları — geliştirme, staging, ön üretim — ayrı kanallara yazın ve dağıtık izleme (örneğin OpenTelemetry) ile bağıntı kimliklerini (correlation id) eşleştirin. Her adımın qa_kasasi ve adim_id değerini bu kimliklere bağlarsanız, tek bir kimlikten tüm senaryoyu yeniden oynatabilirsiniz. Bu tek başına, bir olay sırasında tanılama süresini gözle görülür biçimde kısaltır: hangi adımda hangi token'ın reddedildiğini aramak yerine doğrudan görürsünüz.
Sık karşılaşılan sorunlar
| Sorun | Önerilen çözüm |
|---|---|
| Test CAPTCHA widget'ını bulamıyor | Staging ortamınızdaki seçiciyi ve sayfanın yüklenme zamanlamasını kontrol edin |
CaptchaAI ERROR_NO_SLOT_AVAILABLE döndürüyor |
Geçici bir durumdur; üstel geri çekilme ile yeniden deneyin |
| Backend, QA token'ını reddediyor | sitekey ve action değerlerini gerçek yapılandırmayla karşılaştırın |
| Token geçerli ama adım başarısız | Token'ın doğru alana enjekte edildiğini ve süresinin dolmadığını doğrulayın |
Yayına almadan önce kontrol listesi
- Kapsam kesinlikle kendi uygulamalarınız veya yetkilendirilmiş kaynaklarla sınırlı.
- CaptchaAI anahtarı CI gizli deposunda veya kasada tutuluyor, kaynak koda asla işlenmiyor.
- Her çalıştırma için çağrı süresi ve yanıt kodu kayıt altına alınıyor.
- Geçici hatalar için idempotent yeniden deneme stratejisi kurulu.
- Testler sürekli entegrasyon ortamından tekrarlanabilir biçimde yeniden oynatılabiliyor.
- Test verisi tamamen sentetik; gerçek kişisel veri kullanılmıyor (KVKK).
Sık sorulan sorular
Çok adımlı bir akışta CAPTCHA'yı her adımda mı çözmeliyim?
Hayır. CaptchaAI'yi yalnızca ilgili adımda bir widget gerçekten oluştuğunda çağırın. Çoğu ödeme veya kayıt akışında doğrulama tek bir adımda çıkar; gereksiz çağrılar hem yavaşlatır hem thread harcar.
Aynı token'ı sonraki adımlarda tekrar kullanabilir miyim?
Token'lar tek bir doğrulama adımı içindir ve kısa ömürlüdür. Yarıda kalan bir adımı aynı adim_id ile yeniden denerken token hâlâ geçerliyse kullanabilirsiniz; farklı bir adım için her zaman yeni bir çözüm isteyin.
Bu akışta hangi CAPTCHA türlerini test edebilirim?
reCAPTCHA v2 ve v3, Cloudflare Turnstile ile GeeTest v3 gibi desteklenen türleri aynı desenle test edebilirsiniz. hCaptcha ve FunCaptcha desteklenmez; GeeTest v4 için destek yalnızca "çok yakında" aşamasındadır.
QA testleri için hangi plan yeterli?
Planlar thread bazlıdır ve eşzamanlı açık CAPTCHA sayısına göre ölçeklenir. Çoğu QA senaryosu için BASIC ($15/ay, 5 thread) başlangıç noktasıdır; USD sabit aylık fiyat, kur dalgalanmasından etkilenmediği için bütçelenmesi kolaydır.
ERROR_NO_SLOT_AVAILABLE alırsam ne yapmalıyım?
Bu geçici bir doluluk durumudur. Üstel geri çekilme ile yeniden deneyin; sürekli tekrarlıyorsa eşzamanlı çağrı sayınızı thread limitinizin altına çekin.
İlgili rehberler
- Yetkili ortamlarda CAPTCHA QA testleri
- Kendi formlarınızda CAPTCHA endpoint testleri
- Tarayıcı testi başarısız ama API başarılı: hata ayıklama
CAPTCHA entegrasyonunuzu kendi ortamınızda CaptchaAI ile doğrulayın.
