Guia de migração

Migre do hCaptcha para o CaptchaLa

Substituição plug-and-play em menos de 10 minutos. Mesmo formato de formulário — widget mais rápido, sem rodadas de classificação de imagens, e seu tráfego continua sendo seu.

hhCaptchaCurrent setup~10 minCaptchaLaDrop-in target

Como fica a mudança de código

Antes — hCaptcha
<div class="h-captcha" data-sitekey="YOUR_SITE_KEY"></div>
<script src="https://js.hcaptcha.com/1/api.js" async defer></script>
Depois — CaptchaLa
<button id="login-btn">Sign in</button>
<script src="https://cdn.captcha-cdn.net/captchala-loader.js"></script>
<script>
  loadCaptchala(() => Captchala.init({ appKey: 'YOUR_APP_KEY', action: 'login' })
    .onSuccess(res => onToken(res.token))
    .bindTo('#login-btn'));
</script>
Antes — verificação no servidor do hCaptcha (Node)
const res = await fetch('https://api.hcaptcha.com/siteverify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    secret: process.env.HCAPTCHA_SECRET,
    response: req.body['h-captcha-response'],
  }),
})
const data = await res.json()
if (!data.success) return res.status(400).json({ error: 'bot' })
Depois — verificação no servidor do CaptchaLa (Node)
const res = await fetch('https://apiv1.captcha.la/v1/validate', {
  method: 'POST',
  headers: {
    'X-App-Key': process.env.CAPTCHALA_APP_KEY,
    'X-App-Secret': process.env.CAPTCHALA_APP_SECRET,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ pass_token: req.body['captchala-token'] }),
})
const { data } = await res.json()
if (!data || !data.valid) return res.status(400).json({ error: 'bot' })

Passos da migração

  1. 1

    Cadastre-se e pegue sua App Key + Secret

    Crie uma conta gratuita no CaptchaLa, adicione um site e copie a App Key (pública) e o App Secret (lado do servidor). Sem cartão de crédito.

  2. 2

    Troque a tag do widget

    Substitua a classe h-captcha por captchala, data-sitekey por data-app-key e o src do script pela URL do nosso CDN. A estrutura permanece idêntica.

  3. 3

    Atualize o nome do campo oculto

    O hCaptcha injeta h-captcha-response; o CaptchaLa injeta captchala-token. Faça um search-and-replace do nome do campo no seu handler de formulário se você o referencia pelo nome.

  4. 4

    Atualize a verificação no servidor

    Mude o endpoint para apiv1.captcha.la/v1/validate. Usamos JSON (o hCaptcha usa form-urlencoded), então atualize o Content-Type e o corpo. A flag valid (data.valid) continua na resposta — o código de ramificação permanece.

  5. 5

    Faça o rollout gradualmente

    Coloque o CaptchaLa primeiro em um formulário, meça a conversão e a taxa de desafio por algumas horas. A maioria das equipes vê a conclusão estável ou melhor imediatamente, porque as rodadas de classificação de imagens desaparecem.

Perguntas frequentes

O que acontece com a minha conta do hCaptcha?

Nada — deixe-a como está e pare de enviar requisições. Não há contrato nem etapa de notificação. A conta fica inativa. Se quiser encerrá-la formalmente, o hCaptcha tem uma opção self-service de exclusão de conta.

Os Core Web Vitals vão melhorar?

Geralmente sim. O widget do hCaptcha normalmente adiciona de 400 a 600 ms ao LCP em páginas de formulário. O widget do CaptchaLa mira em <100ms. O delta exato depende do restante do budget da sua página, mas em páginas com muitos formulários a diferença é perceptível.

E os recursos do hCaptcha Enterprise que estou usando?

A maioria dos recursos enterprise (temas personalizados, scoring de risco avançado, dashboards de analytics) tem equivalentes diretos no plano padrão do CaptchaLa. A página de migração na documentação lista cada recurso e sua contrapartida no CaptchaLa.