ALTCHA
e CapMonster Cloud

Solução de captcha, instalação no site e testes.

Preços da solução ALTCHA

CAPTCHA
Preço (USD)
$ 0.80
1000 tokens
Você herdou um site com captcha ou outra camada de proteção, mas não tem acesso ao código-fonte? Então é normal querer saber qual solução está instalada, se a configuração está correta e como testar tudo.

Neste artigo, procuramos responder a todas as principais dúvidas. Para começar a resolver o problema, o primeiro passo é identificar qual sistema de proteção está sendo utilizado. Para isso, você pode consultar a lista de captchas e sistemas de proteção antibot mais populares, onde há exemplos visuais e sinais principais que ajudam a identificar rapidamente com o que você está lidando.

Se você notar que o seu site utiliza ALTCHA, o passo seguinte é estudar com mais detalhes as suas características e o seu funcionamento. Neste mesmo artigo, você também pode conferir o guia de integração do ALTCHA, para entender por completo como o sistema opera no seu site. Isso permitirá não apenas compreender a proteção atual, mas também planejar adequadamente a sua manutenção.

O que é o ALTCHA
O que é o ALTCHA
ALTCHA (Alternative CAPTCHA) é um sistema de proteção de sites contra bots e spam. Ele ajuda a diferenciar usuários reais de programas automatizados, garantindo que o site funcione de forma segura e estável. ALTCHA é uma alternativa moderna às CAPTCHAs tradicionais: utiliza um desafio criptográfico leve (proof-of-work) e não coleta cookies nem rastreia usuários.
Background
Exemplos de ALTCHA
Proof-of-Work (PoW)
Proof-of-Work (PoW)
O sistema utiliza por padrão o método de verificação Proof-of-Work (PoW), eliminando puzzles visuais e verificações intrusivas. Essa abordagem combina segurança com conveniência para os usuários, oferecendo uma solução captcha discreta adequada para a maioria dos visitantes.
Code Captcha
Code Captcha
A proteção pode ser reforçada até a passagem de um captcha textual.
Invisible Captcha
Invisible Captcha
A verificação ocorre sem widget visível e não requer ação do usuário.

Como resolver ALTCHA através do CapMonster Cloud

Ao testar formulários com ALTCHA, é comum precisar confirmar se a captcha está funcionando e integrada corretamente.

Você pode testar manualmente a captcha incorporada no site.

  • Abra a página do formulário e veja se a captcha é exibida.
  • Tente enviar sem resolver — o servidor deve retornar erro.
  • Depois de resolver corretamente, o envio precisa ocorrer sem falhas.

Para resolver automaticamente use ferramentas como o CapMonster Cloud, que recebe os parâmetros da captcha, processa em seus servidores e devolve um token pronto. Basta inseri-lo no formulário para passar na verificação sem interação humana.

Trabalhar com o CapMonster Cloud via API normalmente envolve as etapas abaixo:

Criação da tarefaCriação da tarefa
arrow
Envio da requisição APIEnvio da requisição API
arrow
Recebimento do resultadoRecebimento do resultado
arrow
Aplicação do token na páginaAplicação do token na página
arrow
Resolução, inserção do token e envio de formulário
Exemplo em Node.js para o ciclo completo de reconhecimento de captcha na sua página web. Abordagens possíveis: usar requisições HTTP para obter HTML e parâmetros do captcha, enviar a resposta e processar o resultado; ou usando ferramentas de automação (ex: Playwright) — abrir a página, aguardar o captcha, enviar parâmetros (para testes pode enviar dados corretos ou incorretos), obter resultado via cliente CapMonster Cloud, inserir o token no formulário e verificar o resultado.
python
// npm install playwright
// npx playwright install chromium

const { chromium } = require("playwright");

const API_KEY = "YOUR_API_KEY";
const ALTCHA_PAGE = "https://example.com"; // Seu site com ALTCHA

(async () => {
  const browser = await chromium.launch({ headless: false, devtools: true });
  const context = await browser.newContext();
  const page = await context.newPage();

  // Capturando todas as respostas do endpoint Altcha
  let challengeResp = null;
  page.on("response", async (response) => {
    try {
      const url = response.url();
      if (url.startsWith("https://captcha.example.com/altcha")) { // Endpoint Altcha
        challengeResp = await response.json();
        console.log("Captured Altcha response:", challengeResp);
      }
    } catch (err) {
      console.warn("Error parsing Altcha response:", err);
    }
  });

  await page.goto(ALTCHA_PAGE, { waitUntil: "networkidle" });

  // Clique no widget, se existir
  const widgetHandle = await page.$("altcha-widget");
  if (widgetHandle) {
    try {
      await widgetHandle.click();
    } catch {}
  }

  // Aguardando o aparecimento do challenge
  const start = Date.now();
  while (!challengeResp && Date.now() - start < 60000) { // Timeout aumentado
    await new Promise((r) => setTimeout(r, 300));
  }

  if (!challengeResp) {
    console.error("Failed to capture Altcha challenge.");
    await browser.close();
    return;
  }

  const { challenge, salt, signature, maxnumbers } = challengeResp;

  // Criar tarefa no CapMonster Cloud
  const createTaskBody = {
    clientKey: API_KEY,
    task: {
      type: "CustomTask",
      class: "altcha",
      websiteURL: ALTCHA_PAGE,
      websiteKey: "",
      userAgent:"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/150.0.0.0 Safari/537.36",
      metadata: {
        challenge,
        iterations: maxnumbers || 100000,
        salt,
        signature,
      },
    },
  };

  const taskResp = await fetch("https://api.capmonster.cloud/createTask", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(createTaskBody),
  }).then((r) => r.json());

  console.log("CreateTask response:", taskResp);
  if (!taskResp?.taskId) {
    console.error("CreateTask failed:", taskResp);
    await browser.close();
    return;
  }

  const taskId = taskResp.taskId;

  // Obter solução
  let fullSolution = null;
  const pollStart = Date.now();
  while (Date.now() - pollStart < 120000) {
    const res = await fetch("https://api.capmonster.cloud/getTaskResult", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ clientKey: API_KEY, taskId }),
    }).then((r) => r.json());

    if (res.status === "ready") {
      fullSolution = res.solution;
      console.log("Solution:", fullSolution);
      break;
    }
    await new Promise((r) => setTimeout(r, 3000));
  }

  if (!fullSolution) {
    console.error("No solution received in time.");
    await browser.close();
    return;
  }

  const token = fullSolution?.data?.token || fullSolution?.token || fullSolution?.data;

  if (!token) {
    console.error("Token not found in solution:", fullSolution);
    await browser.close();
    return;
  }

  //Inserir token
  await page.evaluate((t) => {
    let input = document.querySelector("#captchaParaValidar");
    if (!input) {
      input = document.createElement("input");
      input.type = "hidden";
      input.id = "captchaParaValidar";
      input.name = "captchaParaValidar";
      (document.querySelector("form") || document.body).appendChild(input);
    }
    input.value = t;

    let alt = document.querySelector('input[name="altcha"]');
    if (!alt) {
      alt = document.createElement("input");
      alt.type = "hidden";
      alt.name = "altcha";
      (document.querySelector("form") || document.body).appendChild(alt);
    }
    alt.value = t;

    const widget = document.querySelector("altcha-widget");
    if (widget) {
      widget.setAttribute("data-state", "verified");
      const checkbox = widget.querySelector("input[type='checkbox']");
      if (checkbox) {
        checkbox.checked = true;
        checkbox.dispatchEvent(new Event("change", { bubbles: true }));
      }
      const label = widget.querySelector(".altcha-label");
      if (label) label.textContent = "Verified";
    }
  }, token);

  console.log("Token injected:", token);
})();
Como conectar o ALTCHA ao seu site
Para compreender totalmente como o captcha funciona no seu site, a lógica de verificação, reconectar ou reconfigurar, recomendamos ler esta seção. Ela descreve o processo de integração da proteção e ajuda a entender rapidamente todos os detalhes.

1. Instalação do widget

Opção 1 — via CDN (mais simples). Adicione ao <head> do seu HTML:

markup
<script async defer src="https://cdn.jsdelivr.net/gh/altcha-org/altcha/dist/altcha.min.js" type="module"></script>

Opção 2 — via npm:

javascript
npm install altcha

Importe o widget no seu arquivo JS:

javascript
import "altcha";

2. Adicionar o widget ao formulário.

Insira o componente <altcha-widget> no formulário onde é necessária proteção:

markup

<form method="POST" action="/submit">
  <altcha-widget challengeurl="/altcha/challenge"></altcha-widget>
  <button type="submit">Send</button>
</form>

challengeurl — seu endpoint de servidor para emitir desafios (challenge).

Se usar ALTCHA Sentinel (proteção de servidor pronta contra bots e spam com machine learning e análise de tráfego), use o URL dele em vez do seu servidor:

markup

<altcha-widget 
  challengeurl="https://sentinel.example.com/v1/challenge?apiKey=YOUR_API_KEY">
</altcha-widget>

3. Verificação no servidor.

Como ocorre a verificação:

  • 1) O widget gera um payload — JSON codificado em Base64, normalmente enviado como campo de formulário altcha.
  • 2) No servidor verifica-se o payload criptograficamente (sem requisições adicionais de API).
  • 3) Após verificação bem-sucedida, o formulário pode ser processado.

Verificação via ALTCHA Sentinel:

Usando a bibliotecaUsando a biblioteca
arrow

Via HTTP API do Sentinel (se a biblioteca não estiver disponível):Via HTTP API do Sentinel (se a biblioteca não estiver disponível):
arrow

4. Verificação sem Sentinel (servidor próprio)

Geração do desafio (challenge):

javascript

import { createChallenge } from 'altcha-lib';

const hmacKey = '$ecret.key'; // Sua chave secreta HMAC

const challenge = await createChallenge({ hmacKey });

// Devolver challenge em JSON para o widget

Verificação do payload ao enviar o formulário:

javascript

import { verifySolution } from 'altcha-lib';

const hmacKey = '$ecret.key'; // Sua chave secreta HMAC

const verified = await verifySolution(payload, hmacKey);

if (verified) {
  // Verificação bem-sucedida — processar dados do formulário
}

Neste caso, você cria o endpoint /altcha/challenge para emitir desafios e verificá-los no servidor.

Background
Possíveis erros e depuração
Bug Icon
challengeurl ou API Key inválidos
O widget não carrega ou retorna erro na verificação.
Bug Icon
Timeout de resolução
O servidor não teve tempo de verificar o payload. Aumente o tempo de espera ou certifique-se que a verificação do lado do servidor funciona corretamente.
Bug Icon
Payload vazio
Erro ao enviar o resultado do widget para o servidor.
Bug Icon
Verification failed
O payload expirou, foi reutilizado ou adulterado. Para diagnóstico, ative o logging e verifique os campos verified e verificationData na resposta do servidor ou do Sentinel.
Verificação da robustez
Depois da integração, confirme que o sistema de fato protege o site contra ações automatizadas.
Recomendações de segurança e otimização
<span class="font-bold">Mantenha as chaves secretas</span> (HMAC ou API Key para Sentinel) apenas no servidor — não envie para o frontend.
<span class="font-bold">Registre erros</span> e eventos de verificação (<span class="font-bold">verified: false</span> e <span class="font-bold">verificationData</span>) para entender os motivos das falhas.
Para transparência e confiança do usuário, <span class="font-bold">adicione links para a política de privacidade</span> e os <span class="font-bold">termos de uso do ALTCHA</span>, se necessário.
Conclusão

Se você herdou um site que já tem um captcha ou outro sistema de proteção instalado e não tem acesso ao código, não tem problema! É bem fácil identificar qual tecnologia está sendo usada. Para verificar se tudo está funcionando corretamente, você pode usar o serviço de reconhecimento CapMonster Cloud em um ambiente de testes isolado, para garantir que o mecanismo de processamento de tokens e a lógica de verificação estejam funcionando corretamente.

No caso de ALTCHA, basta identificar o sistema, analisar o comportamento dele e se certificar de que a proteção está funcionando corretamente. No artigo, mostramos como identificar ALTCHA e onde encontrar instruções para a integração ou reconfiguração, para que você consiga manter a proteção com segurança e controlar o funcionamento dela.

Conclusion
Links úteis
DocIconDocumentação ALTCHADocIconCódigo-fonte ALTCHADocIconDocumentação CapMonster Cloud (trabalhando com ALTCHA)

Perguntas frequentes sobre ALTCHA

Os widgets ALTCHA podem funcionar sem sitekeys tradicionais, por isso o CapMonster Cloud aceita uma string vazia ("") para o parâmetro websiteKey.

Importante: este campo continua obrigatório no payload JSON. Mesmo que o site use ALTCHA Sentinel e exponha um apiKey na challengeurl, não o extraia — simplesmente envie "websiteKey": "".

O parâmetro iterations na sua tarefa CapMonster Cloud corresponde diretamente ao valor maxnumber (número máximo para cálculos) no objeto challenge retornado pelo endpoint ALTCHA na página alvo. Você deve passar exatamente este valor para evitar falhas silenciosas na resolução.

A resposta getTaskResult fornece simultaneamente o number simples e o token completo codificado em base64 no mesmo payload. O desenvolvedor simplesmente extrai o valor exigido pelo site alvo para validação.

Alguns formulários exigem apenas o número calculado, enquanto outros esperam o conjunto completo de parâmetros criptografados em formato base64.

O CapMonster Cloud suporta as três variantes ALTCHA:

  • Proof-of-Work — o widget ALTCHA padrão que executa um challenge computacional no navegador.
  • Code Captcha — exige que o usuário ou o script insira um código curto.
  • Invisible Captcha — funciona em segundo plano sem widget visível ou interação do usuário.

Saiba como encontrar todos os parâmetros necessários para criar a tarefa

Após o cliente enviar o challenge, seu backend verifica os dados (salt, signature, número calculado e difficulty). Você pode implementar isso de duas formas:

  • Sentinel API: valida automaticamente o payload e previne ataques de replay (deduplicação e expiração).
  • Servidor próprio: use a função verifySolution para verificar manualmente o booleano verified e o payload.

Consulte o capítulo Como conectar o ALTCHA ao seu site (etapas 3–4) acima para detalhes.

Nota: se a validação falhar (ex.: 403 Forbidden), geralmente se deve a um payload expirado ou reutilizado (ataque de replay), não a um cálculo PoW incorreto.