> 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/tratamento-de-captcha.md).

# Tratamento de CAPTCHA

Por padrão, o Oxylabs Headless Browser detecta e lida automaticamente com CAPTCHAs assim que uma página carrega. Não é necessária nenhuma configuração ou definição de parâmetros. 

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 no acesso dependem muito do alvo. Os resultados podem variar com base na configuração específica do site-alvo, nos níveis de imposiçã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` da extensão do navegador transmite eventos de status diretamente para o objeto `window` . Ao registrar um listener de evento personalizado "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 concluiu 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á **habilitada por padrão**. Se você adicionar `solve_captcha=false` à sua URL de conexão, o tratamento automático será desativado e esses eventos não serão emitidos.
{% 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 = "ubc.oxylabs.io"
# Garanta que solve_captcha=true esteja ativo (padrão) para emitir eventos
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()

        # Injete o listener ANTES da navegação
        """
            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 (consulta a flag 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 = "ubc.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();

    // Registre o script init para ouvir eventos 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é que o CAPTCHA retorne 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 = "ubc.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: avalie 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 %}

## Acionadores manuais dinâmicos

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

Você pode acionar programaticamente o manipulador de CAPTCHA do Headless Browser a qualquer momento na sua sessão usando `window.postMessage` evento diretamente para o 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 o 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
// Execute a interação com o formulário
await page.click("#form-submit-button");

// Acione a resolução para CAPTCHA em estágio avançado
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](https://oxylabs.io/) ou [email](mailto:support@oxylabs.io)) ou com o seu Gerente de Conta Dedicado para mais detalhes.
{% endhint %}

## Otimização de velocidade

O tratamento de CAPTCHAs adiciona latência de execução mecânica. Ao fazer scraping de alvos que impõem barreiras repetitivas de CAPTCHA, considere estes métodos para 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 remota do navegador completa um CAPTCHA em um domínio, a verificação é salva. Navegue repetidamente ou execute etapas adicionais da página dentro da mesma sessão do navegador sem reativar rotinas de resolução de desafios.</td></tr><tr><td><strong>Várias abas</strong> </td><td>Em vez de conexões WebSocket separadas (que iniciam sandboxes distintas com pools de cookie vazios), execute tarefas simultâneas 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>Desativação adaptativa</strong></td><td>Depois que um sinal confiável de confiança da sessão tiver sido estabelecido, desative as verificações do resolvedor em segundo plano com <code>solve_captcha=false</code>, para evitar a latência de inicialização do processo para domínios nos quais suas sessões já passam livremente.</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/tratamento-de-captcha.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.