Solvedor de CAPTCHA do CloakBrowser: Como Integrar o CapSolver com Automação de Navegador Playwright

Resumo

• O CloakBrowser inicia uma versão do Chromium através de uma API Python compatível com Playwright; o CapSolver lida com a tarefa de CAPTCHA e retorna um token ou resultado de reconhecimento de imagem.
• O CloakBrowser não é um serviço de resolução de CAPTCHA. A integração mantém o estado do navegador no CloakBrowser, envia apenas os parâmetros necessários do desafio para o CapSolver e submete o resultado através da mesma página do Playwright.
• Para um script existente do Playwright, a principal alteração do lado do navegador é substituir o launcher do Chromium padrão por from cloakbrowser import launch.
• Mantenha a URL da página, a chave do site, o proxy, os cookies, o local e o agente do usuário consistentes quando um desafio estiver vinculado à sessão atual.
• Um token retornado é um resultado intermediário. Trate o fluxo como bem-sucedido somente após a página de destino ou aplicativo autorizado aceitá-lo.

O que o CloakBrowser e o CapSolver fazem

CloakBrowser é um pacote de navegador baseado em Chromium para automação do Playwright e Puppeteer. Seu repositório oficial descreve alterações no nível de código-fonte nos sinais do navegador, como canvas, WebGL, áudio, fontes, GPU, tela, WebRTC e comportamento relacionado à automação. O launcher em Python retorna um objeto Browser padrão do Playwright, então métodos familiares como new_page(), localizadores, evaluate(), cliques e operações de formulário permanecem disponíveis.

O CloakBrowser não resolve CAPTCHAs. O CapSolver fornece esse serviço separado: seu aplicativo cria uma tarefa com os parâmetros do desafio, recebe uma solução e usa a página atual para submetê-la. Essa divisão é importante porque a gestão do ambiente do navegador e o tratamento de CAPTCHA têm entradas e modos de falha diferentes.

As responsabilidades são as seguintes:

CloakBrowser
  -> inicia o Chromium e mantém cookies, proxy, página e contexto do navegador
  -> lê os parâmetros do desafio exibidos para a sessão atual

CapSolver
  -> recebe o tipo de tarefa suportado e os parâmetros do desafio necessários
  -> retorna um token ou resultado de reconhecimento de imagem

API do Playwright
  -> coloca o resultado de volta na mesma página
  -> invoca o retorno de chamada esperado ou submete o formulário
  -> verifica a resposta da página final ou do aplicativo

Se você precisar de um refresher sobre o Playwright antes de integrar os dois serviços, consulte o glossário do Playwright e o guia de automação do navegador do Playwright.

Pré-requisitos

Use esse fluxo somente em sites e aplicações que você possua ou esteja autorizado a testar ou automatizar. Você precisará de:

• Python 3.9 ou mais recente;
• instalação e licença do CloakBrowser ou configuração de avaliação suportada;
• conta e chave de API do CapSolver;
• URL de destino e parâmetros do desafio da página que você está autorizado a automatizar.

Instale os pacotes Python:

pip install cloakbrowser capsolver

Quanto à licença do CloakBrowser, o repositório atual documenta cloakbrowser login para uma configuração interativa e a variável de ambiente CLOAKBROWSER_LICENSE_KEY para CI ou servidores. Mantenha as credenciais dos fornecedores fora do controle de fonte. Variáveis de ambiente ou um gerenciador de segredos são mais seguros do que comprometer chaves literais.

Etapa 1: Iniciar o CloakBrowser com a API do Playwright

O seguinte exemplo mínimo abre uma página, lê seu título e fecha o navegador:

from cloakbrowser import launch

browser = launch(
    headless=False,
    humanize=True,
    license_key="cb_...",
)

page = browser.new_page()
page.goto("https://example.com", wait_until="domcontentloaded")
print(page.title())
browser.close()

As opções do launcher controlam o ambiente do navegador:

Para desafios vinculados à sessão, evite alterar o proxy, o agente do usuário, os cookies ou o contexto do navegador entre ler o desafio e submeter sua solução. A FAQ do CapSolver sobre fingerprinting de navegador na segurança da web explica por que múltiplos sinais do navegador podem ser avaliados juntos.

Etapa 2: Criar uma Tarefa reCAPTCHA v2 do CapSolver

O fluxo básico da SDK Python define a chave de API e envia um objeto de tarefa suportado. Este exemplo usa valores públicos do reCAPTCHA v2 do Google:

import capsolver

capsolver.api_key = "CAP-..."

solution = capsolver.solve(
    {
        "type": "ReCaptchaV2TaskProxyLess",
        "websiteURL": "https://www.google.com/recaptcha/api2/demo",
        "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    }
)

token = solution.get("gRecaptchaResponse")
if not isinstance(token, str) or not token:
    raise RuntimeError(f"CapSolver não retornou um token reCAPTCHA: {solution}")

print("Token recebido")

Os campos importantes são:

Verifique a documentação do reCAPTCHA v2 do CapSolver antes da implantação em produção e use os valores da página ativa em vez de copiar parâmetros de demonstração. O guia mais longo sobre como resolver o reCAPTCHA v2 cobre a seleção de tarefa e campos de resposta em mais detalhes.

Resgate seu código promocional do CapSolver

Aumente seu orçamento de automação instantaneamente!
Use o código promocional CAP26 ao recarregar sua conta do CapSolver para obter um bônus adicional de 5% em cada recarga — sem limites.
Resgate-o agora em seu Painel do CapSolver

Etapa 3: Retornar o Token através da Mesma Página do CloakBrowser

O exemplo completo abaixo mantém a navegação e a submissão do token dentro de uma única página do CloakBrowser. O seletor CSS e o comportamento de submissão são específicos para a demonstração pública; um aplicativo real pode usar um retorno de chamada, um campo gerenciado por um framework ou outro fluxo de formulário.

import re

import capsolver
from cloakbrowser import launch


def inject_recaptcha_token(page, token):
    if not isinstance(token, str) or not token:
        raise ValueError("Um token reCAPTCHA não vazio é necessário")

    page.evaluate(
        """
        (token) => {
            const textarea = document.getElementById('g-recaptcha-response');
            if (!textarea) {
                throw new Error('g-recaptcha-response não foi encontrado');
            }
            textarea.value = token;
        }
        """,
        token,
    )

    with page.expect_navigation(
        wait_until="domcontentloaded",
        timeout=30_000,
    ):
        page.click("#recaptcha-demo-submit")

    return page.content()


def main():
    capsolver.api_key = "CAP-..."  # SUA_CHAVE_API_DO_CAPSOLVER

    browser = launch(
        license_key="cb_...",  # SUA_LICENÇA_DO_CLOAKBROWSER
        headless=False,
        locale="en-US",
    )

    try:
        page = browser.new_page()
        page.goto(
            "https://www.google.com/recaptcha/api2/demo",
            wait_until="domcontentloaded",
            timeout=60_000,
        )

        solution = capsolver.solve(
            {
                "type": "ReCaptchaV2TaskProxyLess",
                "websiteURL": page.url,
                "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
            }
        )

        token = solution.get("gRecaptchaResponse")
        result_page = inject_recaptcha_token(page, token)

        match = re.search(
            r'<div class="recaptcha-success">(.*?)</div>',
            result_page,
        )
        print(match.group(1) if match else "Verificação falhou")
    finally:
        browser.close()


if __name__ == "__main__":
    main()

Execute-o como um script Python normal:

python cloakbrowser-capsolver.py

Em produção, carregue as chaves de variáveis de ambiente, adicione tentativas limitadas ao redor de falhas temporárias da API ou navegação, registre os IDs das tarefas do CapSolver sem registrar segredos e valide o resultado final do negócio. O CapSolver também fornece uma FAQ focada em integrar resolução de CAPTCHA com Playwright ou Puppeteer.

Etapa 4: Tratar CAPTCHAs de Imagem com ImageToTextTask

Alguns fluxos de teste autorizados exibem uma CAPTCHA como uma imagem em vez de um widget baseado em token. Nesse caso, capture ou extraia a imagem, converta-a em Base64 sem o prefixo da URL de dados e envie-a para ImageToTextTask.

A captura de tela abaixo do fluxo original mostra o elemento da imagem e o campo de entrada na demonstração de recursos do BotDetect:

import capsolver
from cloakbrowser import launch


TARGET_URL = "https://captcha.com/demos/features/captcha-demo.aspx"

browser = launch(headless=False, humanize=True)

try:
    page = browser.new_page()
    page.goto(TARGET_URL, wait_until="domcontentloaded")

    image_src = page.locator("#demoCaptcha_CaptchaImage").get_attribute("src")
    if not image_src or "," not in image_src:
        raise RuntimeError("A imagem CAPTCHA não é uma URL de dados")

    base64_image = image_src.split(",", 1)[1].replace("\n", "")

    solution = capsolver.solve(
        {
            "type": "ImageToTextTask",
            "websiteURL": page.url,
            "module": "common",
            "body": base64_image,
        }
    )

    text = solution.get("text")
    if not isinstance(text, str) or not text:
        raise RuntimeError(f"CapSolver não retornou texto OCR: {solution}")

    page.locator("#captchaCode").fill(text)
    page.locator("#validateCaptchaButton").click()
finally:
    browser.close()

Os seletores estão intencionalmente ligados à página de demonstração. Inspeção da página alvo autorizada e uso de seus seletores de imagem, entrada e submissão reais.

Várias imagens e o módulo de número

ImageToTextTask pode usar diferentes módulos para formatos de imagem suportados. A revisão original incluiu esta visão geral do módulo, preservada aqui para referência:

Quando um módulo suportado aceita várias imagens, envie a matriz documentada para esse módulo e leia as respostas correspondentes:

solution = capsolver.solve(
    {
        "type": "ImageToTextTask",
        "module": "number",
        "images": [base64_image],
    }
)

answers = solution["answers"]

Nomes de módulo, campos de solicitação e formatos suportados podem mudar, então verifique-os contra a documentação do ImageToTextTask. Para um padrão mais amplo da API Python, veja como integrar uma API de resolução de CAPTCHA em Python.

O que Muda para o reCAPTCHA v3?

A arquitetura do navegador permanece a mesma, mas a tarefa do CapSolver e os parâmetros da página devem corresponder a uma implementação v3. Em particular:

1. Use o tipo de tarefa reCAPTCHA v3 suportado pelo CapSolver.
2. Forneça o valor da ação esperado pela página quando a integração usar uma.
3. Leia a URL e a chave do site da página ativa em vez de de um exemplo irrelevante.
4. Mantenha o token resultante na mesma sessão do navegador e submeta-o antes que expire.
5. Verifique a resposta do aplicativo. Um score ou token retornado por uma API não garante que o aplicativo de destino aceite a solicitação.

Não abra uma nova página sem os cookies e estado da sessão original apenas para submeter o token. Isso quebra o contexto que o aplicativo de destino pode usar ao avaliar o resultado.

Solução de Problemas com o CloakBrowser e o CapSolver

O script inicia o Chromium padrão do Playwright

Este código inicia o Chromium embutido do Playwright, não o CloakBrowser:

from playwright.sync_api import sync_playwright

pw = sync_playwright().start()
browser = pw.chromium.launch()

Use o launcher do CloakBrowser em vez disso:

from cloakbrowser import launch

browser = launch()

De acordo com o repositório do CloakBrowser, playwright install-deps chromium pode ser útil no Linux quando bibliotecas do sistema estão faltando. Executar playwright install chromium é diferente: ele baixa o navegador do Playwright e não corrige o caminho de inicialização do CloakBrowser.

O CapSolver retorna um token, mas a página o rejeita

Verifique cada limite na ordem:

• websiteURL é a URL completa usada pela página ativa;
• websiteKey pertence a essa página;
• o tipo de tarefa selecionado e a ação opcional correspondem ao desafio;
• o token é escrito no campo esperado ou passado para o retorno de chamada da página;
• a página não foi atualizada ou substituiu o desafio;
• cookies, proxy, agente do usuário e contexto do navegador permanecem consistentes;
• a resposta da página final ou do aplicativo confirma a aceitação.

A tarefa de imagem não retorna texto

Confirme que o corpo da imagem é um Base64 válido, o prefixo da URL de dados foi removido, o módulo escolhido suporta a imagem e o campo de resposta corresponde à documentação atual. Capture o código de erro e o ID da tarefa do CapSolver para depuração, mas não registre chaves de API ou dados sensíveis da página.

A navegação trava após a submissão

Não toda submissão causa uma navegação completa. Alguns sites atualizam o DOM ou fazem uma solicitação XHR em vez disso. Substitua expect_navigation() pela condição que realmente representa o sucesso: um localizador tornando-se visível, uma mudança de URL, um evento de resposta ou um elemento de status específico do aplicativo. A referência oficial da API do Browser do Playwright é a melhor fonte para o comportamento atual da API.

Automação Responsável e Confiável

Sistemas CAPTCHA são mecanismos de controle de acesso e prevenção de abuso. Use o CapSolver e o CloakBrowser apenas para automatização legal em sistemas que você possui ou tem permissão explícita para testar. Respeite os termos do site, limites de taxa, requisitos de privacidade e leis aplicáveis. Não use automatização para acessar dados privados, criar tráfego abusivo ou interferir em outros usuários.

Para testes de qualidade (QA) e monitoramento, prefira ambientes de teste dedicados e chaves de teste do provedor quando disponíveis. Registre a URL da página, tipo de tarefa, ID da tarefa, tempo decorrido e status final da aplicação para que falhas possam ser rastreadas sem armazenar credenciais ou dados pessoais. O guia de automação CAPTCHA para testes de qualidade fornece padrões adicionais para fluxos de trabalho de teste controlados.

Construa Fluxos de Trabalho de Automação Confiáveis com CapSolver

O CloakBrowser pode fornecer o ambiente do navegador compatível com Playwright, enquanto o CapSolver lida com as tarefas CAPTCHA suportadas. Manter essas responsabilidades separadas torna o fluxo mais fácil de testar: leia o desafio da página ativa, solicite a solução correspondente, envie-a no mesmo contexto e verifique o resultado da aplicação.

Tente o CapSolver para um fluxo autorizado do CloakBrowser ou Playwright e consulte a documentação atual antes de mover o código de demonstração para produção.

Perguntas Frequentes

P: O CloakBrowser é um solucionador de CAPTCHA?

Não. O CloakBrowser fornece um navegador Chromium e uma interface de automação compatível com Playwright. Um serviço separado, como o CapSolver, lida com as tarefas CAPTCHA suportadas.

P: Um script existente de Playwright pode usar o CloakBrowser?

Normalmente, sim. Substitua o caminho de inicialização do navegador por from cloakbrowser import launch, depois continue usando o Browser do Playwright retornado, páginas, localizadores e métodos de avaliação. Teste opções e dependências específicas do navegador no seu ambiente.

P: Por que o resultado do CAPTCHA deve ser enviado no mesmo contexto do navegador?

O aplicativo de destino pode associar um desafio a cookies, endereço de proxy, sinais do navegador, URL ou outros dados de sessão. Trocar de contexto pode tornar parâmetros de desafio válidos inconsistentes.

P: Onde encontro a chave do site reCAPTCHA?

Use a chave configurada na página que você está autorizado a automatizar. Ela pode aparecer no markup do widget ou nos scripts da página. Não copie uma chave de um tutorial ou domínio não relacionado.

P: Um token do CapSolver garante sucesso?

Não. Um token é um resultado intermediário. A condição de sucesso final é a resposta do aplicativo ou página de destino após o token ser submetido corretamente e no tempo certo.

P: A integração pode lidar com CAPTCHAs de imagem?

A ImageToTextTask do CapSolver suporta módulos de reconhecimento de imagem documentados. Extraia a imagem da página autorizada, envie o payload Base64 necessário e insira o texto retornado pela mesma página do CloakBrowser.

P: As chaves de API e licença devem aparecer no script?

Não. Os exemplos usam placeholders reconhecíveis. O código de produção deve ler segredos de variáveis de ambiente ou um gerenciador de segredos e nunca deve comprometê-los no controle de versão.

P: Como devo testar essa integração de forma segura?

Comece com demonstrações do provedor ou com uma aplicação que você controle. Use taxas de solicitação limitadas, registre IDs de tarefa e resultados finais, e avance para um site de produção apenas quando tiver autorização e uma necessidade operacional clara.