Saltearse al contenido
ALTCHA ALTCHA ALTCHA

API de Desafíos PoW

Utiliza la API de Desafíos junto con el Widget ALTCHA para generar y validar desafíos criptográficos.

La API ofrece varias ventajas sobre la verificación de desafíos autohospedados:

  • Integración simplificada con cualquier backend o CMS.
  • Medidas de seguridad adicionales como la expiración de desafíos y protección contra reutilización.
  • Capacidad de utilizar el Filtro de Spam directamente desde el widget, permitiendo la clasificación de datos antes de enviarlos a tu servidor.
  • Cero solicitudes de API realizadas desde tu servidor; todo se verifica criptográficamente, reduciendo la latencia y eliminando posibles problemas de red.

Autorización

Acceder a la API requiere una Clave API. Consulta autorización de API.

Uso con el Widget

Para emplear la API con el widget de ALTCHA, configura el challengeurl e incluye tu Clave API en la URL:

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

Habilitar Filtro de Spam

La API también permite la clasificación automática de datos para spam utilizando el Filtro de Spam. Para habilitar el Filtro de Spam, agrega el atributo spamfilter al widget (requiere versión 0.3+):

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

Con el Filtro de Spam habilitado, la verificación enviará automáticamente campos de texto del formulario junto con direcciones de correo electrónico detectadas y devolverá un resultado de clasificación.

Para procesar la clasificación en tu sitio web, utiliza el evento serververification del widget. Una versión limitada de la clasificación también se incluye en el nuevo payload enviado a tu servidor.

Importante

Usar la API de ALTCHA como challengeurl junto con spamfilter altera el proceso de verificación en el servidor. Consulta verificación de servidor.

Verificación de Servidor

Cuando utilizas la API de ALTCHA con spamfilter, el payload recibido en tu servidor tiene un formato diferente al generado por el widget.

Recibirás una cadena codificada en base64 que contiene un objeto JSON codificado:

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

Propiedades del payload:

  • algorithm - El algoritmo utilizado para la firma HMAC.
  • signature Firma HMAC de los datos de verificación.
  • verificationData - Datos de verificación y clasificación codificados en URL.
    • time - Marca de tiempo de la verificación en segundos.
    • verified - Si la solución se ha verificado correctamente.
    • Con spamfilter habilitado (ver Respuesta Filtro de Spam):
      • classification - Clasificación del Filtro de Spam.
      • email - Correo electrónico enviado.
      • expire - Tiempo de expiración en segundos.
      • fields - Array de nombres de campos que se enviaron.
      • fieldsHash - Hash SHA de los valores de los campos.
      • ipAddress - La dirección IP del usuario.
      • reasons - Array de razones.
      • score - Puntuación global de clasificación.
  • verified - Si la solución se ha verificado correctamente.

Verificación de Firma

Para verificar que el cliente ha sido verificado, verifica la firma recibida en el payload:

  1. Calcula un hash SHA de los verificationData (usando el algorithm).
  2. Calcula una firma HMAC con el mismo algorithm, donde la hmac_key es la parte secreta de tu Clave API (es decir, csec_...).

Pseudocódigo de ejemplo usando el algoritmo SHA-256:

// Calcular el hash SHA de los `verificationData`, sin analizar, tal como aparecen en la carga útil (el hash contiene datos binarios sin procesar, NO codificados en hexadecimal):
hash = sha2(payload.verificationData);


// Calcular la firma HMAC
signature = hmac_sha2_hex(hash, hmac_key);

El payload se considera verificada si la firma calculada coincide con la propiedad signature de la carga. También es recomendable verificar los datos enviados, como se describe en la sección Verificación de Campos a continuación.

Alternativamente, si no puedes verificar la firma criptográficamente, utiliza el punto de verificación de Firma de Servidor.

Verificación de Campos

Si utiliza el Filtro de Spam, verificationData incluirá propiedades adicionales: fields y fieldsHash. Estas propiedades le permiten validar la precisión de los datos clasificados. Este paso de verificación asegura que el usuario no ha alterado los datos enviados desde su validación por el Filtro de Spam.

Para verificar el hash de los campos, concatene los valores de los campos con \n (nueva línea) y calcule el hash SHA (usando el algorithm especificado). Por ejemplo, si fields = field1,field2,field3:

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

Asegúrese de que los valores estén ordenados en el orden en que aparecen en la propiedad fields.

Los datos se consideran correctos si el hash calculado coincide con el fieldsHash.

Puntos finales de API

Si prefieres utilizar la API directamente, sin el widget, utiliza los siguientes puntos finales. Recuerda que el encabezado Referer siempre debe estar presente y debe contener el origen (dominio) de tu sitio web.

Crear un Nuevo Desafío

Verificar Solución

Validar Firma de Servidor

Este punto final sirve como una forma alternativa de verificar la firma de servidor recibida de /api/v1/challenge/verify. Se recomienda la verificación criptográfica.