Resmi, [doğrulanmış CaptchaSonic topluluk node'u](https://n8n.io/integrations/captchasonic/) ile **n8n iş akışlarınızda** CAPTCHA çözmeyi otomatikleştirin. Node'u çalışma alanınıza sürükleyin, bir CAPTCHA'yı gösterin; çözülmüş token'ı veya yanıtı döndürür — HTTP altyapısı, görsel kazıma veya proxy kurulumu gerekmez.

> [!TIP]
> Node **20+ captcha türünü** destekler ve hem **bağımsız bir iş akışı node'u** hem de **n8n AI Agent node'u için bir araç** olarak çalışır. Tam liste için [yetenek matrisine](/docs/clients-sdks/capabilities) bakın.

**Bağlantılar:** [npm](https://www.npmjs.com/package/n8n-nodes-captchasonic) · [GitHub](https://github.com/captchasonic/n8n-nodes-captchasonic) · [n8n.io listesi](https://n8n.io/integrations/captchasonic/)

---

## Ön koşullar

- Çalışan bir **n8n örneği** (kendi sunucunuzda veya n8n Cloud)
- Bir **CaptchaSonic API anahtarı** — [my.captchasonic.com](https://my.captchasonic.com) üzerinden alın, ardından [bakiye ekleyin](/docs/guides/add-funds)
- **Node.js 18+** (yalnızca kendi sunucunuzda)

---

## Kurulum

1. n8n örneğinizi açın ve **Settings → Community Nodes** bölümüne gidin.
2. **Install** düğmesine tıklayın ve şunu girin:
   ```
   n8n-nodes-captchasonic
   ```
3. **Kendi sunucunuzda:** kurulumdan sonra n8n'i yeniden başlatın. **Cloud:** node otomatik yüklenir.
4. **Doğrulayın** — node paletini açın (**+** tıklayın), `CaptchaSonic` arayın ve node'un göründüğünü onaylayın.

> [!NOTE]
> Node, [n8n tarafından doğrulanmıştır](https://n8n.io/integrations/captchasonic/) ve resmi entegrasyon dizininde listelenir.

---

## Kimlik bilgisi kurulumu

1. n8n'de **Credentials → Add Credential** bölümüne gidin ve **CaptchaSonic API** arayın.
2. [dashboard](https://my.captchasonic.com) üzerinden aldığınız **API anahtarını** yapıştırın.
3. **Save** düğmesine tıklayın — kimlik bilgisi bağlantıyı otomatik olarak test eder.

Kimlik bilgisi artık iş akışlarınızdaki tüm CaptchaSonic node'ları için kullanılabilir.

---

## Hızlı başlangıç iş akışı

En basit iş akışı: tetikleyici → çöz → çıktı.

```json
{
  "nodes": [
    {
      "name": "Manual Trigger",
      "type": "n8n-nodes-base.manualTrigger",
      "position": [250, 300]
    },
    {
      "name": "CaptchaSonic",
      "type": "n8n-nodes-captchasonic.captchaSonic",
      "position": [450, 300],
      "parameters": {
        "operation": "solveCaptcha",
        "captchaType": "ReCaptchaV2TaskProxyLess",
        "websiteURL": "https://example.com/login",
        "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
      }
    }
  ],
  "connections": {
    "Manual Trigger": {
      "main": [[ { "node": "CaptchaSonic", "type": "main", "index": 0 } ]]
    }
  }
}
```

> [!TIP]
> Yukarıdaki JSON'u kopyalayın ve boş bir tuvalde **Import from clipboard** (Ctrl/⌘ + V) ile iş akışını anında yükleyin.

---

## İşlem referansı

### CAPTCHA çöz

Ana işlem. CAPTCHA türünü seçin ve gerekli parametreleri girin.

#### Token görevleri (tarayıcı otomasyonu)

| CAPTCHA türü | Gerekli parametreler | Döndürür |
|---|---|---|
| **reCAPTCHA v2** | `websiteURL`, `websiteKey` | `gRecaptchaResponse` token'ı |
| **reCAPTCHA v3** | `websiteURL`, `websiteKey`, `pageAction` | `gRecaptchaResponse` token'ı |
| **Cloudflare Turnstile** | `websiteURL`, `websiteKey` | `token` |
| **hCaptcha** | `websiteURL`, `websiteKey` | `token` |
| **DataDome** | `websiteURL`, `captchaUrl` | `cookie` |

#### Tanıma görevleri (görsel tabanlı)

| CAPTCHA türü | Gerekli parametreler | Döndürür |
|---|---|---|
| **Image-to-Text (OCR)** | `body` (base64 görsel) | `text` |
| **PopularCaptcha (görsel ızgara)** | `images`, `question` | `solution` dizisi |
| **GeeTest v3** | `gt`, `challenge`, `websiteURL` | `challenge`, `validate`, `seccode` |
| **GeeTest v4** | `captchaId`, `websiteURL` | çözücü çıktısı |
| **AWS WAF** | `websiteURL`, `context`, `iv` | `cookie` |
| **TikTok** | `images` dizisi | `solution` |

> [!NOTE]
> Görsel tabanlı görevlerde görseli **ham base64 string** olarak verin (`data:image/…;base64,` öneki olmadan). Üst akış node'unuz önek ekliyorsa, öneki kaldırmak için **Function** node'unu kullanın.

### Bakiye kontrolü

Mevcut USD kredi bakiyenizi döndürür. Toplu işlemlerden önce bir koruma olarak kullanın.

---

## İş akışı tarifleri

### Tarif 1: Web scraping hattında reCAPTCHA v2

**Trigger → HTTP Request (sayfayı al) → CaptchaSonic (reCAPTCHA çöz) → HTTP Request (formu gönder)**

1. **Schedule Trigger** her saat başı çalışır.
2. **HTTP Request** hedef sayfayı alır ve bir **Function** node'u ile `siteKey` değerini çıkarır.
3. **CaptchaSonic**, `ReCaptchaV2TaskProxyLess` kullanarak reCAPTCHA'yı çözer.
4. İkinci bir **HTTP Request**, çözülmüş `gRecaptchaResponse` ile formu gönderir.

---

### Tarif 2: İzleme için Cloudflare Turnstile aşımı

**Schedule Trigger → CaptchaSonic (Turnstile çöz) → HTTP Request (korumalı API'ye eriş)**

1. **Schedule Trigger** her 15 dakikada bir çalışır.
2. **CaptchaSonic**, `AntiTurnstileTaskProxyLess` ile Turnstile challenge'ını çözer.
3. **HTTP Request**, çözülmüş token'ı cookie veya header olarak kullanarak korumalı uç noktayı çağırır.

---

### Tarif 3: Toplu görselden metne OCR

**Spreadsheet Trigger → Loop Over Items → CaptchaSonic (OCR) → Google Sheets (sonuçları yaz)**

1. **Google Sheets Trigger**, görsel URL'leri içeren yeni satırları algılar.
2. **Loop Over Items** her satırı dolaşır.
3. **HTTP Request** görseli indirir, **Function** base64'e çevirir.
4. **CaptchaSonic**, `ImageToTextTask` ile OCR çalıştırır.
5. **Google Sheets**, çıkarılan metni satıra geri yazar.

---

### Tarif 4: Toplu çalıştırmadan önce bakiye koruması

**Manual Trigger → CaptchaSonic (bakiye al) → IF (< $5) → Stop / Continue**

1. **Manual Trigger** toplu işlemi başlatır.
2. `getBalance` işlemli **CaptchaSonic** node'u `{ balance: 12.50 }` döndürür.
3. **IF** node'u `{{ $json.balance < 5 }}` koşulunu kontrol eder.
4. **True yolu:** "Düşük bakiye — lütfen yükleme yapın." mesajlı **Stop and Error** node'u.
5. **False yolu:** ana çözme döngüsüne devam eder.

> [!TIP]
> İş akışı sessizce başarısız olmadan önce sizi uyarmak için düşük bakiye yoluna bir **Send Email** node'u ekleyin.

---

## Hata yönetimi

### Yaygın hatalar ve çözümler

| Hata | Neden | Çözüm |
|---|---|---|
| `ERROR_WRONG_USER_KEY` | Geçersiz API anahtarı | **Credentials → CaptchaSonic API** bölümünde anahtarınızı yeniden girin |
| `ERROR_ZERO_BALANCE` | Kalan kredi yok | [Bakiye ekleyin](/docs/guides/add-funds) veya yukarıdaki bakiye koruma tarifini kullanın |
| `ERROR_CAPTCHA_UNSOLVABLE` | Hatalı siteKey, URL veya görsel | Parametrelerin canlı sayfayla eşleştiğini doğrulayın; bir kez yeniden deneyin |
| `TIMEOUT` | Çözüm çok uzun sürdü | Node'un zaman aşımı ayarını artırın; CAPTCHA türünün doğru olduğunu kontrol edin |

### Yeniden deneme deseni

CaptchaSonic node'unun **hata çıkışını** bir yeniden deneme döngüsüne bağlayın:

**CaptchaSonic → (hata) → Wait (5 sn) → CaptchaSonic (yeniden dene)**

Sonsuz döngüleri önlemek için Wait'ten sonra bir **IF** node'u kullanarak yeniden denemeleri 3 ile sınırlayın.

### Bakiye koruma deseni

Toplu işlemlerden önce her zaman bakiyeyi kontrol edin. Bkz. yukarıdaki [Tarif 4](#recipe-4-balance-guard-before-batch-execution).

---

## AI agent aracı olarak kullanma

n8n'in **AI Agent** node'u CaptchaSonic'i bir araç olarak çağırabilir; böylece agent, bir sohbet veya görev sırasında CAPTCHA'ları ne zaman çözeceğine dinamik olarak karar verir.

1. Çalışma alanınıza bir **CaptchaSonic** node'u ekleyin.
2. **AI Agent** node'unda **Tools → Add Tool** bölümüne gidin ve CaptchaSonic node'unuzu seçin.
3. Agent artık `solveCaptcha` ve `getBalance` işlemlerine erişir ve sohbet bağlamı gerektirdiğinde bunları çağırır.

> [!NOTE]
> Saf kod agent iş akışları (Claude Code, Cursor vb.) için bunun yerine [MCP sunucu kurulumuna](/docs/mcp/get-started) bakın — doğrudan agent'ın araç sistemine bağlanır.

---

## İpuçları ve en iyi uygulamalar

- Mümkün olduğunda **ProxyLess görev türlerini** kullanın — daha basit ve daha hızlıdırlar.
- Yarım kalan çalıştırmaları önlemek için toplu işlemlerden önce **önce bakiyeyi kontrol edin**.
- Her CAPTCHA türüne uygun **zaman aşımı değerleri** ayarlayın (token: 60 sn, görsel: 30 sn).
- Çözümler başarısız olduğunda uyarı göndermek için n8n'in **hata iş akışını** kullanın (Slack, e-posta).
- İş akışınızı oluştururken kredi harcamamak için test modunda sonuçları **pin** edin.

---

## Sorun giderme

| Belirti | Neden | Çözüm |
|---|---|---|
| Kurulumdan sonra node palette'te yok | n8n yeniden yüklenmedi | n8n'i yeniden başlatın (kendi sunucunuzda) veya tarayıcıyı yenileyin |
| "Invalid credentials" | Anahtarın süresi dolmuş veya yanlış yazılmış | [dashboard](https://my.captchasonic.com) üzerinden anahtarı yeniden oluşturun ve kimlik bilgisini güncelleyin |
| Görev "processing" durumunda takılı | CAPTCHA türü uyuşmuyor veya site değişti | Parametrelerin canlı sayfayla eşleştiğini doğrulayın; farklı bir görev türü deneyin |
| Hız sınırı hataları | Çok fazla eşzamanlı istek | Çözümler arasına bir **Wait** node'u (1–2 sn) ekleyin |

---

## Kaynaklar

- [npm: n8n-nodes-captchasonic](https://www.npmjs.com/package/n8n-nodes-captchasonic)
- [GitHub: captchasonic/n8n-nodes-captchasonic](https://github.com/captchasonic/n8n-nodes-captchasonic)
- [n8n.io listesi](https://n8n.io/integrations/captchasonic/)
- [CaptchaSonic dashboard](https://my.captchasonic.com)
- [REST API referansı](/docs/api)
- [Yetenek matrisi](/docs/clients-sdks/capabilities)
- [AI agent'lar ve MCP](/docs/clients-sdks/ai-agents)
