Scarnox · Blog

PopularCaptcha Python ile nasıl çözülür (çalışan örnek, 2026)

Python betiğiniz bir PopularCaptcha ile karşılaştıysa, bir tarayıcı çiftliğine ya da kendi modelinize ihtiyacınız yok. Sayfanın sitekey'ine, bir POST isteğine ve geri dönen token'a ihtiyacınız var.

Bu rehber sizi yaklaşık beş dakikada çalışan bir token'a götürür: bir API anahtarı alın, sitekey'i bulun, token isteyin, formda gönderin ve betik denetimsiz çalışmaya başladığında çıkan hata durumlarını ele alın. Başarısız çözümler ücretsizdir; yeniden denemenin maliyeti yalnızca zamandır.

Scarnox bugün PopularCaptcha'yı proxysiz veya kendi proxy'nizle çözer. reCAPTCHA, Cloudflare Turnstile ve AWS WAF gibi diğer captcha tipleri yakında geliyor; bu yüzden buradaki her örnek PopularCaptcha kullanır. Diğerlerinin nasıl farklı olduğunu captcha tipleri genel bakışı açıklar.

1. Bir API anahtarı alın

Hesap oluşturun ve ücretsiz deneme kredisiyle başlayın; kart gerekmez. API anahtarınız kontrol panelinizdedir. Anahtarı kaynak kodunuza koymayın, bir ortam değişkeninden okuyun:

export SCARNOX_KEY="scarnox_YOURAPIKEY"

2. Sitekey'i bulun

Captcha'lı sayfayı açın, DevTools'u açın ve Elements panelinde data-sitekey araması yapın. PopularCaptcha sitekey'leri UUID'lerdir:

<div class="h-captcha" data-sitekey="10000000-ffff-ffff-ffff-000000000001"></div>

HTML'de data-sitekey yok mu? Widget muhtemelen JavaScript ile render edilmiştir. Network sekmesinde widget'ın yapılandırma isteğine bakın; onun sitekey sorgu parametresi ihtiyacınız olan değerdir. iframe URL'si ve görünmez widget'lar dahil diğer yollar için sitekey'i bulmanın yolları sayfasına bakın.

Widget'ı gösteren sayfanın URL'sini site_url olarak gönderin. En önemli kısım host'tur, ama tam sayfa URL'si güvenli seçimdir.

3. Bir token isteyin

import os
import requests

API_URL = "https://api.scarnox.com/api/tasks/create"
API_KEY = os.environ["SCARNOX_KEY"]

def solve_captcha(sitekey: str, page_url: str) -> str:
    r = requests.post(
        API_URL,
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={
            "captcha_type": "PopularCaptchaTaskProxyless",
            "site_key": sitekey,
            "site_url": page_url,
        },
        timeout=185,  # çağrı token hazır olana kadar bloklar
    )
    data = r.json()
    if data.get("errorId") != 0:
        raise RuntimeError(f"{data.get('errorCode')}: {data.get('errorDescription')}")
    return data["solution"]["token"]

if __name__ == "__main__":
    token = solve_captcha("10000000-ffff-ffff-ffff-000000000001", "https://example.com/signup")
    print(token[:40], "...")

Entegrasyonun tamamı budur. Yoklama döngüsü yoktur ve ikinci bir "sonucu al" çağrısı yoktur. İstek token hazır olduğunda döner; bu yüzden tek önemli ayar yavaş bir çözümü kapsayacak kadar uzun bir zaman aşımıdır. Yaklaşık 185 saniye kullanın.

Başarılı bir yanıtta errorId değeri 0'dır ve token solution.token altındadır. Başka bir errorId, çözümün başarısız olduğu anlamına gelir; yanıt nedenini söyleyen bir errorCode ve bir errorDescription içerir.

4. Token'ı gönderin

Token, sitenin captcha yanıtını beklediği yere gider. PopularCaptcha için bu neredeyse her zaman h-captcha-response adlı bir form alanıdır. Birçok site g-recaptcha-response alanını da kabul eder, bu yüzden ikisini de gönderin:

import requests

def sign_up(session: requests.Session, form_url: str, email: str, sitekey: str) -> requests.Response:
    token = solve_captcha(sitekey, form_url)
    return session.post(form_url, data={
        "email": email,
        "h-captcha-response": token,
        "g-recaptcha-response": token,
    }, timeout=30)

Burada iki ayrıntı önemlidir. Gerçek siteler genellikle sayfa yüklemesinden gelen oturum çerezlerini de kontrol eder; bu yüzden göndermeden önce formu aynı requests.Session ile yükleyin. Ayrıca, gönderimi formun action URL'sine yapın; bu her zaman sayfa URL'si değildir.

Göndermeden hemen önce çözün. Token yaklaşık iki dakika içinde sona erer; uzun bir işin başında alıp elinizde tutmayın. Site token'ı reddediyorsa, formu DevTools'ta açın ve gizli alan adlarını doğrulayın.

5. Hataları ele alın

Başarısız çözümler ücretsizdir; yeniden denemenin maliyeti yalnızca zamandır. Yine de bazı hatalar yeniden denemeyle asla düzelmez, bu yüzden körü körüne döngüye girmeyin. Her seferinde errorId değerini kontrol edin, errorCode ve errorDescription değerlerini loglayın ve yalnızca geçici hataları yeniden deneyin.

Ağ hataları ayrı ele alınmalıdır, çünkü requests bir yanıt oluşmadan önce fırlatır:

import requests

try:
    token = solve_captcha(sitekey, page_url)
except requests.RequestException as exc:
    print("ağ sorunu, sonra tekrar deneyin:", exc)
except RuntimeError as exc:
    print("çözüm reddedildi:", exc)

Geri çekilme ve jitter içeren tam bir yeniden deneme politikası için hata yönetimi rehberine bakın.

Yaygın hatalar

Ücretsiz deneyin

Hesap oluşturun ve ücretsiz deneme kredisiyle başlayın; kart gerekmez. Daha büyük bir işe bağlamadan önce yukarıdaki örneği kendi sahip olduğunuz bir formda çalıştırın. Hacimde çözümün maliyeti için güncel fiyatlandırmaya bakın.

Her çözümü loglamak

Her çözüm için bir satır loglayın: sitekey, sayfa host'u, errorId, hata durumunda errorCode ve çağrının ne kadar sürdüğü. API anahtarını ve bir proxy şifresini loglara yazmayın. Bu satırlar, yavaş bir çalıştırmanın sayfadan, proxy'den mi yoksa çözücüden mi kaynaklandığını söyler. Bir destek talebi açacağınızda da ilk ihtiyacınız olacak bilgi bunlardır.

Döngüde çözmek

Betiğiniz arka arkaya çok sayıda captcha çözüyorsa, döngüyü basit tutun. Çöz, gönder, sonucu kontrol et ve ancak ondan sonra ilerle. Önceden çözüp token'ları kuyruğa koymayın; her biri yaklaşık iki dakika içinde sona erer. Aynı sitede çözümler arasında kısa bir duraklama, isteklerinizin hızını bir insanın üreteceğine yakın tutar.

Sonraki adımlar