Automatize a resolução de CAPTCHAs nos seus **workflows do n8n** com o [nó da comunidade CaptchaSonic oficial e verificado](https://n8n.io/integrations/captchasonic/). Arraste o nó para o seu canvas, aponte-o para um CAPTCHA e ele retorna um token ou resposta resolvida — sem código HTTP, sem raspagem de imagens, sem configuração de proxy.

> [!TIP]
> O nó suporta **mais de 20 tipos de captcha** e funciona tanto como **nó de workflow** quanto como **ferramenta do nó AI Agent** do n8n. Veja a [matriz de capacidades](/docs/clients-sdks/capabilities) para a lista completa.

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

---

## Pré-requisitos

- Uma **instância do n8n** em execução (self-hosted ou n8n Cloud)
- Uma **chave de API do CaptchaSonic** — obtenha uma em [my.captchasonic.com](https://my.captchasonic.com) e depois [adicione saldo](/docs/guides/add-funds)
- **Node.js 18+** (somente self-hosted)

---

## Instalação

1. Abra sua instância do n8n e vá em **Settings → Community Nodes**.
2. Clique em **Install** e informe:
   ```
   n8n-nodes-captchasonic
   ```
3. **Self-hosted:** reinicie o n8n após a instalação. **Cloud:** o nó é carregado automaticamente.
4. **Verifique** — abra a paleta de nós (clique em **+**), pesquise `CaptchaSonic` e confirme que o nó aparece.

> [!NOTE]
> O nó é [verificado pelo n8n](https://n8n.io/integrations/captchasonic/) e listado no diretório oficial de integrações.

---

## Configuração de credencial

1. No n8n, vá em **Credentials → Add Credential** e pesquise por **CaptchaSonic API**.
2. Cole sua **chave de API** do [painel](https://my.captchasonic.com).
3. Clique em **Save** — a credencial testa a conexão automaticamente.

A credencial fica disponível para qualquer nó CaptchaSonic nos seus workflows.

---

## Workflow de início rápido

O workflow mais simples possível: gatilho → resolver → saída.

```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]
> Copie o JSON acima e use **Import from clipboard** (Ctrl/⌘ + V em um canvas vazio) para carregar o workflow instantaneamente.

---

## Referência de operações

### Resolver CAPTCHA

A operação principal. Selecione o tipo de captcha e informe os parâmetros obrigatórios.

#### Tarefas de token (automação de navegador)

| Tipo de CAPTCHA | Parâmetros obrigatórios | Retorna |
|---|---|---|
| **reCAPTCHA v2** | `websiteURL`, `websiteKey` | token `gRecaptchaResponse` |
| **reCAPTCHA v3** | `websiteURL`, `websiteKey`, `pageAction` | token `gRecaptchaResponse` |
| **Cloudflare Turnstile** | `websiteURL`, `websiteKey` | `token` |
| **hCaptcha** | `websiteURL`, `websiteKey` | `token` |
| **DataDome** | `websiteURL`, `captchaUrl` | `cookie` |

#### Tarefas de reconhecimento (baseadas em imagem)

| Tipo de CAPTCHA | Parâmetros obrigatórios | Retorna |
|---|---|---|
| **Image-to-Text (OCR)** | `body` (imagem em base64) | `text` |
| **PopularCaptcha (grade de imagens)** | `images`, `question` | array `solution` |
| **GeeTest v3** | `gt`, `challenge`, `websiteURL` | `challenge`, `validate`, `seccode` |
| **GeeTest v4** | `captchaId`, `websiteURL` | saída do solver |
| **AWS WAF** | `websiteURL`, `context`, `iv` | `cookie` |
| **TikTok** | array `images` | `solution` |

> [!NOTE]
> Para tarefas baseadas em imagem, informe a imagem como uma **string base64 pura** (sem o prefixo `data:image/…;base64,`). Use o nó **Function** para remover o prefixo caso o nó anterior o adicione.

### Verificar saldo

Retorna seu saldo de créditos atual em USD. Use-o como uma proteção antes de operações em lote.

---

## Receitas de workflow

### Receita 1: reCAPTCHA v2 em um pipeline de raspagem web

**Trigger → HTTP Request (obter página) → CaptchaSonic (resolver reCAPTCHA) → HTTP Request (enviar formulário)**

1. **Schedule Trigger** dispara a cada hora.
2. **HTTP Request** busca a página alvo e extrai o `siteKey` com um nó **Function**.
3. **CaptchaSonic** resolve o reCAPTCHA usando `ReCaptchaV2TaskProxyLess`.
4. Um segundo **HTTP Request** envia o formulário com o `gRecaptchaResponse` resolvido.

---

### Receita 2: bypass de Cloudflare Turnstile para monitoramento

**Schedule Trigger → CaptchaSonic (resolver Turnstile) → HTTP Request (acessar API protegida)**

1. **Schedule Trigger** dispara a cada 15 minutos.
2. **CaptchaSonic** resolve o desafio Turnstile com `AntiTurnstileTaskProxyLess`.
3. **HTTP Request** chama o endpoint protegido usando o token resolvido como cookie ou cabeçalho.

---

### Receita 3: OCR em lote de imagem para texto

**Spreadsheet Trigger → Loop Over Items → CaptchaSonic (OCR) → Google Sheets (gravar resultados)**

1. **Google Sheets Trigger** detecta novas linhas com URLs de imagens.
2. **Loop Over Items** percorre cada linha.
3. **HTTP Request** baixa a imagem, e o **Function** a converte para base64.
4. **CaptchaSonic** executa o OCR com `ImageToTextTask`.
5. **Google Sheets** grava o texto extraído de volta na linha.

---

### Receita 4: proteção de saldo antes da execução em lote

**Manual Trigger → CaptchaSonic (obter saldo) → IF (< $5) → Stop / Continue**

1. **Manual Trigger** inicia o lote.
2. O nó **CaptchaSonic** com a operação `getBalance` retorna `{ balance: 12.50 }`.
3. O nó **IF** verifica `{{ $json.balance < 5 }}`.
4. **Caminho verdadeiro:** nó **Stop and Error** com a mensagem "Saldo baixo — recarregue por favor."
5. **Caminho falso:** continua para o loop principal de resolução.

> [!TIP]
> Adicione um nó **Send Email** no caminho de saldo baixo para avisar você antes que o workflow falhe silenciosamente.

---

## Tratamento de erros

### Erros comuns e correções

| Erro | Causa | Correção |
|---|---|---|
| `ERROR_WRONG_USER_KEY` | Chave de API inválida | Informe novamente sua chave em **Credentials → CaptchaSonic API** |
| `ERROR_ZERO_BALANCE` | Sem créditos restantes | [Adicione saldo](/docs/guides/add-funds), ou use a receita de proteção de saldo acima |
| `ERROR_CAPTCHA_UNSOLVABLE` | siteKey, URL ou imagem incorretos | Verifique se os parâmetros correspondem à página ativa; tente novamente uma vez |
| `TIMEOUT` | A resolução demorou demais | Aumente a configuração de timeout do nó; confirme se o tipo de captcha está correto |

### Padrão de nova tentativa

Conecte a **saída de erro** do nó CaptchaSonic a um loop de nova tentativa:

**CaptchaSonic → (erro) → Wait (5 s) → CaptchaSonic (nova tentativa)**

Use o nó **IF** após o Wait para limitar as tentativas a 3 e evitar loops infinitos.

### Padrão de proteção de saldo

Sempre verifique o saldo antes de operações em lote. Veja a [Receita 4](#recipe-4-balance-guard-before-batch-execution) acima.

---

## Usando como ferramenta de agente de IA

O nó **AI Agent** do n8n pode chamar o CaptchaSonic como ferramenta, para que o agente decida dinamicamente quando resolver CAPTCHAs durante uma conversa ou tarefa.

1. Adicione um nó **CaptchaSonic** ao seu canvas.
2. No nó **AI Agent**, vá em **Tools** → **Add Tool** → selecione seu nó CaptchaSonic.
3. O agente agora tem acesso às operações `solveCaptcha` e `getBalance` e as invocará quando o contexto da conversa exigir.

> [!NOTE]
> Para workflows de agentes de código puros (Claude Code, Cursor etc.), veja a [configuração do servidor MCP](/docs/mcp/get-started) — ele se conecta diretamente ao sistema de ferramentas do agente.

---

## Dicas e boas práticas

- **Use tipos de tarefa ProxyLess** sempre que possível — são mais simples e rápidos.
- **Verifique o saldo primeiro** antes de operações em lote para evitar execuções parciais.
- **Defina valores de timeout** adequados para cada tipo de captcha (tokens: 60 s, imagem: 30 s).
- **Use o workflow de erros do n8n** para enviar alertas (Slack, e-mail) quando as resoluções falharem.
- **Fixe resultados** no modo de teste para não gastar créditos enquanto constrói seu workflow.

---

## Solução de problemas

| Sintoma | Causa | Solução |
|---|---|---|
| Nó não aparece na paleta após a instalação | O n8n não recarregou | Reinicie o n8n (self-hosted) ou atualize o navegador |
| "Invalid credentials" | Chave expirada ou digitada incorretamente | Gere uma nova chave no [painel](https://my.captchasonic.com) e atualize a credencial |
| Tarefa presa em "processing" | Tipo de captcha incompatível ou site alterado | Verifique se os parâmetros correspondem à página ativa; tente outro tipo de tarefa |
| Erros de limite de taxa | Muitas requisições simultâneas | Adicione um nó **Wait** (1–2 s) entre as resoluções |

---

## Recursos

- [npm: n8n-nodes-captchasonic](https://www.npmjs.com/package/n8n-nodes-captchasonic)
- [GitHub: captchasonic/n8n-nodes-captchasonic](https://github.com/captchasonic/n8n-nodes-captchasonic)
- [Página no n8n.io](https://n8n.io/integrations/captchasonic/)
- [Painel do CaptchaSonic](https://my.captchasonic.com)
- [Referência da API REST](/docs/api)
- [Matriz de capacidades](/docs/clients-sdks/capabilities)
- [Agentes de IA e MCP](/docs/clients-sdks/ai-agents)
