Primeiros passos

Este guia ajuda você a integrar o CAPTCHA da CaptchaLa em 5 minutos.

Veja funcionar em 30 segundos

demo-v1.captcha.la — HTML + PHP puro, licença MIT, com view-source em todas as páginas.

• popup.html — modo popup
• float.html — widget flutuante
• bind.html — vinculado a botão
• inline.html — incorporado inline
• server-token.html — token emitido pelo servidor (anti-replay)

1. Criar conta

Crie uma conta gratuita no painel

Cadastre-se agora →

2. Criar aplicação

Crie uma aplicação no painel para obter sua App Key

3. Instalar o SDK

Escolha o método de instalação que preferir

<!-- CDN loader (recommended): auto-fallback CDN, ~6 KB gzip -->
<script src="https://cdn.captcha-cdn.net/captchala-loader.js"></script>

# or via npm
npm install captchala

4. Inicializar o CAPTCHA

Inicialize o componente de CAPTCHA na sua página

<button id="login-btn">Sign in</button>

<script>
loadCaptchala(function () {
  Captchala.init({
    appKey: 'YOUR_APP_KEY',
    product: 'bind',          // popup | float | bind | embed
    action: 'login',
    lang: 'auto',
  })
  .onSuccess(function (res) {
    // res.token starts with pt_ — POST it to your backend
    submitLogin(res.token);
  })
  .onError(function (err) { console.error(err.message); })
  .bindTo('#login-btn');     // popup/bind use bindTo; float/embed use appendTo
});
</script>

5. Validação no servidor

Valide o token no seu servidor

POST https://apiv1.captcha.la/v1/validate
X-App-Key: YOUR_APP_KEY
X-App-Secret: YOUR_APP_SECRET
Content-Type: application/json

{ "pass_token": "<from onSuccess>", "client_ip": "<end-user IP>" }

{
  "code": 0,
  "data": {
    "valid": true,
    "action": "login",
    "challenge_id": "ch_xxx",
    "uid": null,
    "client_ip": "1.2.3.4",
    "risk_score": 12
  }
}

WARNING

Sempre verifique data.valid === true e que data.action coincide com o cenário esperado. Os pass tokens são de uso único; o mesmo pt_xxx não pode ser validado duas vezes.

Modo Token emitido pelo servidor (recomendado para produção)

Para ações sensíveis (login, cadastro, pagamento) recomendamos o fluxo de Token emitido pelo servidor: seu backend solicita primeiro um server_token de curta duração, que o navegador então usa para inicializar o CAPTCHA. Isso impede abusos caso a app_key vaze.

Quando usar

• Recomendado: cadastro, login, redefinição de senha, pagamento, resgate de pontos e qualquer endpoint que um atacante consiga automatizar.
• Opcional: formulários públicos casuais, caixas de pesquisa e interações de baixo valor em que a conveniência pesa mais.

1. O backend emite o server_token

Chame /v1/server/challenge/issue a partir do seu próprio servidor, usando os headers X-App-Key e X-App-Secret. Nunca exponha esses headers ao navegador.

# Server-side only — never call this from a browser
curl -X POST https://apiv1.captcha.la/v1/server/challenge/issue \
  -H "X-App-Key: YOUR_APP_KEY" \
  -H "X-App-Secret: YOUR_APP_SECRET" \
  -d "action=login&ttl=300&max_uses=1&bind_ip=1.2.3.4"

# → { "code": 0, "data": { "server_token": "sct_...", "expires_in": 300 } }

2. O frontend renderiza a CaptchaLa com o server_token

Passe o token para o seu componente CaptchaLa. O SDK o encaminha à inicialização do desafio.

// Browser fetches the token from YOUR backend, not from CaptchaLa directly
const { serverToken } = await fetch('/api/captcha/issue').then(r => r.json());

Captchala.init({
  appKey: 'YOUR_APP_KEY',
  serverToken,             // single-use, short-lived
  product: 'popup',
  action: 'login',
})
.appendTo('#captcha-container')
.onSuccess(res => submitForm(res.token));

Notas de segurança

• Nunca coloque a app_secret em código de frontend, aplicativos móveis ou repositórios públicos. Ela deve permanecer no servidor.
• Habilite "Exigir token de desafio emitido pelo servidor" no painel para rejeitar qualquer desafio tentado sem um server_token.
• Mantenha o ttl curto (300s por padrão, máx. 900s) e prefira max_uses=1 para reduzir o impacto de um vazamento de token.

Próximos passos

• SDK Web
• Referência da API