Pular para o conteúdo
ALTCHA ALTCHA ALTCHA

Utilize a API de Desafios em conjunto com o Widget ALTCHA para gerar e validar desafios criptográficos.

A API oferece várias vantagens em relação à verificação de desafios auto-hospedados:

  • Integração simplificada com qualquer backend ou CMS.
  • Medidas de segurança adicionais, como expiração de desafios e proteção contra reutilização.
  • Capacidade de utilizar o Filtro de Spam diretamente do widget, permitindo a classificação de dados antes de enviá-los ao seu servidor.
  • Nenhuma solicitação de API é feita a partir do seu servidor; tudo é verificado criptograficamente, reduzindo a latência e eliminando possíveis problemas de rede.

Autorização

Acesso à API exige uma Chave da API. Consulte Autorização da API.

Uso com o Widget

Para usar a API com o widget ALTCHA, configure o challengeurl e lembre-se de incluir sua Chave da API na URL:

<widget-altcha
  challengeurl="https://eu.altcha.org/api/v1/challenge?apiKey=ckey_..."
></widget-altcha>

Ativar Filtro de Spam

A API também permite a classificação automática de dados para spam usando o Filtro de Spam. Para ativar o Filtro de Spam, adicione o atributo spamfilter ao widget (requer versão 0.3+):

<widget-altcha
  challengeurl="https://eu.altcha.org/api/v1/challenge?apiKey=ckey_..."
  spamfilter
></widget-altcha>

Com o Filtro de Spam ativado, a verificação submeterá automaticamente campos de texto do formulário juntamente com endereços de e-mail detectados e retornará um resultado de classificação.

Para processar a classificação em seu site, utilize o evento serververification do widget. Uma versão limitada da classificação também está inclusa na nova payload enviada ao seu servidor.

:::atenção[Importante] Usar a API da ALTCHA como challengeurl juntamente com spamfilter altera o processo de verificação no servidor. Consulte verificação do servidor. :::

Verificação do Servidor

Ao usar a API da ALTCHA com spamfilter, a payload recebida em seu servidor tem um formato diferente da payload gerada pelo widget.

Você receberá uma string codificada em base64 contendo um objeto codificado em JSON:

{
  "algorithm": "SHA-256",
  "signature": "71b86949a1a84595f71d8abd7bdef414e8b883247e30cba93f4946b028c4fbf1",
  "verificationData": "classification=BAD&score=7.75&...&time=1713566250&verified=true",
  "verified": true
}

Propriedades da payload:

  • algorithm - O algoritmo usado para a assinatura HMAC.
  • signature Assinatura HMAC dos verificationData.
  • verificationData - Dados de verificação e classificação codificados por URL.
    • time - Carimbo de data/hora da verificação em segundos.
    • verified - Se a solução foi verificada com sucesso.
    • Com spamfilter ativado (veja Resposta do Filtro de Spam):
      • classification - Classificação do Filtro de Spam.
      • email - E-mail enviado.
      • expire - Tempo di scadenza in secondi.
      • fields - Matriz de nomes de campos enviados.
      • fieldsHash - Hash SHA dos valores dos campos.
      • reasons - Matriz de motivos.
      • score - Pontuação geral da classificação.
  • verified - Se a solução foi verificada com sucesso.

Verificando a Assinatura

Para verificar se o cliente foi verificado, verifique a assinatura recebida na payload:

  1. Calcule um hash SHA dos verificationData (usando o algorithm).
  2. Calcule uma assinatura HMAC com o mesmo algorithm, onde a hmac_key é a parte secreta de sua Chave da API (por exemplo, csec_...).

Exemplo de pseudocódigo usando o algoritmo SHA-256:

// Calcular o hash SHA dos `verificationData`, não analisados, como aparecem na carga útil (o hash contém dados binários brutos, NÃO codificados em hexadecimal):
hash = sha2(payload.verificationData);


// Calcular a assinatura HMAC
signature = hmac_sha2_hex(hash, hmac_key);

A payload é considerada verificada se a assinatura calculada for igual à propriedade signature da payload. Também é aconselhável verificar os dados enviados, conforme descrito na seção Verificando Campos abaixo.

Alternativamente, se não puder verificar a assinatura criptograficamente, utilize o Ponto de Verificação da Assinatura do Servidor.

Verificando Campos

Se você utilizar o Filtro de Spam, verificationData incluirá propriedades adicionais: fields e fieldsHash. Essas propriedades permitem validar a precisão dos dados classificados. Esta etapa de verificação garante que o usuário não tenha alterado os dados enviados desde a sua validação pelo Filtro de Spam.

Para verificar o hash dos campos, concatene os valores dos campos com \n (nova linha) e calcule o hash SHA (usando o algorithm especificado). Por exemplo, se fields = field1,field2,field3:

hash = sha2_hex(field1_value + "\n" + field2_value + "\n" + field3_value);

Certifique-se de que os valores estejam ordenados na ordem em que aparecem na propriedade fields.

Os dados são considerados corretos se o hash calculado corresponder ao fieldsHash.

Pontos de Extremidade da API

Se preferir usar a API diretamente, sem o widget, utilize os seguintes pontos de extremidade. Lembre-se de que o cabeçalho Referer deve sempre estar presente e conter a origem (domínio) do seu site.

Criando um Novo Desafio

Verificando Solução

Validando Assinatura do Servidor

Este ponto de extremidade serve como uma forma alternativa de verificar a assinatura do servidor recebida de /api/v1/challenge/verify. A verificação criptográfica é recomendada.