Automatisez la résolution des CAPTCHA dans vos **workflows n8n** grâce au [nœud communautaire CaptchaSonic officiel et vérifié](https://n8n.io/integrations/captchasonic/). Placez le nœud sur votre canevas, indiquez-lui un CAPTCHA, et il renvoie un jeton ou une réponse résolue — sans plomberie HTTP, sans extraction d'images, sans configuration de proxy.

> [!TIP]
> Le nœud prend en charge **plus de 20 types de captcha** et fonctionne à la fois comme **nœud de workflow autonome** et comme **outil du nœud AI Agent de n8n**. Consultez la [matrice des capacités](/docs/clients-sdks/capabilities) pour la liste complète.

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

---

## Prérequis

- Une **instance n8n** en fonctionnement (auto-hébergée ou n8n Cloud)
- Une **clé API CaptchaSonic** — obtenez-en une sur [my.captchasonic.com](https://my.captchasonic.com), puis [ajoutez des fonds](/docs/guides/add-funds)
- **Node.js 18+** (auto-hébergement uniquement)

---

## Installation

1. Ouvrez votre instance n8n et accédez à **Settings → Community Nodes**.
2. Cliquez sur **Install** et saisissez :
   ```
   n8n-nodes-captchasonic
   ```
3. **Auto-hébergement :** redémarrez n8n après l'installation. **Cloud :** le nœud se charge automatiquement.
4. **Vérification** — ouvrez la palette de nœuds (cliquez sur **+**), recherchez `CaptchaSonic` et vérifiez que le nœud apparaît.

> [!NOTE]
> Le nœud est [vérifié par n8n](https://n8n.io/integrations/captchasonic/) et figure dans le répertoire officiel des intégrations.

---

## Configuration des identifiants

1. Dans n8n, accédez à **Credentials → Add Credential** et recherchez **CaptchaSonic API**.
2. Collez votre **clé API** depuis le [tableau de bord](https://my.captchasonic.com).
3. Cliquez sur **Save** — les identifiants testent automatiquement la connexion.

Les identifiants sont désormais disponibles pour tout nœud CaptchaSonic de vos workflows.

---

## Workflow de démarrage rapide

Le workflow le plus simple : déclencheur → résolution → sortie.

```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]
> Copiez le JSON ci-dessus et utilisez **Import from clipboard** (Ctrl/⌘ + V sur un canevas vide) pour charger le workflow instantanément.

---

## Référence des opérations

### Résoudre un CAPTCHA

L'opération principale. Sélectionnez le type de captcha et renseignez les paramètres requis.

#### Tâches à jeton (automatisation de navigateur)

| Type de captcha | Paramètres requis | Renvoie |
|---|---|---|
| **reCAPTCHA v2** | `websiteURL`, `websiteKey` | jeton `gRecaptchaResponse` |
| **reCAPTCHA v3** | `websiteURL`, `websiteKey`, `pageAction` | jeton `gRecaptchaResponse` |
| **Cloudflare Turnstile** | `websiteURL`, `websiteKey` | `token` |
| **hCaptcha** | `websiteURL`, `websiteKey` | `token` |
| **DataDome** | `websiteURL`, `captchaUrl` | `cookie` |

#### Tâches de reconnaissance (basées sur l'image)

| Type de captcha | Paramètres requis | Renvoie |
|---|---|---|
| **Image-to-Text (OCR)** | `body` (image en base64) | `text` |
| **PopularCaptcha (grille d'images)** | `images`, `question` | tableau `solution` |
| **GeeTest v3** | `gt`, `challenge`, `websiteURL` | `challenge`, `validate`, `seccode` |
| **GeeTest v4** | `captchaId`, `websiteURL` | résultat du solveur |
| **AWS WAF** | `websiteURL`, `context`, `iv` | `cookie` |
| **TikTok** | tableau `images` | `solution` |

> [!NOTE]
> Pour les tâches basées sur l'image, fournissez l'image sous forme de **chaîne base64 brute** (sans le préfixe `data:image/…;base64,`). Utilisez le nœud **Function** pour supprimer ce préfixe si le nœud amont l'ajoute.

### Vérifier le solde

Renvoie votre solde de crédit actuel en USD. Utilisez-le comme garde-fou avant les opérations par lots.

---

## Recettes de workflow

### Recette 1 : reCAPTCHA v2 dans un pipeline de scraping web

**Déclencheur → HTTP Request (récupérer la page) → CaptchaSonic (résoudre le reCAPTCHA) → HTTP Request (soumettre le formulaire)**

1. **Schedule Trigger** se déclenche toutes les heures.
2. **HTTP Request** récupère la page cible et extrait le `siteKey` avec un nœud **Function**.
3. **CaptchaSonic** résout le reCAPTCHA avec `ReCaptchaV2TaskProxyLess`.
4. Un second **HTTP Request** soumet le formulaire avec le `gRecaptchaResponse` obtenu.

---

### Recette 2 : contournement de Cloudflare Turnstile pour la surveillance

**Schedule Trigger → CaptchaSonic (résoudre Turnstile) → HTTP Request (accéder à l'API protégée)**

1. **Schedule Trigger** se déclenche toutes les 15 minutes.
2. **CaptchaSonic** résout le défi Turnstile avec `AntiTurnstileTaskProxyLess`.
3. **HTTP Request** appelle le point de terminaison protégé en utilisant le jeton obtenu comme cookie ou en-tête.

---

### Recette 3 : OCR par lots d'images vers texte

**Spreadsheet Trigger → Loop Over Items → CaptchaSonic (OCR) → Google Sheets (écrire les résultats)**

1. **Google Sheets Trigger** détecte les nouvelles lignes contenant des URL d'images.
2. **Loop Over Items** parcourt chaque ligne.
3. **HTTP Request** télécharge l'image, puis **Function** la convertit en base64.
4. **CaptchaSonic** exécute l'OCR avec `ImageToTextTask`.
5. **Google Sheets** réécrit le texte extrait dans la ligne.

---

### Recette 4 : garde-fou de solde avant l'exécution par lots

**Manual Trigger → CaptchaSonic (get balance) → IF (< 5 $) → Stop / Continue**

1. **Manual Trigger** lance le lot.
2. Le nœud **CaptchaSonic** avec l'opération `getBalance` renvoie `{ balance: 12.50 }`.
3. Le nœud **IF** vérifie `{{ $json.balance < 5 }}`.
4. **Branche vraie :** nœud **Stop and Error** avec le message « Solde insuffisant — veuillez recharger votre compte ».
5. **Branche fausse :** le workflow se poursuit vers la boucle de résolution principale.

> [!TIP]
> Ajoutez un nœud **Send Email** sur la branche de solde insuffisant pour vous alerter avant que le workflow n'échoue silencieusement.

---

## Gestion des erreurs

### Erreurs courantes et solutions

| Erreur | Cause | Solution |
|---|---|---|
| `ERROR_WRONG_USER_KEY` | Clé API invalide | Saisissez à nouveau votre clé dans **Credentials → CaptchaSonic API** |
| `ERROR_ZERO_BALANCE` | Aucun crédit restant | [Ajoutez des fonds](/docs/guides/add-funds), ou utilisez la recette de garde-fou de solde ci-dessus |
| `ERROR_CAPTCHA_UNSOLVABLE` | siteKey, URL ou image incorrects | Vérifiez que les paramètres correspondent à la page en ligne ; réessayez une fois |
| `TIMEOUT` | La résolution a pris trop de temps | Augmentez le paramètre de délai d'attente du nœud ; vérifiez que le type de captcha est correct |

### Schéma de nouvelle tentative

Reliez la **sortie d'erreur** du nœud CaptchaSonic à une boucle de nouvelle tentative :

**CaptchaSonic → (erreur) → Wait (5 s) → CaptchaSonic (nouvelle tentative)**

Utilisez le nœud **IF** après le Wait pour limiter les tentatives à 3 et éviter les boucles infinies.

### Schéma de garde-fou de solde

Vérifiez toujours le solde avant les opérations par lots. Voir la [Recette 4](#recipe-4-balance-guard-before-batch-execution) ci-dessus.

---

## Utilisation comme outil d'agent IA

Le nœud **AI Agent** de n8n peut appeler CaptchaSonic comme outil, de sorte que l'agent décide dynamiquement quand résoudre les CAPTCHA pendant une conversation ou une tâche.

1. Ajoutez un nœud **CaptchaSonic** sur votre canevas.
2. Dans le nœud **AI Agent**, accédez à **Tools** → **Add Tool** → sélectionnez votre nœud CaptchaSonic.
3. L'agent dispose désormais des opérations `solveCaptcha` et `getBalance` et les invoquera lorsque le contexte de la conversation l'exige.

> [!NOTE]
> Pour les workflows d'agents de code purs (Claude Code, Cursor, etc.), consultez plutôt la [configuration du serveur MCP](/docs/mcp/get-started) — il se connecte directement au système d'outils de l'agent.

---

## Conseils et bonnes pratiques

- **Utilisez les types de tâches ProxyLess** lorsque c'est possible : ils sont plus simples et plus rapides.
- **Vérifiez le solde d'abord** avant les opérations par lots pour éviter les exécutions partielles.
- **Définissez des délais d'attente** adaptés à chaque type de captcha (jetons : 60 s, image : 30 s).
- **Utilisez le workflow d'erreur de n8n** pour envoyer des alertes (Slack, e-mail) en cas d'échec de résolution.
- **Épinglez les résultats** en mode test pour ne pas consommer de crédits pendant la mise au point de votre workflow.

---

## Dépannage

| Symptôme | Cause | Solution |
|---|---|---|
| Nœud absent de la palette après l'installation | n8n ne s'est pas rechargé | Redémarrez n8n (auto-hébergement) ou actualisez le navigateur |
| « Invalid credentials » | Clé expirée ou mal saisie | Régénérez la clé dans le [tableau de bord](https://my.captchasonic.com) et mettez à jour les identifiants |
| Tâche bloquée sur « processing » | Type de captcha incorrect ou site modifié | Vérifiez que les paramètres correspondent à la page en ligne ; essayez un autre type de tâche |
| Erreurs de limitation de débit | Trop de requêtes simultanées | Ajoutez un nœud **Wait** (1–2 s) entre les résolutions |

---

## Ressources

- [npm : n8n-nodes-captchasonic](https://www.npmjs.com/package/n8n-nodes-captchasonic)
- [GitHub : captchasonic/n8n-nodes-captchasonic](https://github.com/captchasonic/n8n-nodes-captchasonic)
- [Fiche n8n.io](https://n8n.io/integrations/captchasonic/)
- [Tableau de bord CaptchaSonic](https://my.captchasonic.com)
- [Référence de l'API REST](/docs/api)
- [Matrice des capacités](/docs/clients-sdks/capabilities)
- [Agents IA et MCP](/docs/clients-sdks/ai-agents)
