hCaptcha Nedir? Token, Siteverify ve Enterprise Açıklaması

hCaptcha, bir formun önüne koyduğunuz bir bot denetimidir. Ziyaretçi bir widget içinde challenge’ı geçer, widget da forma h-captcha-response adlı bir token ekler. Sunucunuz o token’ın gerçek olduğunu doğrulamak için onu hCaptcha’ya gönderir. Peki bir geliştirici için hCaptcha nedir? Bir widget, bir token ve tek bir doğrulama çağrısıdır; bir script birini geçmek zorundaysa ilgilendiğiniz de budur. Bu kılavuz onu nasıl tanıyacağınızı, sunucunun neyi denetlediğini, her hatanın ne anlama geldiğini ve bir script’in ne gönderdiğini anlatır.
CAPTCHA’nın genel fikri için bkz. CAPTCHA nedir ve siteler neden kullanır. Bu sayfa hCaptcha konusunda kalır.
Bir sayfada hCaptcha’yı nasıl tanırsınız
hCaptcha geliştirici kılavuzu widget’ı, data-sitekey özniteliği taşıyan ve sınıfı h-captcha olan bir öğe olarak gösterir. CapSkip hCaptcha sayfası sitekey’e herkese açık bir UUID der. Widget’ı bir script kurarsa sitekey, yapılandırma kılavuzunun belgelediği hcaptcha.render() fonksiyonunun bir parametresidir. Kılavuza göre başarılı bir challenge’dan sonra hCaptcha form gönderimine h-captcha-response token’ını ekler.
Yani onu üç şey tanıtır: sınıfı h-captcha olan bir öğe, bir sitekey ve challenge geçildikten sonra h-captcha-response adlı bir form alanı. CapSkip API belgeleri ayrıca bir formun, aynı token ile doldurulacak g-recaptcha-response adlı ikinci bir alan taşıyabileceğini ekler.
Checkbox, invisible ve Enterprise hesapları
Checkbox ve invisible iki widget modudur. Enterprise, ikisini de kullanabilen ve sunucunun doğrulama yanıtının içeriğini değiştiren bir hesap katmanıdır. CapSkip hepsi için tek bir metot kullanır.
- Checkbox. Ziyaretçi bir kutuyu işaretler ve CapSkip belgelerine göre bazen bir resim challenge’ını yanıtlar.
- Invisible. Invisible kılavuzu, öğede data-size değerini invisible yaptığınızı söyler; widget o zaman arka planda render edilir ve yalnızca bir challenge gerektiğinde görünür. Sayfanız onu hcaptcha.execute() ile tetikler ve token callback fonksiyonunuza gider.
- Enterprise. Doğrulama yanıtı, hCaptcha kılavuzunun yalnızca Enterprise için işaretlediği iki alan kazanır: score ve score_reason. CapSkip’te bir görevde score seçeneği yoktur. İlgili tek anahtar, aşağıdaki SSS’de anlatılan hCaptcha için High score mode ayarıdır.
Bazı Enterprise siteleri, widget çalışmadan önce hcaptcha.setData() ile widget’a rqdata adlı bir değer de geçirir. Herkese açık hCaptcha belgeleri onu anlatmaz; bu yüzden buradaki her şey CapSkip belgelerine dayanır: site her challenge için bir değer verir ve bu değer çabuk bayatlar, bu yüzden bir script her görev için yeni bir tane almalıdır.
Sunucu token’la ne yapar
Sunucu token’ı, URL kodlamalı bir form gövdesi olarak https://api.hcaptcha.com/siteverify adresine gönderir; kılavuz JSON göndermemeniz konusunda uyarır. İki alan zorunludur: hesabın gizli anahtarı ve token; bunlar secret ve response olarak gönderilir. Kılavuz remoteip (kullanıcının adresi) alanını önerir ve sitekey’i isteğe bağlı olarak listeler; bu, hangi sitekey’i beklediğinizi belirtmenin bir yoludur. JSON yanıtında success, challenge_ts, hostname ve error-codes bulunur.
Token’lar tek kullanımlıktır. Kılavuzun verdiği tek ömür, bir hata kodunun açıklaması içindeki 120 saniyelik varsayılandır. CapSkip belgeleri bunu yaklaşık iki dakika olarak verir. Token’ı göndermeden hemen önce isteyin.
siteverify hataları ve neyi kontrol etmeli
Bu kodlar hCaptcha kılavuzundaki hata tablosundan gelir. Bir script genellikle yalnızca reddedilmiş bir form görür. Son sütun neyi kontrol edeceğinizin bir okumasıdır, hCaptcha metni değildir.
| Hata kodu | Kılavuz ne diyor | Neyi kontrol etmeli |
|---|---|---|
missing-input-response | Token parametresi eksik. | Form gönderimi h-captcha-response alanını taşımadı ya da site başka bir ad okuyor. |
invalid-input-response | Token geçersiz ya da bozuk. | Değer forma girerken kesildi, düzenlendi ya da iki kez kodlandı. |
expired-input-response | Token’ın süresi dolmuş (varsayılan 120 sn). | Çözme ile gönderme arasında çok uzun süre geçti. Çözün, sonra hemen gönderin. |
already-seen-response | Token zaten bir kez doğrulandı. | Bir token yeniden kullanıldı ya da form gönderimi eski token ile tekrarlandı. Her seferinde yenisini isteyin. |
sitekey-secret-mismatch | Sitekey, verilen secret ile kayıtlı değil. | Sunucu tarafında bir site yapılandırma sorunu; script’in gönderdiği bir şey değil. |
invalid-input-secret | Gizli anahtar geçersiz ya da bozuk. | Bu da sunucu tarafında, site sahibinin kodunda. |
reCAPTCHA ve Turnstile ile karşılaştırması
Üçü de forma tek bir token koyar ve onu sunucu tarafında doğrular; bu yüzden farklar adlarda ve sayılardadır. reCAPTCHA g-recaptcha-response kullanır ve Google doğrulama kılavuzu bir token’ın iki dakika geçerli olduğunu ve bir kez doğrulanabileceğini söyler. Turnstile cf-turnstile-response kullanır ve Cloudflare’ın sunucu tarafı doğrulama kılavuzu 300 saniye ve tek kullanım verir. CapSkip Python SDK’sında çağrılar hcaptcha(), recaptcha() ve turnstile() olup 1.7.0 kaynağından alınmıştır.
CapSkip’e yapılan bir istek nasıl görünür
CapSkip Windows bilgisayarınızda çalışır ve 2captcha istek biçimini konuşur; bu yüzden bir hCaptcha görevi iki HTTP çağrısıdır. Aşağıdaki iki curl.exe komutu da PowerShell’de ve cmd’de yazıldığı gibi çalışır. Birincisi görevi gönderir ve bir iş kimliği döndürür. İkincisi o kimlikle yoklar; CAPCHA_NOT_READY birkaç saniye bekleyip yeniden sormak demektir. data alanını yalnızca sayfa bir rqdata ayarlıyorsa ekleyin. Anahtar yalnızca CapSkip’te API anahtarı doğrulaması açıksa önem taşır.
curl.exe -X POST -d "key=YOUR_API_KEY&method=hcaptcha&sitekey=YOUR_SITEKEY&pageurl=https://example.com/login&json=1" http://127.0.0.1:8080/in.php curl.exe "http://127.0.0.1:8080/res.php?key=YOUR_API_KEY&action=get&id=12345&json=1"
Aynı görev Python SDK ile, görevi gönderen, yoklayan ve sonucu döndüren tek bir çağrıdır. Seçenekler: invisible, data (Enterprise rqdata), userAgent ve proxy. CapSkip, gönderdiğiniz userAgent değerini yalnızca çözümde kullandığı tarayıcıyla eşleşiyorsa kullanır. Sonuç, token’ı code ve token olarak, bir respKey değerini ve token’ı kazandıran User-Agent’ı taşır.
# pip install capskip
from capskip import CapSkip
# The key matters only when API Key Validation is on in CapSkip.
solver = CapSkip(apiKey="YOUR_API_KEY", host="127.0.0.1", port=8080)
# For an Enterprise rqdata add data=RQDATA; for an invisible widget
# add invisible=1. Neither is needed for a plain checkbox.
result = solver.hcaptcha(
sitekey="YOUR_SITEKEY",
url="https://example.com/login",
)
# The token goes in h-captcha-response, sent with this User-Agent.
print(result["code"][:12], result["userAgent"])İki blok da CapSkip’in bir mock’una karşı çalıştı, gerçek uygulamaya karşı değil ve her biri verilen sitekey ve sayfa adresiyle method=hcaptcha gönderdi. Gerçek bir çözüm yapılmadı; bu yüzden burada çözüm süresi ya da başarı oranı hakkında bir iddia yok. Tam scriptler ve her parametre için bkz. CapSkip hCaptcha çözücü sayfası, yöntemin listesi için ise bkz. CapSkip API belgeleri.
- capskip SDK ile Python’da hCaptcha
- Taze bir rqdata ile Node.js’de hCaptcha Enterprise
- C# dilinde HCaptchaAsync ile hCaptcha
CapSkip’i bir sunucuda çalıştırmak
Script’iniz başka bir makinede çalışıyorsa CapSkip’i Server moduna alın ve host ayarını o makineye yönlendirin. Her iki modu da kurulum kılavuzundaki bağlantı ayarları bölümü bunu anlatır. Server modu, CapSkip’in yönetici olarak çalışmasını gerektirir ve makine sizin denetlediğiniz bir Windows bilgisayarı olarak kalır. Hangi adreslerin porta ulaşabildiğini kontrol edin ve ulaşmaması gerekenler için bir Windows Güvenlik Duvarı engelleme kuralı ekleyin. Çözüm o makinede yapıldığı için hCaptcha onun ağını görür; site için önemliyse göreve bir proxy ekleyin.
Sık sorulan sorular
hCaptcha, reCAPTCHA ile aynı mı?
Hayır. Bunlar kendi widget’ları, alan adları ve doğrulama host’ları olan ayrı servislerdir. Bir script doğru alanı göndermeli ve CapSkip’ten doğru metodu istemelidir.
Bir sitenin hCaptcha Enterprise kullandığını nasıl anlarım?
Her zaman ön yüzden anlaşılmaz. CapSkip belgeleri, bazı Enterprise sitelerinin widget çalışmadan önce hcaptcha.setData() ile bir rqdata değeri geçirdiğini söyler. Bu çağrıyı görürseniz değeri data seçeneği olarak, her görev için taze göndererek kullanın. Görmezseniz normal şekilde çözün ve site token’ları reddediyorsa High score mode’u deneyin.
CapSkip’in döndürdüğü token’ı bir form neden reddeder?
CapSkip belgeleri olağan nedenleri sıralar: eski ya da zaten kullanılmış bir token, sayfayla eşleşmeyen bir sitekey ya da yanıttakinden farklı bir User-Agent. Katı siteler için Settings, Captcha types altında hCaptcha için High score mode ayarını da eklerler; bu ayar CapSkip bilgisayarında Google Chrome gerektirir.
CapSkip’i hCaptcha görevleri için bir sunucuda çalıştırabilir miyim?
Evet. Denetlediğiniz bir Windows makinesinde Server modunu kullanın ve script’inizi onun adresine yönlendirin.
Kısa özet
hCaptcha, kendi siteverify adresinde bir kez denetlenen, tek kullanımlık bir token ile biten bir widget’tır. Kendi Windows bilgisayarınızdaki yerel captcha çözücü checkbox, invisible ve Enterprise durumlarının üçünü de tek bir metotla ve çözüm başına ücret olmadan kapsar.
