Integrar CaptchaSonic en tus flujos de automatización de navegador te permite superar desafíos CAPTCHA complejos sin intervención manual. Esta guía cubre la instalación, la configuración y el uso de la extensión de CaptchaSonic en entornos automatizados.

> [!TIP]
> **Método preferido**: para automatización a gran escala, recomendamos usar nuestra API directamente. Sin embargo, la extensión de navegador es ideal para herramientas como Selenium, Puppeteer y Playwright, donde se necesita un entorno de navegador real.

---

## 1. Primeros pasos

Antes de usar la extensión en tus scripts de automatización, necesitas una clave API válida de tu panel de CaptchaSonic.

1.  **Crear una cuenta**: regístrate en [captchasonic.com](https://captchasonic.com).
2.  **Obtener la clave API**: inicia sesión en tu [panel](https://captchasonic.com/app) y copia tu clave API única.

![Resultado del panel de CaptchaSonic](/guides/CR/guide.7.png)

---

## 2. Instalación y configuración

### Para navegadores basados en Chrome/Chromium

Los frameworks de automatización suelen requerir una clave API «fija en el código» si no usas un perfil de navegador persistente.

1.  **Descargar el código fuente**: clona o descarga el [repositorio de la extensión de CaptchaSonic](https://github.com/Captcha-Sonic/CaptchaSonic-Extension/releases/latest).
2.  **Configurar la clave API**:
    *   Ve a la carpeta `config` dentro del código fuente de la extensión.
    *   Abre el archivo de configuración predeterminado (normalmente `config.json` o similar).
    *   Pega tu clave API en el campo `apiKey`.
3.  **Cargar en Chrome**:
    *   Abre `chrome://extensions/`.
    *   Activa el **Modo de desarrollador**.
    *   Haz clic en **Load unpacked** y selecciona la carpeta de la extensión modificada.

> [!IMPORTANT]
> Asegúrate de que tu framework de automatización está configurado para permitir cargar extensiones sin empaquetar. En Selenium, esto se hace mediante `ChromeOptions`.

### Para Firefox

1.  **Descargar el XPI**: instálala desde la [tienda de complementos de Firefox](https://addons.mozilla.org/en-US/firefox/addon/captchasonic/), o descarga la última compilación desde las [versiones de la extensión de CaptchaSonic](https://github.com/Captcha-Sonic/CaptchaSonic-Extension/releases/latest).
2.  **Instalación manual**: ve a `about:addons`, haz clic en el icono de engranaje y selecciona **Install Add-on From File**.

---

## 3. Integración con frameworks de automatización

Para usar la extensión en tu código, debes indicar la ruta a la carpeta o al archivo de la extensión.

### Selenium (Python)

```python
from selenium import webdriver
from selenium.webdriver.chrome.options import Options

chrome_options = Options()
chrome_options.add_argument("--load-extension=/path/to/extracted/extension")

driver = webdriver.Chrome(options=chrome_options)
driver.get("https://web.captcha-target.com")
```

### Playwright (Node.js)

```javascript
const { chromium } = require('playwright');

(async () => {
  const pathToExtension = require('path').join(__dirname, 'my-extension');
  const userDataDir = '/tmp/test-user-data-dir';
  const browserContext = await chromium.launchPersistentContext(userDataDir, {
    headless: false,
    args: [
      `--disable-extensions-except=${pathToExtension}`,
      `--load-extension=${pathToExtension}`,
    ],
  });
  // ... your automation logic
})();
```

---

## 4. Configuración de parámetros

Dentro del popup de la extensión o de su archivo de configuración, puedes ajustar con precisión cómo se gestionan los CAPTCHAs:

*   **Auto-Solve**: activa automáticamente el proceso de resolución cuando se detecta un CAPTCHA.
*   **Solve Delay**: añade una pausa natural antes de resolver, para imitar el comportamiento humano.
*   **Target Types**: activa o desactiva solucionadores específicos para reCAPTCHA, hCaptcha, GeeTest, etc.

---

## 5. Consideraciones de despliegue

*   **Modo headless**: las extensiones estándar no se ejecutan en modo «headless real» (`--headless=new`). Usa `--headless=old` o un framebuffer virtual (Xvfb) en servidores Linux.
*   **Compatibilidad con proxy**: la mayoría de las extensiones respetan la configuración de proxy del sistema del navegador, definida mediante tu framework de automatización.

---

## 6. Conclusión

Al integrar la extensión de CaptchaSonic, reduces de forma notable la complejidad de gestionar desafíos interactivos en tus tareas de automatización de navegador.

Para soporte técnico adicional o solicitudes de integración personalizada, contacta con nuestro equipo a través del [panel](https://captchasonic.com/app).
