> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/pt-br/headless-browser/captcha-handling.md).

# Tratamento de CAPTCHA

Saiba mais sobre os mecanismos de detecção e tratamento de CAPTCHA do Headless Browser e como usá-los.

Por padrão, Oxylabs Headless Browser não faz **não** lida com CAPTCHAs automaticamente. Para ativar a detecção e o tratamento automáticos assim que uma página carregar, adicione `solve_captcha=true` à sua URL de conexão.

Se um site-alvo exibir desafios dinamicamente durante interações em várias etapas, ou se você precisar de monitoramento avançado de eventos e otimizações de velocidade, pode usar os parâmetros, eventos e técnicas documentados abaixo.

{% hint style="info" %}
**Observação:** As taxas de sucesso de acesso dependem muito do alvo. Os resultados podem variar com base na configuração específica do site-alvo, nos níveis de aplicação (por exemplo, rastreamento passivo de fingerprint vs. escalada ativa do desafio) e na reputação em tempo real do IP residencial da sessão.
{% endhint %}

## Monitorando eventos de CAPTCHA

Você pode monitorar o ciclo de vida do resolvedor. A extensão interna `oxylabs-runtime` do navegador emite eventos de status diretamente para o `window` objeto window do navegador. Ao registrar um ouvinte personalizado do evento "message", seu script pode rastrear esses eventos para pausar e retomar ações.

<table><thead><tr><th width="243">Tipo de evento</th><th>Descrição</th></tr></thead><tbody><tr><td><code>oxylabs-captcha-start</code></td><td>O resolvedor detectou um CAPTCHA e iniciou o processo de tratamento.</td></tr><tr><td><code>oxylabs-captcha-end</code></td><td>O resolvedor foi concluído com sucesso e tratou o desafio.</td></tr><tr><td><code>oxylabs-captcha-solve-end</code></td><td>Evento alternativo de conclusão emitido após o sucesso.</td></tr><tr><td><code>oxylabs-captcha-error</code></td><td>O resolvedor falhou ao tratar o desafio.</td></tr></tbody></table>

{% hint style="info" %}
A resolução automática está **desativada por padrão**. Acrescente `solve_captcha=true` à sua URL de conexão para ativar o tratamento automático e começar a emitir esses eventos.
{% endhint %}

### Exemplos de código

Estes exemplos mostram como injetar um `init` script para capturar eventos de CAPTCHA em tempo de execução antes da navegação da página, para que seu script pause durante o tratamento ativo.

{% tabs %}
{% tab title="Python (Playwright)" %}

```python
from playwright.sync_api import sync_playwright

username = "USERNAME_abc12"
password = "PASSWORD"
endpoint = "hb.oxylabs.io"
# solve_captcha=true ativa o tratamento e a emissão de eventos (desativado por padrão)
browser_url = f"wss://{username}:{password}@{endpoint}?solve_captcha=true"

def run():
    with sync_playwright() as p:
        browser = p.chromium.connect_over_cdp(browser_url)
        ctx = browser.contexts[0]
        page = ctx.new_page()

        # Injetar listener ANTES da navegação
        ctx.add_init_script("""
            window.addEventListener("message", (event) => {
                if (event.data && event.data.source === "oxylabs-runtime") {
                    window.__extensionStatus = event.data.type;
                }
            });
        """)

        page.goto("https://example.com/captcha-page", wait_until="domcontentloaded")

        # Aguarde o resolvedor concluir (faz polling do sinalizador de status)
        page.wait_for_function(
            """() => {
                const status = window.__extensionStatus;
                if (status === "oxylabs-captcha-error") {
                    throw new Error("CAPTCHA solving failed");
                }
                return status === "oxylabs-captcha-solve-end" || status === "oxylabs-captcha-end";
            }""",
            timeout=60000
        )
        print("CAPTCHA solved. Resuming automation...")
        browser.close()

if __name__ == "__main__":
    run()
```

{% endtab %}

{% tab title="JavaScript (Playwright)" %}

```javascript
import { chromium } from "playwright";

const username = "USERNAME_abc12";
const password = "PASSWORD";
const endpoint = "hb.oxylabs.io";
const browserUrl = `wss://${username}:${password}@${endpoint}?solve_captcha=true`;

(async () => {
    const browser = await chromium.connectOverCDP(browserUrl);
    const ctx = browser.contexts()[0];
    const page = await ctx.newPage();

    // Registrar script de inicialização para escutar eventos de oxylabs-runtime
    await ctx.addInitScript(() => {
        window.addEventListener("message", (e) => {
            if (e.data?.source === "oxylabs-runtime") {
                window.__extensionStatus = e.data.type;
            }
        });
    });

    await page.goto("https://example.com/captcha-page", { waitUntil: "domcontentloaded" });

    try {
        // Interrompa a execução do script até o CAPTCHA retornar um status de resolução positiva
        await page.waitForFunction(() => {
            const status = window.__extensionStatus;
            if (status === "oxylabs-captcha-error") {
                throw new Error("CAPTCHA solving failed");
            }
            return status === "oxylabs-captcha-solve-end" || status === "oxylabs-captcha-end";
        }, null, { timeout: 60000 });

        console.log("CAPTCHA solved. Resuming automation...");
    } catch (err) {
        console.error("Error during bypass execution:", err.message);
    } finally {
        await browser.close();
    }
})();
```

{% endtab %}

{% tab title="JavaScript (Puppeteer)" %}

```javascript
import puppeteer from "puppeteer";

const username = "USERNAME_abc12";
const password = "PASSWORD";
const endpoint = "hb.oxylabs.io";
const browserUrl = `wss://${username}:${password}@${endpoint}?solve_captcha=true`;

(async () => {
    const browser = await puppeteer.connect({ browserWSEndpoint: browserUrl });
    const page = await browser.newPage();

    // Alternativa do Puppeteer: avaliar na criação do documento
    await page.evaluateOnNewDocument(() => {
        window.addEventListener("message", (e) => {
            if (e.data?.source === "oxylabs-runtime") {
                window.__extensionStatus = e.data.type;
            }
        });
    });

    await page.goto("https://example.com/captcha-page", { waitUntil: "domcontentloaded" });

    try {
        await page.waitForFunction(() => {
            const status = window.__extensionStatus;
            if (status === "oxylabs-captcha-error") {
                throw new Error("CAPTCHA solving failed");
            }
            return status === "oxylabs-captcha-solve-end" || status === "oxylabs-captcha-end";
        }, { timeout: 60000 });

        console.log("CAPTCHA solved. Resuming automation...");
    } catch (err) {
        console.error("Error during bypass execution:", err.message);
    } finally {
        await browser.close();
    }
})();
```

{% endtab %}
{% endtabs %}

## Gatilhos manuais dinâmicos

Alguns alvos só exibem desafios CAPTCHA após ações do usuário (por exemplo, depois de clicar em um botão interativo de envio de formulário ou realizar rolagem dinâmica).

Você pode acionar programaticamente o tratador de CAPTCHA do Headless Browser a qualquer momento da sua sessão usando `window.postMessage` evento diretamente no objeto window:

```
window.postMessage({ action: "solve_captcha", type: "type_name" }, "*");
```

{% hint style="info" %}
Para saber mais sobre os tipos de CAPTCHA suportados, entre em contato com o suporte da Oxylabs ([chat ao vivo](https://oxylabs.io/) ou [email](mailto:support@oxylabs.io)) ou com seu Gerente de Conta Dedicado.
{% endhint %}

### Padrão de acionamento

Para elementos típicos, acione o resolvedor imediatamente após executar a ação do usuário:

```javascript
// Realize a interação com o formulário
await page.click("#form-submit-button");

// Acione a resolução para CAPTCHA em estágio tardio
await page.evaluate(() => {
    window.postMessage({ action: "solve_captcha", type: "type_name" }, "*");
});
```

{% hint style="info" %}
Para saber mais sobre os tipos de CAPTCHA suportados ou exceções para tipos específicos, entre em contato com o suporte da Oxylabs (chat ao vivo ou email) ou com seu Gerente de Conta Dedicado para obter mais detalhes.
{% endhint %}

## Otimização de velocidade

O tratamento de CAPTCHAs adiciona latência de execução mecânica. Ao raspar alvos que impõem verificações de CAPTCHA repetitivas, considere estes métodos para obter melhor desempenho:

<table data-header-hidden><thead><tr><th width="175"></th><th></th></tr></thead><tbody><tr><td><strong>Reutilizar sessões</strong></td><td>Depois que uma sessão de navegador remoto conclui um CAPTCHA em um domínio, a verificação é salva. Navegue repetidamente ou execute etapas adicionais da página na mesma sessão do navegador sem reativar rotinas de resolução de desafios.</td></tr><tr><td><strong>Múltiplas abas</strong></td><td>Em vez de conexões WebSocket separadas (que iniciam sandboxes distintos com pools de cookie vazios), execute tarefas concorrentes abrindo várias abas ou contextos dentro da sua sessão existente, para reduzir o tempo de conexão e verificação em todas as páginas.</td></tr><tr><td><strong>Ativar seletivamente</strong></td><td>Como <code>solve_captcha</code> está desativado por padrão, ative-o apenas (<code>solve_captcha=true</code>) para as conexões específicas que precisam dele, em vez de deixá-lo ativado durante todo o fluxo de trabalho — isso evita a latência de inicialização do resolvedor em páginas ou sessões que não enfrentam desafios CAPTCHA.</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.oxylabs.io/products/pt-br/headless-browser/captcha-handling.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.