reCAPTCHA Enterprise Assessment API'si: puan nedenleri ve otomasyon

Bir sayfanın kaynağında recaptcha/enterprise.js görüyorsanız, otomasyon tarafında değişen tek şey vardır: çözücü isteğine enterprise=1 eklemeniz gerekir. Token biçimi de, sayfaya geri yazdığınız g-recaptcha-response alanı da aynı kalır. Farkın tamamı sunucu tarafındadır: Google, site operatörüne düz bir puan yerine nedenleri, hesap sinyallerini ve WAF kancalarını döndürür.

reCAPTCHA Enterprise ile standart sürüm arasındaki fark

Tablodaki satırların çoğu site operatörünün işine yarar. Otomasyon tarafında tek önemli satır puanlamadır: puan aralığı değişmediği için token üretimi de değişmez.

Assessment API akışı: istemciden sunucuya

Client-side:

  1. Load reCAPTCHA Enterprise script
  2. Call grecaptcha.enterprise.execute(SITE_KEY, {action: 'LOGIN'})
  3. Receive token
  4. Send token to your backend

Server-side:

  1. Create assessment via Enterprise API
  2. Receive detailed risk analysis
  3. Make access decision based on score + reasons
  4. Optionally annotate the assessment (report fraud/legitimate)

İlk dört adım tarayıcıda, kalan dördü sitenin arka ucunda geçer; ikinci yarının çıktısını hiçbir zaman görmezsiniz.

İstemci tarafı: enterprise.js entegrasyonu

JavaScript SDK

<script src="https://www.google.com/recaptcha/enterprise.js?render=SITE_KEY"></script>
<script>
    grecaptcha.enterprise.ready(function() {
        grecaptcha.enterprise.execute('SITE_KEY', { action: 'LOGIN' })
            .then(function(token) {
                // Send token to backend
                fetch('/api/verify', {
                    method: 'POST',
                    headers: { 'Content-Type': 'application/json' },
                    body: JSON.stringify({ token: token })
                });
            });
    });
</script>

Standart reCAPTCHA v3'e göre üç fark:

• Script URL'si .../recaptcha/api.js yerine .../recaptcha/enterprise.js
• API nesnesi grecaptcha değil, grecaptcha.enterprise
• execute() aynı token biçimini döndürür; entegrasyon mantığınız değişmez

Sayfa kaynağından Enterprise tespiti

Sayfanın HTML'ini çekip sitekey ile action adlarını birlikte çıkarmak daha güvenilir:

import requests
import re

def detect_recaptcha_enterprise(url):
    """Detect if a page uses reCAPTCHA Enterprise."""
    html = requests.get(url, timeout=10).text

    indicators = {
        "is_enterprise": False,
        "is_standard": False,
        "site_key": None,
        "actions": [],
    }

    # Enterprise detection
    if "recaptcha/enterprise.js" in html:
        indicators["is_enterprise"] = True
        match = re.search(r"render=([A-Za-z0-9_-]+)", html)
        if match:
            indicators["site_key"] = match.group(1)

    # Standard v3 detection
    elif "recaptcha/api.js?render=" in html:
        indicators["is_standard"] = True
        match = re.search(r"render=([A-Za-z0-9_-]+)", html)
        if match:
            indicators["site_key"] = match.group(1)

    # Extract action names
    actions = re.findall(r"action:\s*['\"](\w+)['\"]", html)
    indicators["actions"] = list(set(actions))

    return indicators

print(detect_recaptcha_enterprise("https://staging.example.com/qa-login"))

action adları önemlidir: Enterprise puanı beklenen eylemle birlikte değerlendirir.

Sunucu tarafında değerlendirme oluşturma

Kendi sitenizi Enterprise ile koruyorsanız Google Cloud istemcisi token'ı, sitekey'i ve beklenen eylemi tek istekte birleştirir:

from google.cloud import recaptchaenterprise_v1
from google.cloud.recaptchaenterprise_v1 import Assessment

def create_assessment(project_id, site_key, token, action):
    """Create a reCAPTCHA Enterprise assessment."""
    client = recaptchaenterprise_v1.RecaptchaEnterpriseServiceClient()

    event = recaptchaenterprise_v1.Event()
    event.site_key = site_key
    event.token = token
    event.expected_action = action

    assessment = recaptchaenterprise_v1.Assessment()
    assessment.event = event

    request = recaptchaenterprise_v1.CreateAssessmentRequest()
    request.assessment = assessment
    request.parent = f"projects/{project_id}"

    response = client.create_assessment(request)
    return response

Assessment yanıtında ne var?

{
    "name": "projects/123456/assessments/abcdef123",
    "event": {
        "token": "...",
        "siteKey": "6Le...",
        "expectedAction": "LOGIN",
        "hashedAccountId": "abc123..."
    },
    "riskAnalysis": {
        "score": 0.9,
        "reasons": [
            "AUTOMATION",
            "TOO_MUCH_TRAFFIC"
        ],
        "extendedVerdictReasons": [
            "BROWSER_ERROR"
        ]
    },
    "tokenProperties": {
        "valid": true,
        "hostname": "example.com",
        "action": "LOGIN",
        "createTime": "2025-01-15T10:30:00Z",
        "invalidReason": ""
    },
    "accountDefenderAssessment": {
        "labels": ["PROFILE_MATCH"]
    }
}

• riskAnalysis — puanın kendisi ve puanı düşüren nedenler.
• tokenProperties — token'ın geçerliliği. Üretimde ilk bakacağınız alan burasıdır: tokenProperties.valid false ise puanı tartışmanın anlamı yoktur.
• accountDefenderAssessment — hesaba ait davranış etiketleri.

Account Defender: hesap yaşam döngüsü sinyalleri

Account Defender tek bir isteği değil, hesabın zaman içindeki davranışını izler:

{
    "accountDefenderAssessment": {
        "labels": [
            "PROFILE_MATCH",
            "SUSPICIOUS_LOGIN_ACTIVITY",
            "SUSPICIOUS_ACCOUNT_CREATION",
            "RELATED_ACCOUNTS_NUMBER_HIGH"
        ]
    }
}

• PROFILE_MATCH — davranış, bu hesap için bilinen profille uyuşuyor.
• SUSPICIOUS_LOGIN_ACTIVITY — oturum açma düzeni normalden farklı: yeni cihaz, yeni konum.
• SUSPICIOUS_ACCOUNT_CREATION — hesap oluşturma akışı otomatik görünüyor.
• RELATED_ACCOUNTS_NUMBER_HIGH — aynı cihaza veya oturuma çok sayıda hesap bağlı.

WAF katmanında Enterprise

Enterprise, doğrulamayı ağ ucuna taşımak için WAF sağlayıcılarıyla entegre olur.

Cloudflare WAF

Request arrives at Cloudflare edge
    ↓
Cloudflare WAF rule evaluates request
    ↓
Rule triggers reCAPTCHA Enterprise challenge
    ↓
Client solves CAPTCHA → token returned
    ↓
Cloudflare validates token via Enterprise API
    ↓
If valid + score above threshold → request forwarded to origin

F5 BIG-IP

F5 iRule or policy evaluates request
    ↓
Triggers reCAPTCHA Enterprise challenge page
    ↓
Client solves → token validated server-side
    ↓
F5 forwards or blocks based on assessment score

Yani doğrulama sayfası, uygulamanın login formundan önce gelebilir. Token ürettiğiniz hâlde sayfa hâlâ doğrulama istiyorsa sorun genellikle uçtaki kuraldadır.

Puan nedenlerini okumak

Enterprise'ın standart sürümden asıl farkı burada: puanın neden düştüğünü söyleyen alan.

Genişletilmiş karar nedenleri

Bu nedenleri yalnızca site operatörü görür: kendi ödeme akışınızı test ediyorsanız liste bir sorun giderme aracıdır, üçüncü taraf bir sitede yalnızca sonucu gözlemlersiniz.

Otomasyon tarafı: enterprise=1 ile token alma

Enterprise token'ları standart reCAPTCHA token'larıyla aynı şekilde çalışır; tek fark göreve enterprise=1 eklemenizdir:

import requests
import time

API_KEY = "YOUR_API_KEY"

# Enterprise is solved with the same method
# The solver handles the Enterprise variant automatically
submit = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": API_KEY,
    "method": "userrecaptcha",
    "googlekey": "6LcR_RsTAAAAAN_r0GEkGBfq3L7KmU5JbPHJtwNp",
    "pageurl": "https://enterprise-site.com/login",
    "enterprise": 1,  # Flag for Enterprise variant
    "json": 1,
})

task_id = submit.json()["request"]

for _ in range(60):
    time.sleep(5)
    result = requests.get("https://ocr.captchaai.com/res.php", params={
        "key": API_KEY,
        "action": "get",
        "id": task_id,
        "json": 1,
    }).json()

    if result.get("status") == 1:
        token = result["request"]
        print(f"Enterprise token: {token[:50]}...")
        break

Node.js

const axios = require("axios");

async function solveEnterprise(sitekey, pageurl) {
    const API_KEY = "YOUR_API_KEY";

    const { data: submit } = await axios.post(
        "https://ocr.captchaai.com/in.php",
        new URLSearchParams({
            key: API_KEY,
            method: "userrecaptcha",
            googlekey: sitekey,
            pageurl: pageurl,
            enterprise: 1,
            json: 1,
        })
    );

    const taskId = submit.request;

    for (let i = 0; i < 60; i++) {
        await new Promise(r => setTimeout(r, 5000));
        const { data: result } = await axios.get(
            "https://ocr.captchaai.com/res.php",
            { params: { key: API_KEY, action: "get", id: taskId, json: 1 } }
        );

        if (result.status === 1) return result.request;
    }

    throw new Error("Timeout");
}

Türkiye'den somut bir senaryo: İstanbul'daki bir e-ticaret ekibi kendi ödeme adımını Enterprise ile koruyor, gece regresyonlarını Europe/Istanbul saatine göre planlıyor. Test kullanıcısı tr-TR locale ve +90 biçiminde sahte telefon verisiyle üretiliyor. İki nokta önemli: test verisi gerçek müşteri kayıtlarından türetilmemeli (KVKK kapsamına girer) ve testler yalnızca ekibin kendi yetkili ortamında koşmalı.

CaptchaAI thread bazlı ücretlendirir: plan içindeki çözüm sayısı sınırsızdır, CAPTCHA türüne göre ek ücret yoktur. Tek bir gece paketi için BASIC ($15/ay, 5 thread) genelde yeterlidir; test matrisi paralelleştikçe STANDARD ($30/ay, 15 thread) veya ADVANCE ($90/ay, 50 thread) devreye girer. Fiyatlar USD'dir ve kur dalgalansa da aylık gider sabit kalır — Türkiye'deki ekipler için bütçe planlamasında gerçek bir avantaj.

Sürümü kod ile ayırt etme

Boru hattınıza koyabileceğiniz en küçük kontrol, HTML'e bakıp sürümü döndüren bir yardımcı fonksiyondur:

def identify_recaptcha_version(html):
    """Determine which reCAPTCHA version a page uses."""
    if "recaptcha/enterprise.js" in html:
        return "enterprise"
    elif "recaptcha/api.js?render=" in html:
        return "v3"
    elif "g-recaptcha" in html and 'data-size="invisible"' in html:
        return "v2_invisible"
    elif "g-recaptcha" in html:
        return "v2"
    else:
        return "none"

Sorun giderme

• Token, Enterprise API tarafından reddediliyor. Enterprise bir site için standart yöntem kullanılmıştır; çözücü isteğine enterprise=1 ekleyin.
• Token geçerli ama puan sürekli 0,1. action değeri uyuşmuyordur; gönderdiğiniz değerin sayfanınkiyle aynı olduğunu doğrulayın.
• Nedenlerde SITE_MISMATCH var. Token yanlış alan adı için üretilmiştir; pageurl değerinin hedefle birebir eşleştiğinden emin olun.
• Nedenlerde AUTOMATION var. Çözüm ortamı algılanmıştır; CaptchaAI bunu kendi tarafında yönetir, sürerse desteğe yazın.
• Token geçerli, site yine de engelliyor. Site CAPTCHA dışında ek kontroller uyguluyordur; WAF kurallarını ve diğer bot algılama katmanlarını kontrol edin.

Sık sorulan sorular

enterprise=1 göndermezsem ne olur?

Görev standart reCAPTCHA olarak işlenir ve dönen token çoğu zaman reddedilir. Belirti "token geçersiz" değil, "doğrulama tamamlanamadı" biçiminde görünür; ilk bakılacak yer bu bayraktır.

Enterprise token'ı ne kadar süre geçerli kalır?

reCAPTCHA token'larının ömrü iki dakikadır, Enterprise bunu değiştirmez. Formu 120 saniye içinde gönderin; uzun kuyruklarda token'ı gönderimden hemen önce üretin.

Enterprise için ayrı bir CaptchaAI planı gerekiyor mu?

Hayır. Planlar thread sayısına göre belirlenir; BASIC ($15/ay, 5 thread) ile de Enterprise görevleri gönderebilirsiniz. Değişen tek şey eşzamanlı görev kapasitenizdir.

action parametresi neden bu kadar önemli?

Enterprise puanı beklenen eylemle birlikte değerlendirir. Sayfa LOGIN gönderirken siz SUBMIT gönderirseniz token geçerli olsa bile puan düşer. Değeri sayfa kaynağından çıkarın.

Enterprise CAPTCHA çözmek için Google Cloud hesabı gerekir mi?

Hayır. Google Cloud projesi, değerlendirmeyi oluşturan site operatörünün tarafındadır. Size sayfadaki sitekey, doğru pageurl ve CaptchaAI gibi bir API çözücü yeter.

Özet

Enterprise'ın eklediği her şey — risk analizi, puan nedenleri, Account Defender, WAF entegrasyonu — sitenin sunucu tarafında yaşar. Sizin listeniz kısadır: sayfa kaynağında recaptcha/enterprise.js arayın, sitekey ve action değerlerini çıkarın, CaptchaAI isteğine enterprise=1 ekleyin, token'ı iki dakika dolmadan gönderin.

İlgili Makaleler

• reCAPTCHA v2 callback sorununu API ile çözme
• Aynı sayfada reCAPTCHA v2 ve Turnstile'ı birlikte yönetme
• reCAPTCHA v3 Enterprise'ı API ile çözme rehberi