Automatiza la resolución de CAPTCHAs en tus **flujos de n8n** con el nodo comunitario oficial y [verificado de CaptchaSonic](https://n8n.io/integrations/captchasonic/). Arrastra el nodo a tu lienzo, indícale un CAPTCHA y devolverá un token o una respuesta resuelta — sin código HTTP, sin extraer imágenes, sin configurar proxy.

> [!TIP]
> El nodo admite **más de 20 tipos de captcha** y funciona tanto como **nodo independiente del flujo** como **herramienta del nodo AI Agent de n8n**. Consulta la [matriz de capacidades](/docs/clients-sdks/capabilities) para ver la lista completa.

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

---

## Requisitos previos

- Una **instancia de n8n** en funcionamiento (autoalojada o n8n Cloud)
- Una **clave de API de CaptchaSonic** — obtenla en [my.captchasonic.com](https://my.captchasonic.com) y luego [añade fondos](/docs/guides/add-funds)
- **Node.js 18+** (solo para instalaciones autoalojadas)

---

## Instalación

1. Abre tu instancia de n8n y ve a **Settings → Community Nodes**.
2. Haz clic en **Install** e introduce:
   ```
   n8n-nodes-captchasonic
   ```
3. **Autoalojada:** reinicia n8n después de la instalación. **Cloud:** el nodo se carga automáticamente.
4. **Verifica** — abre la paleta de nodos (haz clic en **+**), busca `CaptchaSonic` y confirma que aparece el nodo.

> [!NOTE]
> El nodo está [verificado por n8n](https://n8n.io/integrations/captchasonic/) y aparece en el directorio oficial de integraciones.

---

## Configuración de credenciales

1. En n8n, ve a **Credentials → Add Credential** y busca **CaptchaSonic API**.
2. Pega tu **clave de API** desde el [panel](https://my.captchasonic.com).
3. Haz clic en **Save** — la credencial prueba la conexión automáticamente.

La credencial ya está disponible para cualquier nodo de CaptchaSonic en tus flujos.

---

## Flujo de inicio rápido

El flujo más sencillo posible: disparador → resolver → salida.

```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]
> Copia el JSON de arriba e **impórtalo desde el portapapeles** (Ctrl/⌘ + V en un lienzo vacío) para cargar el flujo al instante.

---

## Referencia de operaciones

### Resolver CAPTCHA

La operación principal. Selecciona el tipo de captcha e indica los parámetros requeridos.

#### Tareas de token (automatización de navegador)

| Tipo de captcha | Parámetros requeridos | Devuelve |
|---|---|---|
| **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` |

#### Tareas de reconocimiento (basadas en imágenes)

| Tipo de captcha | Parámetros requeridos | Devuelve |
|---|---|---|
| **Image-to-Text (OCR)** | `body` (imagen en base64) | `text` |
| **PopularCaptcha (cuadrícula de imágenes)** | `images`, `question` | array `solution` |
| **GeeTest v3** | `gt`, `challenge`, `websiteURL` | `challenge`, `validate`, `seccode` |
| **GeeTest v4** | `captchaId`, `websiteURL` | salida del solver |
| **AWS WAF** | `websiteURL`, `context`, `iv` | `cookie` |
| **TikTok** | array `images` | `solution` |

> [!NOTE]
> En tareas basadas en imágenes, envía la imagen como **cadena base64 sin formato** (sin el prefijo `data:image/…;base64,`). Usa el nodo **Function** para quitar el prefijo si el nodo anterior lo añade.

### Consultar saldo

Devuelve tu saldo actual en USD. Úsalo como control previo a las operaciones por lotes.

---

## Recetas de flujos

### Receta 1: reCAPTCHA v2 en un proceso de web scraping

**Disparador → HTTP Request (obtener página) → CaptchaSonic (resolver reCAPTCHA) → HTTP Request (enviar formulario)**

1. **Schedule Trigger** se activa cada hora.
2. **HTTP Request** descarga la página objetivo y extrae el `siteKey` con un nodo **Function**.
3. **CaptchaSonic** resuelve el reCAPTCHA con `ReCaptchaV2TaskProxyLess`.
4. Un segundo **HTTP Request** envía el formulario con el `gRecaptchaResponse` resuelto.

---

### Receta 2: Bypass de Cloudflare Turnstile para monitorización

**Schedule Trigger → CaptchaSonic (resolver Turnstile) → HTTP Request (acceder a la API protegida)**

1. **Schedule Trigger** se activa cada 15 minutos.
2. **CaptchaSonic** resuelve el desafío Turnstile con `AntiTurnstileTaskProxyLess`.
3. **HTTP Request** llama al endpoint protegido usando el token resuelto como cookie o cabecera.

---

### Receta 3: OCR por lotes de imagen a texto

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

1. **Google Sheets Trigger** detecta filas nuevas con URLs de imágenes.
2. **Loop Over Items** recorre cada fila.
3. **HTTP Request** descarga la imagen y **Function** la convierte a base64.
4. **CaptchaSonic** ejecuta el OCR con `ImageToTextTask`.
5. **Google Sheets** escribe el texto extraído de vuelta en la fila.

---

### Receta 4: Control de saldo antes de la ejecución por lotes

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

1. **Manual Trigger** inicia el lote.
2. El nodo **CaptchaSonic** con la operación `getBalance` devuelve `{ balance: 12.50 }`.
3. El nodo **IF** comprueba `{{ $json.balance < 5 }}`.
4. **Ruta verdadera:** nodo **Stop and Error** con el mensaje "Saldo bajo — por favor, recarga."
5. **Ruta falsa:** continúa con el bucle principal de resolución.

> [!TIP]
> Añade un nodo **Send Email** en la ruta de saldo bajo para avisarte antes de que el flujo falle sin aviso.

---

## Manejo de errores

### Errores comunes y soluciones

| Error | Causa | Solución |
|---|---|---|
| `ERROR_WRONG_USER_KEY` | Clave de API no válida | Vuelve a introducir tu clave en **Credentials → CaptchaSonic API** |
| `ERROR_ZERO_BALANCE` | No quedan créditos | [Añade fondos](/docs/guides/add-funds) o usa la receta de control de saldo de arriba |
| `ERROR_CAPTCHA_UNSOLVABLE` | siteKey, URL o imagen incorrectos | Verifica que los parámetros coincidan con la página activa; reintenta una vez |
| `TIMEOUT` | La resolución tardó demasiado | Aumenta el tiempo de espera del nodo; comprueba que el tipo de captcha sea correcto |

### Patrón de reintento

Conecta la **salida de error** del nodo CaptchaSonic a un bucle de reintento:

**CaptchaSonic → (error) → Wait (5 s) → CaptchaSonic (reintento)**

Usa el nodo **IF** después de Wait para limitar los reintentos a 3 y evitar bucles infinitos.

### Patrón de control de saldo

Comprueba siempre el saldo antes de las operaciones por lotes. Consulta la [Receta 4](#recipe-4-balance-guard-before-batch-execution) más arriba.

---

## Uso como herramienta de AI Agent

El nodo **AI Agent** de n8n puede llamar a CaptchaSonic como herramienta, de modo que el agente decide dinámicamente cuándo resolver CAPTCHAs durante una conversación o tarea.

1. Añade un nodo **CaptchaSonic** a tu lienzo.
2. En el nodo **AI Agent**, ve a **Tools** → **Add Tool** → selecciona tu nodo CaptchaSonic.
3. El agente ya tiene acceso a las operaciones `solveCaptcha` y `getBalance` y las invocará cuando el contexto de la conversación lo requiera.

> [!NOTE]
> Para flujos de agentes de código puros (Claude Code, Cursor, etc.), consulta en su lugar la [configuración del servidor MCP](/docs/mcp/get-started), que se conecta directamente al sistema de herramientas del agente.

---

## Consejos y buenas prácticas

- **Usa los tipos de tarea ProxyLess** cuando sea posible: son más sencillos y rápidos.
- **Consulta el saldo primero** antes de las operaciones por lotes para evitar ejecuciones parciales.
- **Define tiempos de espera adecuados** para cada tipo de captcha (tokens: 60 s, imagen: 30 s).
- **Usa el flujo de errores de n8n** para enviar alertas (Slack, email) cuando fallen las resoluciones.
- **Fija los resultados** en modo de prueba para no gastar créditos mientras construyes el flujo.

---

## Solución de problemas

| Síntoma | Causa | Solución |
|---|---|---|
| El nodo no aparece en la paleta tras instalarlo | n8n no se recargó | Reinicia n8n (autoalojada) o actualiza el navegador |
| "Invalid credentials" | Clave caducada o mal escrita | Regenera la clave en el [panel](https://my.captchasonic.com) y actualiza la credencial |
| La tarea se queda en "processing" | Tipo de captcha incorrecto o el sitio cambió | Verifica que los parámetros coincidan con la página activa; prueba otro tipo de tarea |
| Errores de límite de frecuencia | Demasiadas solicitudes simultáneas | Añade un nodo **Wait** (1–2 s) entre resoluciones |

---

## 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)
- [Ficha en n8n.io](https://n8n.io/integrations/captchasonic/)
- [Panel de CaptchaSonic](https://my.captchasonic.com)
- [Referencia de la API REST](/docs/api)
- [Matriz de capacidades](/docs/clients-sdks/capabilities)
- [AI agents y MCP](/docs/clients-sdks/ai-agents)
