logo
bars

ALTCHA
e CapMonster Cloud

Resolução de captcha, instalação no site e testes.
Herdou um site com captcha ou outra proteção mas sem acesso ao código-fonte? É natural perguntar qual solução está instalada, se está configurada corretamente e como testá-la.

Neste artigo procurámos responder a todas as questões importantes. Para começar a resolver o problema, o primeiro passo é identificar que sistema de proteção está a ser utilizado. Para isso, pode consultar a lista de captchas e sistemas de proteção antibot mais populares, onde encontrará exemplos visuais e sinais principais que ajudam a perceber rapidamente com o que está a lidar.

Se verificar que o seu site utiliza ALTCHA, o passo seguinte é analisar mais detalhadamente as suas características e o seu funcionamento. Neste mesmo artigo também pode consultar o guia de integração de ALTCHA, para compreender totalmente como o sistema funciona no seu site. Isto permitirá não só entender a proteção atual, como também planear corretamente 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. Ajuda a distinguir utilizadores reais de programas automatizados, garantindo que o site funcione de forma segura e estável. ALTCHA é uma alternativa moderna às CAPTCHA tradicionais: utiliza um desafio criptográfico leve (proof-of-work) e não recolhe cookies nem rastreia os utilizadores.
Background
Exemplos de ALTCHA
Proof-of-Work (PoW)
Proof-of-Work (PoW)
O sistema utiliza por defeito o método de verificação Proof-of-Work (PoW), eliminando puzzles visuais e verificações intrusivas. Esta abordagem combina segurança com conveniência para os utilizadores, oferecendo uma solução captcha discreta adequada para a maioria dos visitantes.
Code Captcha
Code Captcha
A proteção pode ser reforçada até à passagem de um captcha textual.
Invisible Captcha
Invisible Captcha
A verificação é realizada sem widget visível e não requer ação do utilizador.

Como resolver ALTCHA através do CapMonster Cloud

Ao testar formulários que incluem ALTCHA, é comum precisar verificar se a captcha foi integrada e funciona corretamente.

Pode testar manualmente a captcha incorporada no seu site.

  • Abra a página do formulário e confirme que a captcha é apresentada.
  • Tente enviar o formulário sem resolvê-la — o servidor deve devolver um erro.
  • Após uma resolução bem-sucedida, o formulário deve ser enviado sem problemas.

Para resolução automática recorra a ferramentas como o CapMonster Cloud, que recebe os parâmetros da captcha, processa-os nos seus servidores e devolve um token pronto. Basta inseri-lo no formulário para ultrapassar a verificação sem interação do utilizador.

Trabalhar com o CapMonster Cloud através da API normalmente envolve os passos seguintes:

Criação da tarefaCriação da tarefa
arrow
Envio do pedido APIEnvio do pedido API
arrow
Receção do resultadoReceção do resultado
arrow
Aplicação do token na páginaAplicação do token na página
arrow
Resolução, inserção de 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 pedidos HTTP para obter HTML e parâmetros de captcha, enviar resposta e processar o resultado; ou usando ferramentas de automação (ex: Playwright) — abrir a página, esperar pelo 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.
// npm install playwright
// npx playwright install chromium

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

const API_KEY = "YOUR_API_KEY";
const ALTCHA_PAGE = "https://example.com"; // O 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/145.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 ligar 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 secção. Descreve o processo de integração de proteção e ajuda a compreender rapidamente todos os detalhes.

1. Instalação do widget

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

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

Opção 2 — via npm:

npm install altcha

Importe o widget no seu ficheiro JS:

import "altcha";

2. Adicionar o widget ao formulário.

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


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

challengeurl — o 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 seu URL em vez do seu servidor:


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

3. Verificação no servidor.

Como a verificação ocorre:

  • 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 pedidos API adicionais).
  • 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 de desafio (challenge):


import { createChallenge } from 'altcha-lib';

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

const challenge = await createChallenge({ hmacKey });

// Devolver challenge em JSON para o widget

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


import { verifySolution } from 'altcha-lib';

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

const verified = await verifySolution(payload, hmacKey);

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

Neste caso, 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ções de robustez
Depois da integração, certifique-se de que o sistema protege efetivamente o site contra ações automatizadas.
Recomendações de segurança e otimização
<b>Mantenha as chaves secretas</b> (HMAC ou API Key para Sentinel) apenas no servidor — não envie para o frontend.
<b>Registre erros</b> e eventos de verificação (<b>verified: false</b> e <b>verificationData</b>) para entender os motivos das falhas.
Para transparência e confiança do usuário, <b>adicione links para a política de privacidade</b> e os <b>termos de uso do ALTCHA</b>, se necessário.
Conclusão

Se 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 há problema! É bastante fácil identificar qual a tecnologia que está a ser utilizada. Para verificar se tudo está a funcionar corretamente, pode usar o serviço de reconhecimento CapMonster Cloud num ambiente de teste isolado, para garantir que o mecanismo de processamento de tokens e a lógica de verificação estão a funcionar corretamente.

No caso de ALTCHA, basta identificar o sistema, analisar o seu comportamento e confirmar que a proteção está a funcionar corretamente. No artigo, mostramos como identificar ALTCHA e onde encontrar instruções para a sua integração ou reconfiguração, para que possa manter a proteção com confiança e controlar o seu funcionamento.

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