Se o reCAPTCHA v3 está devolvendo uma pontuação baixa na sua aplicação, tentar manipular o algoritmo do Google não resolve — a nota é recalculada a cada execução e depende de sinais que só o Google controla. O caminho confiável é outro: montar um ambiente de QA em staging, medir como o seu próprio fluxo se comporta diante do desafio e usar a CaptchaAI como solver de fallback quando o token automatizado não é suficiente. Este guia mostra como montar esse ambiente passo a passo, com dados fictícios e endpoints isolados de produção.
Por que medir em vez de tentar manipular a pontuação
O reCAPTCHA v3 atribui uma nota entre 0,0 e 1,0 a cada execução, com base em sinais de comportamento e reputação que o Google reavalia continuamente. Não existe um ajuste único que "trave" a pontuação em um valor alto — e testar tentativas de manipulação em produção, contra usuários reais, é arriscado e não gera dados confiáveis. Por isso, a abordagem que funciona na prática é diferente: reproduzir o formulário protegido em um ambiente próprio, medir a nota que a sua aplicação recebe hoje e usar a CaptchaAI para obter um token válido de fallback quando esse fluxo automatizado não passa pelo desafio. A CaptchaAI não define nem garante a pontuação — quem atribui a nota é o Google; o papel da API é devolver um token utilizável quando o teste automatizado precisa continuar.
Escopo e limites deste guia
Este guia vale para ambientes próprios, QA, staging ou pré-produção com autorização explícita da sua equipe. Os exemplos usam páginas internas, dados fictícios e endpoints de validação controlados por vocês — não há orientação para medir ou automatizar formulários de terceiros, filas públicas ou fluxos de compra reais. O objetivo é entender o comportamento de pontuação da sua própria aplicação, com contas de teste e sem impacto em usuários reais.
Monte o ambiente de QA em staging
Crie uma página interna com sitekey de QA, um usuário fictício e um payload previsível — ou seja, sempre o mesmo conjunto de campos e ações, para que qualquer variação na pontuação venha do ambiente, não do formulário. Aponte essa página para um endpoint de verificação separado do de produção. Se o runner de QA roda em nuvem, escolha uma região próxima ao público real do formulário: para tráfego brasileiro, uma região como sa-east-1 (São Paulo) evita que a latência da própria infraestrutura distorça o tempo de resposta medido.
Defina dados fictícios e endpoints isolados
Use identificadores previsíveis, como qa_user_001, qa_session_001 e qa_case_001, para reconhecer rapidamente qual execução gerou qual resultado. O backend deve aceitar apenas tokens vinculados ao domínio de staging e gravar os resultados em uma tabela de testes separada da de produção — isso evita que uma falha no teste contamine métricas ou relatórios reais.
Envie a tarefa para a CaptchaAI a partir do runner de QA
Envie a tarefa a partir do runner autorizado e registre o ID retornado para rastrear o teste do início ao fim:
import os, time, requests
API_KEY = os.environ['CAPTCHAAI_API_KEY']
SITEKEY = os.environ['QA_CAPTCHA_SITEKEY']
def criar_tarefa_captcha(pageurl):
resposta = requests.post('https://ocr.captchaai.com/in.php', data={
'key': API_KEY,
'method': 'userrecaptcha',
'googlekey': SITEKEY,
'pageurl': pageurl,
'json': 1,
}).json()
return resposta['request']
def aguardar_resultado(task_id):
while True:
time.sleep(5)
resposta = requests.get('https://ocr.captchaai.com/res.php', params={
'key': API_KEY,
'action': 'get',
'id': task_id,
'json': 1,
}).json()
if resposta.get('status') == 1:
return resposta['request']
task_id = criar_tarefa_captcha('https://staging.example.com/captcha-demo')
token_qa = aguardar_resultado(task_id)
print({'token_recebido': bool(token_qa)})
Valide o token no backend de teste
Depois de receber o token, encaminhe-o para um endpoint interno, como https://staging.example.com/qa-captcha/verify. O backend valida a resposta junto ao provedor do CAPTCHA e retorna apenas um resultado de teste — nenhuma ação de produção deve depender desse endpoint.
Registre logs para rastreabilidade
Registre sitekey, pageurl, tipo de CAPTCHA, tempo de envio, tempo de resposta, status do backend e o identificador do caso de QA. Esses campos são suficientes para depurar regressões sem expor dados sensíveis. Se o time guardar esses registros por muito tempo ou combiná-los com dados de sessão de usuários reais, considere as obrigações da LGPD (ou do RGPD, para equipes em Portugal) antes de definir a política de retenção — na dúvida, mantenha os logs de QA isolados de qualquer dado pessoal.
Resolva problemas comuns no teste
Se o teste falhar, confirme, nessa ordem: a sitekey usada, o domínio de staging autorizado, a expiração do token (o reCAPTCHA v3 expira poucos minutos após ser emitido), o relógio do runner e possíveis diferenças entre o que o navegador envia e o que a API recebe. Faça novas tentativas com backoff exponencial apenas dentro da suíte de QA — nunca contra o domínio de produção.
Checklist antes de publicar a mudança
Antes de publicar a mudança testada, confirme que: a documentação aponta para o ambiente próprio, não para produção; os exemplos usam dados fictícios; nenhum endpoint de produção é acionado pelo teste; e os logs têm correlação suficiente para auditoria. A página de staging precisa ter domínio autorizado, sitekey esperada, configuração de backend separada e uma política clara de expiração. Como o resultado varia entre execuções, trate cada número como uma amostra interna: repita a medição, anote a janela de execução e compare apenas cenários equivalentes — mesmo horário, mesmo ambiente, mesmo conjunto de dados fictícios.
Perguntas frequentes
Por que a pontuação muda entre uma execução e outra?
O reCAPTCHA v3 reavalia sinais de sessão e comportamento a cada chamada — cookies, histórico da página e padrão de navegação mudam de uma execução para a outra, mesmo em staging. Trate cada medição como uma amostra e repita o teste algumas vezes antes de tirar conclusões.
A CaptchaAI garante uma pontuação alta no reCAPTCHA v3?
Não. A pontuação é atribuída pelo Google, não pela CaptchaAI. A API funciona como solver de fallback: quando o seu fluxo automatizado não consegue obter um token válido sozinho, a CaptchaAI resolve o desafio e devolve um token utilizável — sem prometer uma nota específica.
Preciso de um navegador real para chamar a API?
Não. A chamada para in.php/res.php é uma requisição HTTP simples, como no exemplo em Python acima. Um navegador só entra em cena se o próprio formulário exigir grecaptcha.execute() no cliente — nesse caso, rode o teste dentro do seu pipeline de QA de navegador, com a mesma separação de ambiente.
Com que frequência devo repetir a medição?
Sempre que houver mudança no formulário, no domínio de staging ou na versão do reCAPTCHA. Fora isso, repita a medição periodicamente — comparar apenas execuções feitas em condições equivalentes evita conclusões erradas causadas pelo ruído normal da pontuação.
Onde devo registrar os resultados dos testes?
Em uma tabela de testes separada de produção, com sitekey, pageurl, tempos de resposta e status do backend. Nunca misture esses registros com dados de sessão de usuários reais — trate a retenção desses logs conforme as obrigações da LGPD (ou RGPD) da sua empresa.
Guias relacionados
- Início rápido da CaptchaAI
- Testes QA autorizados de CAPTCHA
- Testes de endpoint CAPTCHA em formulários próprios
- Depuração: navegador falha e API funciona
- Como resolver reCAPTCHA v2 com a API
- Como resolver Cloudflare Turnstile com a API
- Como resolver GeeTest v3 com a API
Meça a pontuação do reCAPTCHA v3 no seu ambiente de QA e use a CaptchaAI como solver de fallback nos testes.
