Node.js ve CaptchaAI ile Resim CAPTCHA'sını Çözme

Node.js tarafında bir resim CAPTCHA'sını çözmek tek bir akışa iner: resmi base64'e çevirip in.php uç noktasına gönderin, dönen görev kimliğini res.php üzerinden sorgulayın, gelen metni forma yazın. Eğitilecek bir OCR modeli, kurulacak ek altyapı ya da tarayıcı eklentisi yok — CaptchaAI resmi okur, siz düz metni alırsınız.

Türkiye'deki otomasyon ekipleri bu tipe en çok eski kurumsal panellerde, bayi giriş ekranlarında ve yıllardır elden geçirilmemiş kayıt formlarında rastlar. Modern reCAPTCHA'ya henüz taşınmamış her form hâlâ klasik bozuk metin resmini gösteriyor; e-ticaret ve fintech tarafında bir QA otomasyonu yazarken bu ekranla karşılaşmamak pek mümkün değil. Aşağıdaki adımlar, o formların testini axios ile kurmanız için gereken minimum çalışan yapıyı veriyor.

Başlamadan önce neye ihtiyacınız var?

API anahtarınızı koda gömmeyin; process.env.CAPTCHAAI_KEY gibi bir ortam değişkeninden okuyun. Örneklerdeki YOUR_API_KEY yer tutucusu yalnızca okunabilirlik için duruyor.

Yöntem A: resmi base64 olarak gönderin

Resim zaten bellekteyse — örneğin Puppeteer ile aldığınız bir ekran görüntüsüyse — en pratik yol base64 gönderimidir. Tek bir POST isteği görevi kuyruğa alır ve size bir görev kimliği döner.

const axios = require('axios');
const fs = require('fs');

const API_KEY = 'YOUR_API_KEY';
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

// Read and encode the image
const imageB64 = fs.readFileSync('captcha.png').toString('base64');

// Submit to CaptchaAI
const { data: submitData } = await axios.post('https://ocr.captchaai.com/in.php', null, {
  params: {
    key: API_KEY,
    method: 'base64',
    body: imageB64,
    json: 1,
  },
});

if (submitData.status !== 1) throw new Error(submitData.request);
const taskId = submitData.request;
console.log(`Task submitted: ${taskId}`);

json: 1 parametresini bırakın: yanıt düz metin yerine JSON döner ve hata ayıklamak belirgin biçimde kolaylaşır.

Yöntem B: dosyayı doğrudan yükleyin

Resim diskte duruyorsa form-data ile multipart yükleme yapabilirsiniz. Bu yöntemde method değeri post olur ve base64 kodlamasının getirdiği yaklaşık üçte bir boyut artışından kurtulursunuz.

const FormData = require('form-data');

const form = new FormData();
form.append('key', API_KEY);
form.append('method', 'post');
form.append('json', '1');
form.append('file', fs.createReadStream('captcha.png'));

const { data: submitData } = await axios.post('https://ocr.captchaai.com/in.php', form, {
  headers: form.getHeaders(),
});

const taskId = submitData.request;

Hangi yöntemi seçmeli?

• Yöntem A (base64): resim zaten bellekte duruyorsa — Puppeteer'dan aldığınız bir ekran görüntüsü, indirilmiş bir buffer ya da başka bir servisten gelen yanıt.
• Yöntem B (multipart): resim diskteyse ya da dosya yolunu bir kuyruk worker'ı devralıyorsa.

Çözüm süresi ikisinde de aynıdır; fark yalnızca istek gövdesinin nasıl paketlendiğidir.

Sonucu sorgulayın ve metni okuyun

Görev gönderildikten sonra sonucu periyodik sorgulama ile alırsınız. İlk sorgudan önce yaklaşık 5 saniye bekleyin, sonra 5 saniyelik aralıklarla res.php uç noktasını çağırın. CAPCHA_NOT_READY yanıtı bir hata değildir — çözümün hâlâ sürdüğünü söyler; bunun dışındaki her yanıt kodu akışı durdurmalıdır.

await sleep(5000);

let captchaText;
for (let i = 0; i < 30; i++) {
  const { data: pollData } = await axios.get('https://ocr.captchaai.com/res.php', {
    params: { key: API_KEY, action: 'get', id: taskId, json: 1 },
  });

  if (pollData.status === 1) {
    captchaText = pollData.request;
    console.log(`CAPTCHA text: ${captchaText}`);
    break;
  }
  if (pollData.request !== 'CAPCHA_NOT_READY') {
    throw new Error(pollData.request);
  }
  await sleep(5000);
}

Döngüyü 30 turla sınırlamak, asılı kalan tek bir görevin worker'ınızı süresiz meşgul etmesini önler. Üretimde bu döngüyü kendi zaman aşımı ve yeniden deneme mantığınızın içine alın.

Doğruluğu artıran parametreler

Resim CAPTCHA'larının çoğunun kendine özgü bir karakter kalıbı vardır: yalnızca rakam, sabit uzunluk, büyük harf duyarlılığı. Bu bilgiyi gönderim sırasında paylaşırsanız, çözümün yanlış karakter içerme ihtimali düşer.

// Digits only, 4-6 characters
const { data } = await axios.post('https://ocr.captchaai.com/in.php', null, {
  params: {
    key: API_KEY,
    method: 'base64',
    body: imageB64,
    numeric: 1,      // digits only
    min_len: 4,       // minimum length
    max_len: 6,       // maximum length
    json: 1,
  },
});

Parametreleri tahminle doldurmayın: form yalnızca rakam beklemiyorsa numeric: 1 göndermek doğru okumayı bozar. Emin olmadığınız bir parametreyi hiç göndermemek, yanlış göndermekten iyidir.

Hedef formu bir kez elle inceleyip bu dört parametreyi doğru ayarlamak, sonradan yazacağınız her türlü ek doğrulama kodundan daha çok iş görür.

Uçtan uca örnek: ekran görüntüsünden gönderilen forma

Aşağıdaki betik adımların tamamını tek dosyada birleştirir: Puppeteer sayfayı açar, CAPTCHA öğesinin ekran görüntüsünü alır, resmi gönderir, metni sorgular ve sonucu forma yazıp gönderir.

const axios = require('axios');
const puppeteer = require('puppeteer');
const fs = require('fs');

const API_KEY = 'YOUR_API_KEY';
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function solveImageCaptcha() {
  // 1. Load page and screenshot CAPTCHA
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com/register');

  const captchaEl = await page.$('#captcha-image');
  await captchaEl.screenshot({ path: 'captcha.png' });

  // 2. Encode and submit
  const imageB64 = fs.readFileSync('captcha.png').toString('base64');
  const { data: submit } = await axios.post('https://ocr.captchaai.com/in.php', null, {
    params: { key: API_KEY, method: 'base64', body: imageB64, json: 1 },
  });
  const taskId = submit.request;

  // 3. Poll for text
  await sleep(5000);
  let text;
  for (let i = 0; i < 30; i++) {
    const { data: poll } = await axios.get('https://ocr.captchaai.com/res.php', {
      params: { key: API_KEY, action: 'get', id: taskId, json: 1 },
    });
    if (poll.status === 1) { text = poll.request; break; }
    if (poll.request !== 'CAPCHA_NOT_READY') throw new Error(poll.request);
    await sleep(5000);
  }

  // 4. Type and submit
  await page.type('#captcha-input', text);
  await page.click('form [type="submit"]');
  console.log(`Solved: ${text}`);
  await browser.close();
}

solveImageCaptcha().catch(console.error);

Beklenen çıktı:

Solved: ABC123

Ekran görüntüsünü CAPTCHA öğesinin tam sınırlarından alın: çerçeveye giren fazladan boşluk veya komşu form etiketleri okuma doğruluğunu düşürür.

Üretime alırken dikkat edilecekler

Tek seferlik bir betik ile gece boyunca çalışan bir QA işi arasındaki fark hata yönetiminde ortaya çıkar. Üç şey neredeyse her kurulumda gerekir:

• Sorgulama döngüsünü bir yeniden deneme katmanıyla sarın; ardışık hatalarda üstel geri çekilme (exponential backoff) uygulayın.
• Her göreve kendi zaman aşımınızı koyun — 30 turluk döngü bir güvenlik ağıdır, politika değil.
• Zamanlanmış testlerde Europe/Istanbul saat dilimini açıkça belirtin; sunucu UTC'de çalışırken yerel iş saatlerine göre kurulmuş bir cron ifadesi sessizce kayar.

İkinci nokta veri tarafında: test akışlarınız gerçek kullanıcı verisine dokunuyorsa toplanan her kişisel veri KVKK kapsamındadır. Otomasyonu kendi sisteminizde ya da yazılı izin verilmiş bir ortamda çalıştırın, ekran görüntülerini ve form içeriklerini gereğinden uzun saklamayın.

Maliyet tarafında CaptchaAI çözüm başına değil, eşzamanlı thread başına ücretlendirir: BASIC ($15/ay, 5 thread) küçük bir test paketi için yeterlidir, düzenli gece koşuları için STANDARD ($30/ay, 15 thread), paralel yükler için ADVANCE ($90/ay, 50 thread) uygundur. Fiyatlar USD üzerinden sabittir; kur dalgalanmasının olduğu bir pazarda aylık maliyeti önceden bilmek planlamayı kolaylaştırır.

Yaygın hatalar ve çözümleri

Boyut hatalarının büyük kısmı ekran görüntüsü alınırken oluşur: seçici yanlış öğeyi yakaladığında elinizde ya sıfır baytlık bir dosya ya da sayfanın tamamını içeren büyük bir PNG kalır. Hata ayıklarken kaydedilen dosyayı bir kez gözle kontrol etmek en hızlı yoldur.

Sık sorulan sorular

Matematik içeren CAPTCHA'ları da okuyabilir miyim?

Evet. Gönderim parametrelerine calc: 1 ekleyin; sonuç olarak ifadenin kendisi değil, hesaplanmış değer döner.

Yanlış dönen bir metni nasıl bildiririm?

https://ocr.captchaai.com/res.php?key=KEY&action=reportbad&id=TASK_ID adresini çağırın. Yanlış çözümleri bildirmek, harcanan kredinin iadesi için de doğru yoldur.

Aynı anda kaç resim gönderebilirim?

Eşzamanlı görev sayısı planınızdaki thread sayısına eşittir. BASIC ($15/ay, 5 thread) ile aynı anda beş resim çözülür; biri bittiğinde o thread sıradaki isteği alır ve aylık çözüm sayısında ayrı bir sınır yoktur.

Puppeteer yerine Playwright veya Selenium kullanabilir miyim?

Evet. API'nin tarayıcıyla doğrudan bir bağı yok; PNG üretebilen her araç işe yarar. Yalnızca ekran görüntüsü alan satırı kendi aracınızın karşılığıyla değiştirin.

CaptchaAI hCaptcha görsellerini de çözüyor mu?

Hayır, hCaptcha ve FunCaptcha desteklenmiyor. Bu rehberdeki OCR akışı klasik resim ve grid image CAPTCHA'ları içindir; reCAPTCHA, Cloudflare Turnstile ve GeeTest v3 için ayrı yöntemler kullanılır.

İlgili rehberler

• Aynı akışın Python OCR karşılığı
• Resim CAPTCHA çözümünün API tarafı

Ücretsiz hesabınızı açın ve ilk resim CAPTCHA'nızı bugün çözün