Integrar a CaptchaSonic aos seus fluxos de automação de navegador permite contornar desafios de CAPTCHA complexos sem intervenção manual. Este guia cobre a instalação, a configuração e o uso da extensão da CaptchaSonic em ambientes automatizados.

> [!TIP]
> **Método preferido**: para automação em grande escala, recomendamos usar a nossa API diretamente. No entanto, a extensão de navegador é ideal para ferramentas como Selenium, Puppeteer e Playwright, em que um ambiente de navegador real é necessário.

---

## 1. Primeiros passos

Antes de usar a extensão nos seus scripts de automação, você precisa de uma API key válida do seu dashboard da CaptchaSonic.

1.  **Criação de conta**: cadastre-se em [captchasonic.com](https://captchasonic.com).
2.  **Obtenha a API Key**: faça login no seu [Dashboard](https://captchasonic.com/app) e copie a sua API key exclusiva.

![Painel da CaptchaSonic](/guides/CR/guide.7.png)

---

## 2. Instalação e configuração

### Para navegadores Chrome/baseados em Chromium

Frameworks de automação frequentemente exigem uma API key "fixa no código" caso você não use um perfil de navegador persistente.

1.  **Baixe o código-fonte**: clone ou baixe o [repositório da extensão CaptchaSonic](https://github.com/Captcha-Sonic/CaptchaSonic-Extension/releases/latest).
2.  **Configure a API key**:
    *   Acesse a pasta `config` dentro do código-fonte da extensão.
    *   Abra o arquivo de configuração padrão (geralmente `config.json` ou similar).
    *   Cole a sua API key no campo `apiKey`.
3.  **Carregando no Chrome**:
    *   Abra `chrome://extensions/`.
    *   Ative o **Modo do desenvolvedor**.
    *   Clique em **Load unpacked** e selecione a pasta da extensão modificada.

> [!IMPORTANT]
> Certifique-se de que o seu framework de automação esteja configurado para permitir o carregamento de extensões descompactadas. No Selenium, isso é feito por meio de `ChromeOptions`.

### Para Firefox

1.  **Baixe o XPI**: instale pela [loja de complementos do Firefox](https://addons.mozilla.org/en-US/firefox/addon/captchasonic/), ou baixe a versão mais recente em [Releases da extensão CaptchaSonic](https://github.com/Captcha-Sonic/CaptchaSonic-Extension/releases/latest).
2.  **Instalação manual**: acesse `about:addons`, clique no ícone de engrenagem e selecione **Install Add-on From File**.

---

## 3. Integração com frameworks de automação

Para usar a extensão no seu código, você precisa especificar o caminho da pasta ou do arquivo da extensão.

### 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. Configurando parâmetros

No popup da extensão ou no arquivo de configuração, você pode ajustar finamente a forma como os CAPTCHAs são tratados:

*   **Auto-Solve**: dispara automaticamente o processo de resolução quando um CAPTCHA é detectado.
*   **Solve Delay**: adiciona um atraso natural antes da resolução para imitar o comportamento humano.
*   **Target Types**: ativa/desativa solvers específicos para reCAPTCHA, hCaptcha, GeeTest, etc.

---

## 5. Considerações de implantação

*   **Modo headless**: extensões padrão não funcionam no modo "True Headless" (`--headless=new`). Use `--headless=old` ou um framebuffer virtual (Xvfb) em servidores Linux.
*   **Suporte a proxy**: a maioria das extensões respeita as configurações de proxy do sistema do navegador, definidas pelo seu framework de automação.

---

## 6. Conclusão

Ao integrar a extensão da CaptchaSonic, você reduz significativamente a complexidade de lidar com desafios interativos nas suas tarefas de automação de navegador.

Para suporte técnico adicional ou pedidos de integração personalizada, entre em contato com a nossa equipe pelo [Dashboard](https://captchasonic.com/app).
