reCAPTCHA v2 Enterprise'ı Node.js ile Nasıl Çözebilirim?

Enterprise v2 ile standart v2 arasındaki fark, kodunuzda tek bir satırdır: CaptchaAI'ye gönderdiğiniz isteğe enterprise=1 parametresini eklersiniz. Geri kalan akış — sitekey'i bulmak, görevi göndermek, sonucu sorgulamak, token'ı forma koymak — birebir aynı kalır. Bu yazı o dört adımı Node.js tarafında, kopyalayıp çalıştırabileceğiniz kodla anlatır.

Karışıklığın büyük bölümü, geliştiricinin sayfadaki widget'a bakıp "bu normal v2" demesinden çıkar. Görsel olarak ikisi aynıdır: aynı onay kutusu, aynı "Ben robot değilim" metni. Ayrım ağ trafiğindedir ve yanlış tahmin ettiğinizde CaptchaAI size geçerli bir token döndürse bile hedef site onu kabul etmez.

Acele ediyorsanız akışın tamamı dört satırda şudur:

1. Anchor URL'sinden sitekey'i, varsa action değerini çıkarın.
2. Görevi in.php uç noktasına enterprise=1 ile gönderin.
3. res.php'yi sorgulayıp token'ı ve user_agent değerini alın.
4. Token'ı g-recaptcha-response alanına koyup formu aynı User-Agent ile gönderin.

enterprise=1 pratikte neyi değiştirir?

Enterprise sürümü, Google'ın risk puanlama altyapısını devreye alır ve token'ı standart v2'ye göre daha sıkı doğrular. Sizin tarafınızda bunun üç somut sonucu vardır:

• İstek parametresi değişir. method=userrecaptcha aynı kalır, yanına enterprise=1 gelir.
• action değeri önem kazanır. Anchor URL'sinde sa= varsa aynı değeri göndermeniz gerekir; göndermezseniz token doğrulamada düşer.
• User-Agent tutarlılığı zorunlu hale gelir. Token'ı çözen tarafın User-Agent'ı ile formu gönderen isteğin User-Agent'ı uyuşmalıdır.

Farkı tek bakışta görmek isterseniz:

Token alanının adı iki sürümde de aynıdır; bu yüzden entegrasyonun form tarafını değiştirmeniz gerekmez. Değişen tek şey görevi nasıl gönderdiğinizdir.

Başlamadan önce elinizde olması gerekenler

Adım 1: Enterprise v2'yi ağ trafiğinden ayırt edin

DevTools'u açın ve Network sekmesinde anchor isteğini filtreleyin. Enterprise sürümünde istek şuna benzer:

https://www.google.com/recaptcha/enterprise/anchor?ar=1&k=6LdxxXXxAAAAAAcX...&sa=LOGIN&...

Bakmanız gereken üç işaret:

• Script kaynağı /recaptcha/enterprise.js ya da /enterprise/anchor içerir
• k= parametresi sitekey'dir
• sa= parametresi (varsa) action değeridir

Standart v2 ise /recaptcha/api2/anchor üzerinden yüklenir. Bu durumda enterprise=1 eklemeyin. Ayrımdan emin olamadığınız sayfalarda Enterprise uygulamasını tespit etme rehberi kriterleri tek tek gösterir.

Adım 2: Görevi CaptchaAI'ye gönderin

in.php uç noktasına json=1 ile istek gönderin; yanıttaki request alanı görev kimliğidir. action yalnızca anchor URL'sinde varsa eklenmelidir:

const API_KEY = "YOUR_API_KEY";

async function submitTask(sitekey, pageurl, action) {
  const params = new URLSearchParams({
    key: API_KEY,
    method: "userrecaptcha",
    googlekey: sitekey,
    pageurl: pageurl,
    enterprise: "1",
    json: "1",
  });

  if (action) {
    params.set("action", action);
  }

  const response = await fetch(
    `https://ocr.captchaai.com/in.php?${params}`
  );
  const data = await response.json();

  if (data.status !== 1) {
    throw new Error(`Submit failed: ${data.request}`);
  }

  console.log(`Task submitted. ID: ${data.request}`);
  return data.request;
}

API anahtarınızı kaynak koda gömmeyin; process.env.CAPTCHAAI_KEY gibi bir ortam değişkeninden okuyun. Paylaşılan otomasyon repolarında en sık düşülen hata budur.

Adım 3: Sonucu sorgulayın

Enterprise v2 çözümleri anında dönmez. İlk sorgulamadan önce 20 saniye bekleyin, sonra 5 saniyelik aralıklarla res.php uç noktasını sorgulayın. CAPCHA_NOT_READY yanıtı "henüz hazır değil" demektir ve hata sayılmaz; bunun dışındaki her yanıt döngüyü kırmalıdır:

function delay(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

async function pollResult(taskId) {
  await delay(20000);

  for (let attempt = 0; attempt < 30; attempt++) {
    const params = new URLSearchParams({
      key: API_KEY,
      action: "get",
      id: taskId,
      json: "1",
    });

    const response = await fetch(
      `https://ocr.captchaai.com/res.php?${params}`
    );
    const data = await response.json();

    if (data.status === 1) {
      console.log(`Solved. Token: ${data.request.substring(0, 60)}...`);
      return {
        token: data.request,
        userAgent: data.user_agent || "",
      };
    }

    if (data.request !== "CAPCHA_NOT_READY") {
      throw new Error(`Solve failed: ${data.request}`);
    }

    console.log(`Attempt ${attempt + 1}: not ready, waiting 5s...`);
    await delay(5000);
  }

  throw new Error("Solve timed out");
}

Yanıttaki user_agent alanını bir kenara atmayın — bir sonraki adımda ihtiyacınız olacak.

Adım 4: Token'ı forma ekleyin

Çözülen token, g-recaptcha-response alanı olarak gönderilir. API bir user_agent döndürdüyse aynı değeri istek başlıklarınıza koyun:

async function submitForm(token, userAgent) {
  const headers = { "Content-Type": "application/x-www-form-urlencoded" };

  if (userAgent) {
    headers["User-Agent"] = userAgent;
  }

  const response = await fetch("https://example.com/api/login", {
    method: "POST",
    headers,
    body: new URLSearchParams({
      username: "user",
      password: "pass",
      "g-recaptcha-response": token,
    }),
  });

  console.log(`Response status: ${response.status}`);
  return response;
}

Tarayıcı otomasyonu içinde çalışıyorsanız aynı token'ı document.getElementById('g-recaptcha-response').innerHTML alanına yazıp formu sayfa üzerinden gönderebilirsiniz; mantık değişmez, yalnızca gönderim katmanı değişir.

Uçtan uca çalışan script

Aşağıdaki dosyayı olduğu gibi kaydedip node solve.js ile çalıştırabilirsiniz. SITE_KEY, PAGE_URL ve ACTION değerlerini kendi test ortamınıza göre değiştirmeniz yeterli:

const API_KEY = "YOUR_API_KEY";
const SITE_KEY = "6LdxxXXxAAAAAAcXxxXxxX91xxxxxxxx8xxOx7A";
const PAGE_URL = "https://staging.example.com/qa-login";
const ACTION = "LOGIN"; // optional — omit if not in anchor URL

function delay(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

async function solveRecaptchaV2Enterprise() {
  // Submit task
  const submitParams = new URLSearchParams({
    key: API_KEY,
    method: "userrecaptcha",
    googlekey: SITE_KEY,
    pageurl: PAGE_URL,
    enterprise: "1",
    action: ACTION,
    json: "1",
  });

  const submitRes = await fetch(
    `https://ocr.captchaai.com/in.php?${submitParams}`
  );
  const submitData = await submitRes.json();

  if (submitData.status !== 1) {
    throw new Error(`Submit error: ${submitData.request}`);
  }

  const taskId = submitData.request;
  console.log(`Task ID: ${taskId}`);

  // Poll for result
  await delay(20000);

  for (let i = 0; i < 30; i++) {
    const pollParams = new URLSearchParams({
      key: API_KEY,
      action: "get",
      id: taskId,
      json: "1",
    });

    const pollRes = await fetch(
      `https://ocr.captchaai.com/res.php?${pollParams}`
    );
    const pollData = await pollRes.json();

    if (pollData.status === 1) {
      return {
        token: pollData.request,
        userAgent: pollData.user_agent || "",
      };
    }

    if (pollData.request !== "CAPCHA_NOT_READY") {
      throw new Error(`Solve error: ${pollData.request}`);
    }

    await delay(5000);
  }

  throw new Error("Solve timed out");
}

(async () => {
  const { token, userAgent } = await solveRecaptchaV2Enterprise();
  console.log(`Token: ${token.substring(0, 60)}...`);
  if (userAgent) console.log(`User-Agent: ${userAgent}`);
})();

Beklenen çıktı:

Task ID: 73849562810
Token: 03AGdBq24PBCqLmOx2V4pGHJjkR2xZ1r...
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)...

Yerel senaryo: ödeme adımı QA otomasyonu

Türkiye'deki otomasyon geliştiricilerinin büyük bölümü e-ticaret ve fintech entegrasyonlarıyla uğraşır ve tipik ihtiyaç şudur: staging ortamındaki bir üyelik veya satın alma akışını her gece uçtan uca test etmek, ama akışın ortasındaki Enterprise v2 doğrulaması yüzünden testin takılmaması. Bu senaryoda CaptchaAI, test koşucunuzun içinde bir yardımcı fonksiyondur: beforeEach bloğu token'ı üretir, test formu doldurur, senaryo sonuna kadar akar.

Eşzamanlılık planlamasını buna göre yapın. CaptchaAI faturalaması thread bazlıdır: aynı anda kaç çözümün havada olabileceğini planınız belirler, çözüm başına ücret alınmaz.

• Gece çalışan 5 paralel senaryo için BASIC ($15/ay, 5 thread) yeterlidir.
• 40–50 paralel işin olduğu bir CI matrisinde ADVANCE ($90/ay, 50 thread) daha gerçekçi bir tercihtir.
• Fiyatlar USD'dir; aylık tutarın sabit kalması, kur dalgalanmasıyla bütçe planlayan ekipler için pratik bir avantaj sağlar.

Bir de veri tarafı var: test verilerinizde gerçek müşteri kaydı kullanıyorsanız bu, KVKK kapsamına giren kişisel veridir. Staging ortamlarında +90 biçiminde üretilmiş sahte numaralar ve tr-TR locale'iyle oluşturulmuş anonim kayıtlar kullanın; Europe/Istanbul saat dilimini test konteynerinize sabitleyin ki zaman damgasına bağlı doğrulamalar tutarlı çalışsın.

Sorun giderme

Enterprise'a özgü uç durumların tamamı için yaygın Enterprise v2 hataları listesine bakabilirsiniz.

SSS

Standart v2 için de enterprise=1 gönderebilir miyim?

Hayır, göndermeyin. Parametre yalnızca anchor URL'si /recaptcha/enterprise/ üzerinden yükleniyorsa anlamlıdır. Standart v2'de eklemek gereksiz başarısızlıklara yol açar.

Node.js sürümümde yerleşik fetch yoksa ne yapmalıyım?

Node.js 18 öncesinde npm install node-fetch kurup dosyanın başında içe aktarın. Kodun geri kalanında değişiklik gerekmez; aynı akış axios ile de birebir çalışır.

Aynı anda kaç Enterprise görevi gönderebilirim?

Planınızdaki thread sayısı kadar. Bir thread, o an havada olan bir çözümü temsil eder; çözüm bittiği anda sıradaki görevi alır. BASIC ($15/ay) 5 thread, STANDARD ($30/ay) 15 thread ile gelir ve thread başına çözüm sayısı sınırsızdır.

Token geçerli görünüyor ama site reddediyor, neden?

En sık sebep User-Agent uyumsuzluğudur: Enterprise v2 token'ları çözümü yapan tarafın User-Agent'ına bağlıdır. Sorgulama yanıtında dönen user_agent değerini, formu gönderdiğiniz istekte de kullanın. İkinci sık sebep, anchor URL'sinde sa= olmasına rağmen action göndermemektir.

CaptchaAI hCaptcha'yı da destekliyor mu?

Hayır. hCaptcha ve FunCaptcha şu an desteklenmiyor; GeeTest v4 için yalnızca "çok yakında" durumu geçerli. Buna karşılık reCAPTCHA v2/v3/Enterprise, Cloudflare Turnstile ve GeeTest v3 destekleniyor; CaptchaFox (beta), Friendly Captcha (beta) ve Lemin (beta) ise beta aşamasındadır.

Hemen başlayın

Hesabınızı captchaai.com üzerinden açın, API anahtarınızı kopyalayın ve v2 isteğinize enterprise=1 ekleyin. İlk token'ı üretmeniz birkaç dakika sürer.

İlgili rehberler

• Enterprise v2'yi doğrudan API ile çözme
• Aynı akışın Python karşılığı
• Yaygın Enterprise v2 hataları ve düzeltmeleri
• reCAPTCHA Enterprise uygulamasını tespit etme