Standart ve Enterprise reCAPTCHA v3 çözüm rehberi

Aynı kod bir sitede çalışıp diğerinde sürekli reddedilen token üretiyorsa fark genellikle tek bir parametrededir: enterprise=1. CaptchaAI tarafında standart reCAPTCHA v3 ile reCAPTCHA Enterprise v3 arasındaki bütün entegrasyon farkı budur — görev gönderimi, sorgulama ve token'ı forma yerleştirme adımları birebir aynı kalır. Asıl iş kodlamada değil tespitte: her iki sürüm de görünmez çalışır, sayfada tıklanacak bir onay kutusu bırakmaz ve HTML'e bakmadan hangisinin çalıştığını anlayamazsınız.

Enterprise v3 neyi değiştirir, neyi değiştirmez

Enterprise, Google tarafında sebep kodları, eyleme özel eşikler ve Google Cloud proje yönetimi ekler. Bu özelliklerin tamamı sitenin arka ucunu ilgilendirir; sizin gönderdiğiniz göreve yansıyan tek şey bayraktır. Çözüm tarafında tablo neredeyse aynıdır.

Türkiye'den bir senaryo: ödeme akışı regresyon testleri

Türkiye'deki ekiplerin en sık karşılaştığı durum şu: bir e-ticaret projesinde giriş ve ödeme adımlarının otomatik regresyon testleri aylardır sorunsuz koşuyor, sonra sağlayıcı hiçbir duyuru yapmadan Enterprise'a geçiyor. Test paketi bir gecede kırmızıya dönüyor, log'da yalnızca düşük puan görünüyor. Bu yüzden sürümü ortam değişkenine sabitlemek yerine her koşuda tespit etmek çok daha dayanıklıdır.

İki pratik not: test verilerinde +90 telefon formatı ve tr-TR locale kullanmak akışı gerçekçi tutar; KVKK kapsamında ise yalnızca kendi sisteminizde, yetkili olduğunuz ortamlarda test edin — üretimdeki gerçek müşteri kayıtlarıyla değil, staging üzerinde üretilmiş sahte kayıtlarla çalışın.

Sayfanın hangi sürümü kullandığını tespit etme

Görünür bir widget olmadığı için tespit tamamen JavaScript'e bakar: enterprise.js varsa Enterprise, render= parametreli api.js varsa standart v3. Aynı istekte sitekey'i ve eylem dizesini de çıkarın.

Python ile tespit:

import requests
import re

def detect_v3_type(url):
    resp = requests.get(url)
    html = resp.text

    # Check for enterprise.js
    if "enterprise.js" in html:
        version = "enterprise_v3"
        execute_fn = "grecaptcha.enterprise.execute"
    elif "recaptcha/api.js" in html and "render=" in html:
        version = "standard_v3"
        execute_fn = "grecaptcha.execute"
    else:
        return None

    # Extract sitekey from render parameter
    key_match = re.search(r'render[=:]\s*["\']?([A-Za-z0-9_-]{40})', html)
    sitekey = key_match.group(1) if key_match else None

    # Extract action parameter
    action_match = re.search(r'action["\']?\s*[:=]\s*["\'](\w+)', html)
    action = action_match.group(1) if action_match else "unknown"

    return {
        "version": version,
        "sitekey": sitekey,
        "action": action,
        "execute_fn": execute_fn
    }

info = detect_v3_type("https://staging.example.com/qa-login")
print(info)

Node.js ile tespit:

const axios = require("axios");

async function detectV3Type(url) {
  const { data: html } = await axios.get(url);

  let version, executeFn;
  if (html.includes("enterprise.js")) {
    version = "enterprise_v3";
    executeFn = "grecaptcha.enterprise.execute";
  } else if (html.includes("recaptcha/api.js") && html.includes("render=")) {
    version = "standard_v3";
    executeFn = "grecaptcha.execute";
  } else {
    return null;
  }

  const keyMatch = html.match(/render[=:]\s*['"]?([A-Za-z0-9_-]{40})/);
  const actionMatch = html.match(/action['"]?\s*[:=]\s*['"](\w+)/);

  return {
    version,
    sitekey: keyMatch?.[1] || null,
    action: actionMatch?.[1] || "unknown",
    executeFn,
  };
}

Tarayıcı konsolunda hızlı kontrol:

// Paste in DevTools console
if (document.querySelector('script[src*="enterprise.js"]')) {
  console.log("Enterprise v3");
  console.log("Execute:", typeof grecaptcha?.enterprise?.execute);
} else if (document.querySelector('script[src*="api.js"][src*="render="]')) {
  console.log("Standard v3");
  console.log("Execute:", typeof grecaptcha?.execute);
}

CaptchaAI ile token alma

Standart v3

import requests
import time

# Submit
resp = requests.get("https://ocr.captchaai.com/in.php", params={
    "key": "YOUR_API_KEY",
    "method": "userrecaptcha",
    "version": "v3",
    "googlekey": sitekey,
    "action": "login",
    "pageurl": page_url
})
task_id = resp.text.split("|")[1]

# Poll
for _ in range(60):
    time.sleep(5)
    result = requests.get("https://ocr.captchaai.com/res.php", params={
        "key": "YOUR_API_KEY", "action": "get", "id": task_id
    })
    if result.text.startswith("OK|"):
        token = result.text.split("|")[1]
        break

Enterprise v3

import requests
import time

# Submit — add enterprise=1
resp = requests.get("https://ocr.captchaai.com/in.php", params={
    "key": "YOUR_API_KEY",
    "method": "userrecaptcha",
    "version": "v3",
    "enterprise": 1,  # Required for Enterprise
    "googlekey": sitekey,
    "action": "login",
    "pageurl": page_url
})
task_id = resp.text.split("|")[1]

# Polling is identical to standard
for _ in range(60):
    time.sleep(5)
    result = requests.get("https://ocr.captchaai.com/res.php", params={
        "key": "YOUR_API_KEY", "action": "get", "id": task_id
    })
    if result.text.startswith("OK|"):
        token = result.text.split("|")[1]
        break

Tespit ve çözümü birleştiren tek sınıf

Üretimde en çok işe yarayan yaklaşım, tespiti ve gönderimi tek yerde toplamaktır: sayfayı çekin, enterprise.js var mı bakın, bayrağı ona göre ekleyin.

import requests
import time
import re

class RecaptchaV3Solver:
    def __init__(self, api_key):
        self.api_key = api_key

    def detect_and_solve(self, page_url, action=None):
        """Auto-detect standard vs enterprise and solve."""
        html = requests.get(page_url).text

        is_enterprise = "enterprise.js" in html
        key_match = re.search(r'render[=:]\s*["\']?([A-Za-z0-9_-]{40})', html)
        if not key_match:
            raise Exception("No v3 sitekey found")
        sitekey = key_match.group(1)

        if not action:
            action_match = re.search(r'action["\']?\s*[:=]\s*["\'](\w+)', html)
            action = action_match.group(1) if action_match else "verify"

        params = {
            "key": self.api_key,
            "method": "userrecaptcha",
            "version": "v3",
            "googlekey": sitekey,
            "action": action,
            "pageurl": page_url
        }
        if is_enterprise:
            params["enterprise"] = 1

        resp = requests.get("https://ocr.captchaai.com/in.php", params=params)
        if not resp.text.startswith("OK|"):
            raise Exception(f"Submit failed: {resp.text}")

        task_id = resp.text.split("|")[1]
        for _ in range(60):
            time.sleep(5)
            result = requests.get("https://ocr.captchaai.com/res.php", params={
                "key": self.api_key, "action": "get", "id": task_id
            })
            if result.text.startswith("OK|"):
                return result.text.split("|")[1]
            if result.text != "CAPCHA_NOT_READY":
                raise Exception(f"Solve failed: {result.text}")

        raise Exception("Timed out")

solver = RecaptchaV3Solver("YOUR_API_KEY")
token = solver.detect_and_solve("https://staging.example.com/qa-login", action="login")
print(f"Token: {token[:40]}...")

action parametresini sayfadan çıkarma

action her iki sürüm için de kritiktir. Yanlış eylem gönderirseniz puan düşer ve token doğrulamada reddedilebilir. Değeri tahmin etmek yerine sayfa kaynağından okuyun:

import re

def find_v3_actions(html):
    """Extract all action parameters from page JavaScript."""
    # Look for grecaptcha.execute(key, {action: '...'})
    pattern = r"(?:grecaptcha\.(?:enterprise\.)?execute|action)\s*[(:]\s*['\"](\w+)"
    actions = re.findall(pattern, html)
    return list(set(actions))

# Common actions: "login", "submit", "register", "checkout", "homepage"

Token'ı forma yerleştirme

• Tarayıcı tabanlı akış: alanı doldurun, ardından formu sayfanın kendi gönderim fonksiyonuyla gönderin.
• Saf HTTP akışı: token'ı diğer form alanlarıyla birlikte POST edin.

İki sürüm arasında burada hiçbir fark yoktur; alan adı her ikisinde de g-recaptcha-response'tur.

# For browser-based workflows (Selenium)
driver.execute_script(
    f'document.getElementById("g-recaptcha-response").value = "{token}";'
)

# For pure HTTP workflows
requests.post(page_url, data={
    "g-recaptcha-response": token,
    "username": "user",
    "password": "pass"
})

// Puppeteer
await page.evaluate((tok) => {
  document.getElementById("g-recaptcha-response").value = tok;
}, token);

// Pure HTTP (axios)
await axios.post(pageUrl, new URLSearchParams({
  "g-recaptcha-response": token,
  username: "user",
  password: "pass",
}));

Sık yapılan hatalar

Sık sorulan sorular

Enterprise v3'ü kod içinden nasıl algılarım?

Sayfa kaynağında enterprise.js aramak yeterlidir; Selenium kullanıyorsanız tek satır:

page_source = driver.page_source
is_enterprise = "enterprise.js" in page_source

Bir sayfada hem v2 hem v3 varsa hangi sitekey'i göndermeliyim?

Çözmek istediğiniz doğrulamaya ait olanı. v3 sitekey'i render= parametresinin içinde durur, v2 sitekey'i ise data-sitekey özniteliğinde. İkisini karıştırmak doğrudan ERROR_WRONG_GOOGLEKEY üretir.

Token geçerli görünüyor ama puan sürekli düşük geliyor, sorun nerede?

Genellikle action uyuşmazlığında ya da token'ın geç kullanılmasında. Token'ı aldıktan sonra iki dakika içinde kullanın ve sayfanın beklediği eylem dizesini birebir gönderin.

Plan seçerken thread sayısını neye göre belirlemeliyim?

Eşzamanlı çözüm sayınıza göre; CaptchaAI thread bazlı faturalandırır ve her planda thread başına çözüm sınırsızdır. Tek bir test paketi koşturuyorsanız BASIC ($15/ay, 5 thread) yeterli olur, paralel koşan CI job'ları varsa eşzamanlılığı ölçüp bir üst plana geçin.

Test ve üretim ortamında aynı entegrasyonu kullanabilir miyim?

Evet, ancak sitekey'ler farklıdır ve sürüm de farklı olabilir. Tespiti her iki ortamda da çalıştırın; staging standart v3 kullanırken üretimin Enterprise'a geçmiş olması sık görülen bir durumdur.

İlgili kılavuzlar

• reCAPTCHA v3 Enterprise ve standart karşılaştırması — aynı konuya farklı bir açıdan bakış
• Tüm reCAPTCHA sürümlerini kapsayan Enterprise karşılaştırması — v2 ve v3 birlikte
• Standart reCAPTCHA v3'ü API ile çözme — adım adım eğitim
• reCAPTCHA v3 Enterprise'ı API ile çözme — Enterprise akışının tamamı
• reCAPTCHA v3 action parametresi — eylem parametresinin ayrıntılı incelemesi