WP reCAPTCHA Forms

🇺🇸 Read this in English → README-EN.md

Protege os formulários do WordPress, do WooCommerce e do plugin Newsletter com o reCAPTCHA do Google — com política de falha configurável e sem quebrar cache de página.

• Requer: PHP 7.4+ · WordPress 6.0+ · (opcional) WooCommerce 7.0+ para o checkout clássico e 8.3+ para o Blocks
• Licença: GPL-2.0-or-later
• Estado: em desenvolvimento, ainda sem release pública

---

Índice

• Por que este plugin existe
• Formulários suportados
• Instalação
• Obtendo as chaves do Google
• Configuração
• Quando a verificação não é possível
• Privacidade
• Consentimento e CMP
• Kill switch
• API pública
• FAQ
• Traduções
• Licença

---

Por que este plugin existe

A tese é cobertura, não sofisticação. Não existe plugin gratuito que cubra, junto e no mesmo lugar, comentário + registro + login + recuperação de senha + newsletter + checkout do WooCommerce (clássico e Blocks) + avaliações de produto, com reCAPTCHA v3 e v2. Existem plugins que fazem alguns desses formulários muito bem, e planos pagos que fazem o resto. Este faz a lista inteira.

O que ele não faz, dito na abertura para você não descobrir depois:

• Um único threshold de score, global. Isso é decisão de design, não limitação: um threshold por formulário multiplica a superfície de configuração e a persona que precisa dele é rara. Se você precisa, o filtro wp_recaptcha_forms_verdict te dá a decisão inteira.
• Sem telemetria, sem relatórios, sem histórico de bloqueios. Não há tabela nova no banco. O que existe são dois contadores em transient de uma hora, usados só para um aviso de diagnóstico, e que morrem sozinhos.
• Não é aconselhamento jurídico. O texto de privacidade pronto (abaixo) é um ponto de partida, e não torna a sua instalação conforme à LGPD ou ao GDPR.

---

Formulários suportados

Origem	Formulário	form_id	Observação
WordPress	Comentários	wp_comment	Não se aplica a avaliações de produto do Woo (essas têm linha própria)
WordPress	Login	wp_login	Só o formulário HTML do wp-login.php. XML-RPC, REST, WP-CLI, cron e usuário já logado ficam de fora
WordPress	Registro de usuário	wp_register
WordPress	Recuperação de senha	wp_lostpassword
Newsletter (Stefano Lissa)	Inscrição	newsletter_subscribe
WooCommerce	Checkout	woocommerce_checkout	Cobre o clássico (shortcode) e o Blocks (Store API) — os dois caminhos, com o mesmo veredito
WooCommerce	Avaliações de produto	woocommerce_review
WooCommerce	Recuperação de senha (Minha conta)	woocommerce_lostpassword

Fora de escopo, de propósito: redefinição de senha por link do e-mail (o link já é o fator de autenticação) e qualquer caminho de autenticação que não seja o formulário HTML do wp-login.php.

---

Instalação

1. Baixe o .zip da página de releases.
2. No painel: Plugins → Adicionar novo → Enviar plugin, escolha o .zip e instale.
3. Ative.
4. Vá em Configurações → WP reCAPTCHA Forms e informe as chaves.

Até você informar a site key e a secret key, o plugin fica em estado "ainda não configurado": não imprime campo, não carrega script e não bloqueia nada.

---

Obtendo as chaves do Google

Existem dois caminhos, e eles não produzem chaves intercambiáveis.

Verificado em 2026-09-09. O Google reorganiza estas páginas com alguma frequência; se algum link abaixo mudar, abra uma issue.

Caminho 1 — console clássico do reCAPTCHA · recomendado

https://www.google.com/recaptcha/admin

1. Entre com uma Conta Google.
2. Clique em + para registrar um site novo.
3. Rótulo: qualquer nome que te ajude a achar depois.
4. Tipo: escolha reCAPTCHA v3 (recomendado) ou reCAPTCHA v2 → "Não sou um robô".
5. Domínios: o domínio do site, sem https:// e sem barra final. Acrescente também os domínios de staging, se houver — errar aqui produz exec-error no navegador do visitante, não um erro no seu painel.
6. Aceite os termos e envie.
7. Copie a site key e a secret key.

⚠️ O Google marcou este console como em depreciação, empurrando novos projetos para o reCAPTCHA Enterprise no Google Cloud. Ele continua funcionando e continua gratuito, e é por isso que segue sendo o caminho recomendado aqui — mas conte com uma migração no futuro.

Caminho 2 — reCAPTCHA Enterprise via Google Cloud Console

https://console.cloud.google.com/security/recaptcha (documentação: https://cloud.google.com/recaptcha/docs/create-key-website)

1. Crie ou selecione um projeto no Google Cloud.
2. É necessário habilitar o faturamento no projeto. Sem eufemismo: o Google exige um cartão cadastrado, mesmo dentro da cota gratuita. Há uma cota mensal gratuita generosa para sites pequenos, mas o cadastro é obrigatório e o excedente é cobrado.
3. Ative a API reCAPTCHA Enterprise.
4. Crie uma chave do tipo Website, escolhendo entre pontuação (equivalente ao v3) ou caixa de seleção (equivalente ao v2).
5. Registre os domínios.
6. A site key aparece na listagem. A secret key é a chave de API legada; se você for usar este plugin, gere-a em Configurações legadas / Legacy secret key na mesma tela da chave.

Qual escolher

	Console clássico	Enterprise
Custo	gratuito, sem cartão	exige faturamento habilitado
Complexidade	6 cliques	projeto GCP, API, IAM
Futuro	em depreciação	é para onde o Google está indo
Recomendação para este plugin	sim	só se você já vive no GCP

Um aviso honesto sobre a validação de chave

Ao salvar uma secret key nova, o plugin a testa contra o Google na hora. Essa sonda pega o erro grosseiro — secret com um caractere trocado, secret colada no campo errado (invalid-input-secret).

Ela NÃO detecta um par site key / secret key vindo de projetos diferentes. O endpoint de verificação do Google nem recebe a site key, então não há como perguntar a ele se as duas combinam. Por isso a mensagem na tela diz "secret validada", e nunca "chaves validadas" — a diferença é real.

Esse caso residual é pego depois, em produção, pelo aviso de runtime: se todas as verificações recentes falharem (mínimo de 10, 100% de recusa), o plugin exibe um aviso dizendo que a causa mais provável são chaves de projetos diferentes. Nenhum veredito muda por causa desse aviso — ele é diagnóstico puro.

---

Configuração

Configurações → WP reCAPTCHA Forms

Opção	Default	O que faz
Versão do reCAPTCHA	v3	v3 é invisível e decide por score; v2 mostra a caixa "Não sou um robô". As chaves não são intercambiáveis
Site key / Secret key	vazias	A secret nunca é ecoada de volta; deixe o campo em branco para manter a atual
Threshold de score	0.6	Só vale para o v3. Envios abaixo disso são bloqueados
Enviar IP ao Google	ligado	Melhora a qualidade do score. Ver Privacidade
Consentimento	não exigir	Ver Consentimento e CMP
Política de falha (2 eixos)	permitir	Ver a seção seguinte
Formulários protegidos	todos ligados	Um toggle e dois eixos de política por formulário
Mensagens	vazias	Em branco = usa o texto padrão, já traduzido

A secret key também pode vir do wp-config.php, fora do banco:

define( 'WP_RECAPTCHA_FORMS_SECRET_KEY', 'sua-secret-key' );

Com a constante definida, o campo na tela fica desabilitado e sem name — não há como sobrescrevê-la pelo painel.

---

Quando a verificação não é possível

Existem quatro desfechos possíveis, e cada um tem dono diferente. É a decisão de desenho mais importante do plugin, então vale a tabela:

Classe	O que aconteceu	De quem é o problema	Política	Configurável?
Reprovado	O Google respondeu e reprovou o envio	do visitante (ou do robô)	sempre bloqueia	não
Servidor sem Google	O seu servidor não conseguiu falar com o Google	rede/infra; você pode agir	permitir (default)	sim, 2 níveis
Chaves erradas	O Google recusou as chaves	você, operador	permite + aviso máximo no painel	por filtro
Navegador sem Google	O navegador do visitante não carregou o reCAPTCHA	ninguém — é o mundo	permitir (default)	sim, 2 níveis

"Reprovado" não é configurável de propósito. Torná-lo configurável desligaria o plugin por padrão na primeira vez que alguém escolhesse "permitir", e é justamente o único caso em que temos certeza de que o Google avaliou e disse não.

O que você está comprando ao deixar "navegador sem Google" em permitir

Com esta opção em "permitir", um visitante cujo navegador não consegue carregar o reCAPTCHA envia o formulário sem verificação. Isso preserva a venda de clientes com bloqueador de anúncios — e também deixa passar um robô que simule a mesma condição. Em "bloquear", nenhum envio não verificado passa, e visitantes com bloqueador não conseguem comprar, comentar nem se registrar.

Não há como tornar esse sinal infalsificável: qualquer prova que o navegador possa produzir sem falar com o Google, um script também produz. O plugin não gasta complexidade fingindo o contrário — gasta em deixar a escolha explícita.

Um robô que simplesmente não envia nada continua bloqueado, mesmo em "permitir". A diferença entre "não enviou token" e "declarou que não conseguiu obter token" é o que separa os dois casos.

O que o visitante vê

Quando o navegador não consegue carregar o reCAPTCHA, aparece um aviso no próprio formulário, antes do envio prosseguir:

Não foi possível carregar a verificação de segurança do Google. Se você usa bloqueador de anúncios ou recusou os cookies, desative-o para esta página e tente novamente.

Em "permitir", é só um aviso — o envio funciona. Em "bloquear", a recusa vem com uma mensagem própria, diferente da de "reprovado": o visitante precisa saber que o problema é o bloqueador dele, não que ele foi confundido com um robô.

---

Privacidade

O plugin fornece um texto de aviso pronto para você colar na sua política de privacidade, e ele reflete a configuração real da sua instalação — se o envio de IP está ligado ou desligado, e se o script está sob consentimento.

Três formas de usá-lo:

// 1. Função
echo wp_recaptcha_forms_privacy_notice();
echo wp_recaptcha_forms_privacy_notice( array( 'format' => 'plain' ) );

2. Shortcode
[wp_recaptcha_forms_privacy_notice]
[wp_recaptcha_forms_privacy_notice format="plain"]

3. Ferramenta nativa do WordPress: o texto já aparece em Configurações → Privacidade → guia de política sugerida, ao lado dos textos dos outros plugins, com botão de copiar.

O parágrafo que você precisa ler antes de desligar o envio de IP

O toggle "enviar o endereço IP do visitante ao Google" controla apenas o IP que o seu servidor manda junto com a verificação. Desligá-lo melhora pouco e engana muito:

Desligar esse envio não impede que o Google receba o endereço IP do visitante, porque o script do reCAPTCHA é carregado diretamente do domínio do Google pelo navegador do visitante. O Google vê o IP de qualquer forma.

A mitigação de privacidade que de fato funciona neste plugin é outra, e está ligada por padrão: o script do Google só é carregado nas páginas que contêm um formulário protegido. Em qualquer outra página do seu site, o navegador do visitante não fala com o Google por causa deste plugin.

---

Consentimento e CMP

Um CMP configurado corretamente segura scripts de terceiro até o aceite. Se você tem um, ligue o modo de consentimento:

Modo	Comportamento
não exigir (default)	Carrega o script normalmente
automático	Consulta a WP Consent API, se houver; sem provedor, comporta-se como "não exigir"
exigir	Nunca carrega sem sinal explícito de consentimento

O plugin não se integra com nenhum CMP pelo nome. Manter N adaptadores para N plugins que mudam de API sem avisar é dívida garantida num projeto de mantenedor solo. Em vez disso, ele publica um contrato — e você liga os dois fios com três linhas.

Complianz

document.addEventListener( 'cmplz_status_change', function () {
    if ( cmplz_has_consent( 'marketing' ) ) {
        window.wpRecaptchaForms.grantConsent();
    }
} );

CookieYes

document.addEventListener( 'cookieyes_consent_update', function ( e ) {
    if ( e.detail && e.detail.accepted && e.detail.accepted.includes( 'advertisement' ) ) {
        window.wpRecaptchaForms.grantConsent();
    }
} );

Os nomes de evento e de categoria acima são do CMP, não deste plugin, e mudam sem nos avisar. Confira na documentação corrente do seu CMP; a única parte que é contrato nosso é a chamada window.wpRecaptchaForms.grantConsent().

WP Consent API

Nada a fazer: em automático ou exigir, o plugin já consulta wp_has_consent() quando a WP Consent API está presente. A categoria consultada é marketing, e é filtrável — a classificação do reCAPTCHA como marketing, functional ou statistics é decisão jurídica sua, não nossa:

add_filter( 'wp_recaptcha_forms_consent_category', fn() => 'functional' );