Pular para conteúdo

CapMonster

A integração com o serviço CapMonster Cloud permite que o Marvin resolva reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile e captcha de imagem automaticamente.

Para usar estas ações é necessário ter uma conta no CapMonster Cloud e uma chave de API válida (api_key).

Observação importante: a solução de reCAPTCHA e Turnstile normalmente expira rapidamente (tipicamente cerca de 2 minutos). Sempre resolva o captcha como a última ação antes de submeter o formulário ou validar a página.

Importante sobre retornos (variáveis de estado) - As ações expõem seus valores retornados como variáveis de estado que podem ser lidas pelo integrador. - Para acessar um valor retornado, atribua uma variável local à variável de estado usando o prefixo $. O nome deve ser exatamente igual à chave retornada pela ação.

Exemplo genérico:

# chama a action
capmonster.recaptcha_v2(browser, "MINHA_CHAVE")

# recupera o token retornado pela action
g_recaptcha_response = $g_recaptcha_response

A sitekey é obtida automaticamente da página atual. A busca usa primeiro o atributo data-sitekey. Se ele não existir, a action lê o parâmetro k do iframe do reCAPTCHA (recaptcha/api2/anchor ou recaptcha/enterprise/anchor).

Ações

As ações abaixo estão disponíveis no Marvin:

capmonster.recaptcha_v2

Resolve reCAPTCHA v2 presente na página atual.

A action envia uma tarefa RecaptchaV2Task ao CapMonster, consulta o resultado até ficar pronto e devolve o token. Com auto_inject=True, o token é inserido nos campos g-recaptcha-response da página (incluindo frames internos) e o callback do reCAPTCHA é executado.

Parâmetros:
  • browser — objeto do navegador (página) onde o reCAPTCHA está presente.
  • api_key — chave da conta CapMonster Cloud (string).
  • callback_function (opcional) — nome ou caminho da função JavaScript de callback usada pela página. Só é usado quando auto_inject é True.
  • isInvisible (opcional) — indica se o widget é um reCAPTCHA invisível. O valor é enviado ao CapMonster como informado.
  • auto_inject (opcional) — se True, injeta o token na página e executa o callback. O padrão é False: a action apenas retorna o token.
Retornar:
  • g_recaptcha_response — token de solução (string).

Como usar (exemplo):

# apenas obter o token
capmonster.recaptcha_v2(browser, "MINHA_CHAVE")
g_recaptcha_response = $g_recaptcha_response

# reCAPTCHA invisível, injetando o token e o callback da página
capmonster.recaptcha_v2(browser, "MINHA_CHAVE", isInvisible=True, auto_inject=True)

# callback explícito
capmonster.recaptcha_v2(browser, "MINHA_CHAVE", callback_function="onSuccess", auto_inject=True)

Exceções: - Sitekey não encontrada na página (data-sitekey nem iframe do reCAPTCHA). - Conta sem saldo (Account has zero balance). - Falha ao criar ou consultar a tarefa no CapMonster. - Falha ao executar um callback explícito depois de 3 tentativas. Sem callback_function, a ausência de callback não interrompe a action.

capmonster.recaptcha_v3

Resolve reCAPTCHA v3 presente na página atual.

A action envia uma tarefa RecaptchaV3TaskProxyless ao CapMonster, consulta o resultado até ficar pronto e devolve o token. Com auto_inject=True, o token é inserido nos campos g-recaptcha-response e o callback do reCAPTCHA é executado.

Parâmetros:
  • browser — objeto do navegador (página) onde o reCAPTCHA está presente.
  • api_key — chave da conta CapMonster Cloud (string).
  • callback_function (opcional) — nome ou caminho da função JavaScript de callback usada pela página. Só é usado quando auto_inject é True.
  • isEnterprise (opcional) — se True, resolve como reCAPTCHA Enterprise. O padrão é False.
  • auto_inject (opcional) — se True, injeta o token na página e executa o callback. O padrão é False: a action apenas retorna o token.
Retornar:
  • g_recaptcha_response — token de solução (string).

Como usar (exemplo):

# reCAPTCHA v3 padrão
capmonster.recaptcha_v3(browser, "MINHA_CHAVE")
g_recaptcha_response = $g_recaptcha_response

# reCAPTCHA Enterprise, injetando o token na página
capmonster.recaptcha_v3(browser, "MINHA_CHAVE", isEnterprise=True, auto_inject=True)

Exceções: - Sitekey não encontrada na página. - Conta sem saldo (Account has zero balance). - Falha ao criar ou consultar a tarefa no CapMonster. - Falha ao executar um callback explícito depois de 3 tentativas. Sem callback_function, a ausência de callback não interrompe a action.

capmonster.cloudflare_turnstile

Resolve Cloudflare Turnstile presente na página atual.

A action envia uma tarefa TurnstileTask ao CapMonster e devolve o token. Com auto_inject=True, o token é gravado nos campos cf-turnstile-response da página.

Parâmetros:
  • browser — objeto do navegador (página) onde o Turnstile está presente.
  • api_key — chave da conta CapMonster Cloud (string).
  • auto_inject (opcional) — se True, injeta o token nos campos cf-turnstile-response. O padrão é False: a action apenas retorna o token.
Retornar:
  • token_cloudflare — token de solução (string).

Como usar (exemplo):

# obter o token
capmonster.cloudflare_turnstile(browser, "MINHA_CHAVE")
token_cloudflare = $token_cloudflare

# injetar o token na página
capmonster.cloudflare_turnstile(browser, "MINHA_CHAVE", auto_inject=True)

Exceções: - Sitekey não encontrada na página. - Conta sem saldo (Account has zero balance). - Falha ao criar ou consultar a tarefa no CapMonster.

capmonster.image_to_text

Resolve um captcha de imagem a partir de um arquivo local ou de uma URL pública.

A imagem é convertida para Base64 e enviada ao CapMonster como ImageToTextTask. Informe image_path ou image_url. Se os dois forem informados, o arquivo local é usado.

Parâmetros:
  • api_key — chave da conta CapMonster Cloud (string).
  • image_url (opcional) — URL pública da imagem do captcha.
  • image_path (opcional) — caminho local do arquivo de imagem.
  • case (opcional) — se True, o reconhecimento diferencia maiúsculas e minúsculas. O padrão é False.
Retornar:
  • captcha — texto solucionado (string).

Como usar (exemplo):

# arquivo local
capmonster.image_to_text("MINHA_CHAVE", image_path="C:/temp/captcha.png")
captcha = $captcha

# URL pública, com diferenciação de maiúsculas e minúsculas
capmonster.image_to_text("MINHA_CHAVE", image_url="https://exemplo.com/captcha.png", case=True)
captcha = $captcha

Exceções: - Nem image_url nem image_path foram informados (Enter the image URL or path). - Conta sem saldo (Account has zero balance). - Falha ao baixar a imagem ou ao criar/consultar a tarefa no CapMonster.

Como o callback do reCAPTCHA é executado

As actions recaptcha_v2 e recaptcha_v3 só executam o callback quando auto_inject é True.

  • Sem callback_function, a action tenta descobrir o callback uma vez: atributo data-callback em elementos .g-recaptcha, ou funções registradas em ___grecaptcha_cfg. Se nenhum callback for encontrado, a execução continua e o token já injetado permanece disponível.
  • Com callback_function, a action tenta chamar essa função até 3 vezes, com intervalo de 0,5 segundo. Se todas as tentativas falharem, a action é interrompida.

A função de callback pode ser identificada de duas maneiras principais:

  • Elemento HTML com a classe g-recaptcha e atributo data-callback. Exemplo:
<input type="submit" class="g-recaptcha" data-callback="loginFn" onclick="validateForm" value="OK" data-sitekey="XXXXXXXXXXXXXXXXXXXXXXXX">
  • Definição via JavaScript usando grecaptcha.render, onde o parâmetro callback aponta para a função. Exemplo:
grecaptcha.render("recaptcha", {
    "sitekey": "XXXXXXXXXXXXXXXXXXXXXXXX",
    "callback": verifyCallbackCaptcha,
    "size": "invisible"
})

Se a página valida o reCAPTCHA por POST, em geral basta injetar o token (auto_inject=True) sem informar callback_function.