Automatisieren Sie die CAPTCHA-Lösung in Ihren **n8n-Workflows** mit dem offiziellen, [verifizierten CaptchaSonic-Community-Node](https://n8n.io/integrations/captchasonic/). Ziehen Sie den Node auf Ihre Arbeitsfläche, verweisen Sie ihn auf ein CAPTCHA, und er gibt ein gelöstes Token oder eine Antwort zurück — ohne HTTP-Aufwand, ohne Bild-Scraping, ohne Proxy-Setup.

> [!TIP]
> Der Node unterstützt **20+ CAPTCHA-Typen** und funktioniert sowohl als **eigenständiger Workflow-Node** als auch als **Tool für den AI-Agent-Node von n8n**. Die vollständige Liste finden Sie in der [Fähigkeitenmatrix](/docs/clients-sdks/capabilities).

**Links:** [npm](https://www.npmjs.com/package/n8n-nodes-captchasonic) · [GitHub](https://github.com/captchasonic/n8n-nodes-captchasonic) · [n8n.io-Eintrag](https://n8n.io/integrations/captchasonic/)

---

## Voraussetzungen

- Eine laufende **n8n-Instanz** (selbst gehostet oder n8n Cloud)
- Ein **CaptchaSonic-API-Schlüssel** — holen Sie ihn sich unter [my.captchasonic.com](https://my.captchasonic.com) und [laden Sie Guthaben auf](/docs/guides/add-funds)
- **Node.js 18+** (nur bei selbst gehostetem n8n)

---

## Installation

1. Öffnen Sie Ihre n8n-Instanz und gehen Sie zu **Settings → Community Nodes**.
2. Klicken Sie auf **Install** und geben Sie ein:
   ```
   n8n-nodes-captchasonic
   ```
3. **Selbst gehostet:** Starten Sie n8n nach der Installation neu. **Cloud:** Der Node wird automatisch geladen.
4. **Prüfen** — öffnen Sie die Node-Palette (klicken Sie auf **+**), suchen Sie nach `CaptchaSonic` und bestätigen Sie, dass der Node erscheint.

> [!NOTE]
> Der Node ist [von n8n verifiziert](https://n8n.io/integrations/captchasonic/) und im offiziellen Integrationsverzeichnis gelistet.

---

## Einrichtung der Credentials

1. Gehen Sie in n8n zu **Credentials → Add Credential** und suchen Sie nach **CaptchaSonic API**.
2. Fügen Sie Ihren **API-Schlüssel** aus dem [Dashboard](https://my.captchasonic.com) ein.
3. Klicken Sie auf **Save** — die Credentials prüfen die Verbindung automatisch.

Die Credentials stehen nun jedem CaptchaSonic-Node in Ihren Workflows zur Verfügung.

---

## Schnellstart-Workflow

Der einfachste mögliche Workflow: Auslöser → lösen → Ausgabe.

```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]
> Kopieren Sie das obige JSON und nutzen Sie **Import from clipboard** (Strg/⌘ + V auf einer leeren Arbeitsfläche), um den Workflow sofort zu laden.

---

## Referenz der Operationen

### CAPTCHA lösen

Die primäre Operation. Wählen Sie den CAPTCHA-Typ und geben Sie die erforderlichen Parameter an.

#### Token-Aufgaben (Browser-Automatisierung)

| CAPTCHA-Typ | Erforderliche Parameter | Rückgabe |
|---|---|---|
| **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` |

#### Erkennungs-Aufgaben (bildbasiert)

| CAPTCHA-Typ | Erforderliche Parameter | Rückgabe |
|---|---|---|
| **Image-to-Text (OCR)** | `body` (Base64-Bild) | `text` |
| **PopularCaptcha (Bildraster)** | `images`, `question` | `solution`-Array |
| **GeeTest v3** | `gt`, `challenge`, `websiteURL` | `challenge`, `validate`, `seccode` |
| **GeeTest v4** | `captchaId`, `websiteURL` | Solver-Ausgabe |
| **AWS WAF** | `websiteURL`, `context`, `iv` | `cookie` |
| **TikTok** | `images`-Array | `solution` |

> [!NOTE]
> Geben Sie bei bildbasierten Aufgaben das Bild als **reinen Base64-String** an (ohne das Präfix `data:image/…;base64,`). Verwenden Sie den **Function**-Node, um das Präfix zu entfernen, falls Ihr vorheriger Node es hinzufügt.

### Guthaben prüfen

Gibt Ihr aktuelles Guthaben in USD zurück. Nutzen Sie es als Sicherung vor Batch-Operationen.

---

## Workflow-Rezepte

### Rezept 1: reCAPTCHA v2 in einer Web-Scraping-Pipeline

**Auslöser → HTTP Request (Seite abrufen) → CaptchaSonic (reCAPTCHA lösen) → HTTP Request (Formular absenden)**

1. Der **Schedule Trigger** läuft jede Stunde.
2. Der **HTTP Request** ruft die Zielseite ab, und ein **Function**-Node extrahiert den `siteKey`.
3. **CaptchaSonic** löst das reCAPTCHA mit `ReCaptchaV2TaskProxyLess`.
4. Ein zweiter **HTTP Request** sendet das Formular mit dem gelösten `gRecaptchaResponse` ab.

---

### Rezept 2: Cloudflare-Turnstile-Umgehung für Monitoring

**Schedule Trigger → CaptchaSonic (Turnstile lösen) → HTTP Request (geschützte API aufrufen)**

1. Der **Schedule Trigger** läuft alle 15 Minuten.
2. **CaptchaSonic** löst die Turnstile-Challenge mit `AntiTurnstileTaskProxyLess`.
3. Der **HTTP Request** ruft den geschützten Endpunkt auf und übergibt das gelöste Token als Cookie oder Header.

---

### Rezept 3: Batch-OCR für Bilder zu Text

**Spreadsheet Trigger → Loop Over Items → CaptchaSonic (OCR) → Google Sheets (Ergebnisse schreiben)**

1. Der **Google Sheets Trigger** erkennt neue Zeilen mit Bild-URLs.
2. **Loop Over Items** durchläuft jede Zeile.
3. Der **HTTP Request** lädt das Bild herunter, und **Function** wandelt es in Base64 um.
4. **CaptchaSonic** führt OCR mit `ImageToTextTask` aus.
5. **Google Sheets** schreibt den extrahierten Text zurück in die Zeile.

---

### Rezept 4: Guthaben-Sicherung vor der Batch-Ausführung

**Manual Trigger → CaptchaSonic (Guthaben abrufen) → IF (< $5) → Stop / Continue**

1. Der **Manual Trigger** startet den Batch.
2. Der **CaptchaSonic**-Node mit der Operation `getBalance` liefert `{ balance: 12.50 }`.
3. Der **IF**-Node prüft `{{ $json.balance < 5 }}`.
4. **Wahr-Pfad:** Ein **Stop and Error**-Node mit der Meldung „Niedriges Guthaben — bitte aufladen.“
5. **Falsch-Pfad:** Der Workflow läuft mit der Hauptschleife weiter.

> [!TIP]
> Fügen Sie auf dem Pfad bei niedrigem Guthaben einen **Send Email**-Node hinzu, um sich zu benachrichtigen, bevor der Workflow stillschweigend fehlschlägt.

---

## Fehlerbehandlung

### Häufige Fehler und Lösungen

| Fehler | Ursache | Lösung |
|---|---|---|
| `ERROR_WRONG_USER_KEY` | Ungültiger API-Schlüssel | Schlüssel unter **Credentials → CaptchaSonic API** neu eingeben |
| `ERROR_ZERO_BALANCE` | Kein Guthaben mehr vorhanden | [Guthaben aufladen](/docs/guides/add-funds) oder das Rezept zur Guthaben-Sicherung oben nutzen |
| `ERROR_CAPTCHA_UNSOLVABLE` | Falscher siteKey, falsche URL oder falsches Bild | Prüfen Sie, ob die Parameter zur Live-Seite passen; versuchen Sie es einmal erneut |
| `TIMEOUT` | Lösung hat zu lange gedauert | Timeout-Einstellung des Nodes erhöhen; prüfen, ob der CAPTCHA-Typ korrekt ist |

### Wiederholungsmuster

Verbinden Sie den **Error-Ausgang** des CaptchaSonic-Nodes mit einer Wiederholungsschleife:

**CaptchaSonic → (Fehler) → Wait (5 s) → CaptchaSonic (erneuter Versuch)**

Nutzen Sie nach dem Wait-Node einen **IF**-Node, um Wiederholungen auf 3 zu begrenzen und Endlosschleifen zu vermeiden.

### Muster der Guthaben-Sicherung

Prüfen Sie das Guthaben immer vor Batch-Operationen. Siehe [Rezept 4](#recipe-4-balance-guard-before-batch-execution) oben.

---

## Verwendung als KI-Agent-Tool

Der **AI-Agent**-Node von n8n kann CaptchaSonic als Tool aufrufen, sodass der Agent während eines Gesprächs oder einer Aufgabe selbst entscheidet, wann CAPTCHAs gelöst werden.

1. Fügen Sie einen **CaptchaSonic**-Node zu Ihrer Arbeitsfläche hinzu.
2. Gehen Sie im **AI-Agent**-Node zu **Tools** → **Add Tool** und wählen Sie Ihren CaptchaSonic-Node aus.
3. Der Agent hat nun Zugriff auf die Operationen `solveCaptcha` und `getBalance` und ruft sie auf, wenn der Gesprächskontext es erfordert.

> [!NOTE]
> Für reine Code-Agent-Workflows (Claude Code, Cursor usw.) finden Sie die Anleitung stattdessen im [MCP-Server-Setup](/docs/mcp/get-started) — es verbindet sich direkt mit dem Tool-System des Agenten.

---

## Tipps & Best Practices

- **Verwenden Sie ProxyLess-Aufgabentypen**, wenn möglich — sie sind einfacher und schneller.
- **Prüfen Sie das Guthaben zuerst** vor Batch-Operationen, um teilweise Durchläufe zu vermeiden.
- **Legen Sie Timeout-Werte** passend zu jedem CAPTCHA-Typ fest (Token: 60 s, Bild: 30 s).
- **Nutzen Sie den Error-Workflow von n8n**, um Benachrichtigungen (Slack, E-Mail) bei fehlgeschlagenen Lösungen zu senden.
- **Fixieren Sie Ergebnisse** im Testmodus, damit Sie beim Aufbau Ihres Workflows kein Guthaben verbrauchen.

---

## Fehlerbehebung

| Symptom | Ursache | Lösung |
|---|---|---|
| Node nach der Installation nicht in der Palette | n8n hat nicht neu geladen | n8n neu starten (selbst gehostet) oder Browser aktualisieren |
| „Invalid credentials“ | Schlüssel abgelaufen oder falsch eingegeben | Schlüssel im [Dashboard](https://my.captchasonic.com) neu erzeugen und Credentials aktualisieren |
| Aufgabe bleibt bei „processing“ hängen | CAPTCHA-Typ passt nicht oder Seite hat sich geändert | Parameter mit der Live-Seite abgleichen; anderen Aufgabentyp testen |
| Rate-Limit-Fehler | Zu viele gleichzeitige Anfragen | Einen **Wait**-Node (1–2 s) zwischen den Lösungen einfügen |

---

## Ressourcen

- [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-Eintrag](https://n8n.io/integrations/captchasonic/)
- [CaptchaSonic-Dashboard](https://my.captchasonic.com)
- [REST-API-Referenz](/docs/api)
- [Fähigkeitenmatrix](/docs/clients-sdks/capabilities)
- [KI-Agenten & MCP](/docs/clients-sdks/ai-agents)
