Cómo elegir una API de captcha: del catálogo de tipos a la validación en sistemas propios

Al integrar un captcha, el error más peligroso suele ser confundir la obtención de un resultado con la aprobación de la verificación. Que el cliente reciba un token que no esté vacío, que el servicio de validación lo reconozca y que tu aplicación permita la acción son tres cosas distintas. Validar solo la primera puede dejar el formulario expuesto a rechazos posteriores en el backend; tratar la primera como si fuera la tercera podría permitir que se omitan los controles de permisos.

Esta guía está dirigida al desarrollo y pruebas en sistemas propios: aprende a identificar productos de desafíos, leer el contrato de tipo actual de EveryInfra, aislar la configuración de pruebas y comprobar que el sistema se detiene en el lugar correcto ante un fallo. También resulta aplicable a entornos oficiales de prueba y ámbitos autorizados explícitamente. No se incluyen pasos para manipular cuentas reales de terceros, pagos, permisos ni desafíos de control de riesgos.

determina primero qué sección vas a probar

Si el objetivo es comprobar que tu formulario guarda datos al verificar correctamente y bloquea la escritura si falla, utiliza preferentemente los mecanismos de prueba provistos por el producto de desafíos. Esto ofrece resultados controlados sin necesidad de convertir cada integración continua en la resolución de un desafío real. Añadir otra API en este punto no aporta valor de prueba automático; al contrario, introduce una dependencia adicional que requiere su propia aceptación.

Si necesitas evaluar las capacidades de captcha de EveryInfra, divide la prueba en dos cuestiones independientes: comprueba si la API devuelve la forma correcta según lo acordado y verifica si el resultado se procesa adecuadamente en entornos autorizados. Conserva evidencias separadas para ambos aspectos sin usar el éxito de uno para validar el otro. El punto de partida de la selección es la tarea de prueba, no la cantidad de tipos listados en un catálogo.

identifica el producto por su configuración y no por su aspecto

Confirma el producto, el modo, el dominio y el propósito a partir del código de integración, la configuración del panel y la documentación oficial correspondiente. Una simple casilla de verificación visual no basta para determinar el tipo de solicitud, y los distintos modos de un mismo producto no deben intercambiarse libremente. Deja constancia clara de la prueba indicando quién administra la página, qué se permite comprobar, qué configuración de prueba se utiliza y cuál es el resultado esperado.

En entornos autorizados pero ajenos a tu gestión, los parámetros deben ser provistos por el responsable o consultarse en la documentación oficial. Detente ante la falta de contexto necesario y pide al administrador que confirme los datos; evita adivinar tipos similares o inventar campos. Ver un identificador público en una página no otorga permiso para realizar operaciones automatizadas sin restricciones.

Por ejemplo, la configuración del dominio en Turnstile recibe el nombre de host sin protocolos, puertos ni rutas completas, y configurar un dominio principal afecta también a sus subdominios. El alcance del entorno de prueba debe ser verificado por su responsable, sin relajar las reglas de configuración solo para hacer encajar una dirección errónea; este parámetro difiere del campo website_url en las solicitudes.

lee el tipo, la disponibilidad, los parámetros y el formato de los resultados

A continuación se muestra una lectura de catálogo gratuita y sin autenticación que no genera tareas de resolución. Se seleccionan solo dos tipos a modo de ejemplo con el fin de comparar contratos, sin requerir la ejecución de ambos desafíos. Se requieren curl y jq; si la lectura del catálogo falla, resuelve primero la fase de descubrimiento antes de enviar solicitudes de negocio con salidas vacías.

set -o pipefail
curl -fsS --max-time 30 'https://api.everyinfra.com/api/v1/captcha/types' \
  | jq -e '[.types[] |
      select(.type == "turnstile" or .type == "recaptcha_grid") |
      {type, available, required_params, optional_params, solution}
    ] | if length == 2 then . else error("expected types missing") end'

En esta observación pública realizada en 2026, 9, 4, los parámetros obligatorios para turnstile fueron website_url y website_key, mientras que action, cdata y page_data figuraban como opcionales; solution.shape indicó token con el campo token. En cuanto a recaptcha_grid, los parámetros obligatorios correspondieron a body y question, con un formato shape de tipo points y el campo objects. Ambos servicios mostraron un estado available en true durante dicho momento. Estos datos reflejan declaraciones del catálogo y no constituyen prueba de éxito en un desafío real.

Por lo tanto, el procesador de resultados debe bifurcar según el tipo y contrato de solución determinados, en lugar de tomar un token principal de forma incondicional o convertir cualquier objeto en cadena de texto. Que un parámetro aparezca en optional_params solo indica que el contrato lo contempla como opcional; la validez de una combinación se rige por los errores actuales y la disponibilidad, sin omitir restricciones de negocio necesarias para lograr el éxito.

Guarda la marca de tiempo de la observación del catálogo junto con las entradas seleccionadas. No envíes solicitudes si available se encuentra en false; marca como desconocido cualquier elemento con campos faltantes, tipos incorrectos o fallos de lectura, deteniendo el proceso en esos casos. Incluso si el valor es true, esto solo indica que la capacidad podía probarse en el momento de la consulta, sin garantizar el éxito en cada tarea posterior.

aísla los mecanismos de prueba oficiales de la configuración de producción

Cloudflare Turnstile proporciona claves de sitio y secretos de prueba para simular tokens aprobados, rechazados o ya utilizados. Las credenciales de prueba y las de producción no deben mezclarse. Por su parte, las preguntas frecuentes de Google reCAPTCHA distinguen entre las claves de prueba para v2 y la configuración de pruebas independiente para v3; las puntuaciones de prueba en entornos de v3 no representan el comportamiento ante tráfico real.

La clave de sitio es el identificador público que usa la página y el secreto corresponde a la clave de validación del backend. La configuración de pruebas debe obtenerse de parámetros de entorno explícitos y no activarse automáticamente solo porque una solicitud indique que se trata de una prueba. Al iniciar en producción, comprueba el origen de la configuración y la consistencia del entorno; los registros deben conservar únicamente el estado necesario para auditorías sin exponer secretos, tokens completos ni objetos de solicitud originales.

Se recomienda ubicar el servicio de validación detrás de una interfaz específica en el código de negocio: la lógica principal solo recibe resultados de validación claros y las pruebas pueden inyectar respuestas sintéticas, mientras que la validación real corre a cargo del servidor. El mecanismo de inyección debe controlarse mediante la configuración del servidor o compilaciones de prueba, evitando exponerlo como un parámetro modificable por el usuario. Esta es una recomendación de diseño de aplicación y no una función provista automáticamente por EveryInfra.

separa la aceptación del token, la verificación en el servidor y las operaciones del negocio

Cloudflare exige que el servidor invoque Siteverify; contar únicamente con componentes en el frontend no ofrece protección completa. La documentación oficial también estipula que los tokens tienen una validez de cinco minutos y solo pueden verificarse una vez. No trates los tokens como credenciales almacenables en caché a largo plazo ni reutilizables, y evita intentar recuperar fallos de red reutilizando indefinidamente el mismo valor.

Aun cuando la verificación del servidor sea exitosa, la lógica de negocio debe aplicar sus propias comprobaciones de sesión, permisos de recursos, validación de entradas y control de envíos duplicados. Un captcha no es una credencial de cuenta ni una autorización de transacciones. Si ocurren fallos posteriores en el flujo, conserva los errores correspondientes de la aplicación en lugar de rebautizarlos como fallos de verificación para generar tareas nuevas sin límite.

Tampoco deben combinarse los detalles de validación de distintos productos. La documentación de Google reCAPTCHA para el backend establece reglas de uso único con un límite de dos minutos y errores como timeout-or-duplicate, lo cual difiere de la ventana de cinco minutos de Turnstile. El manejo de errores debe ajustarse al producto específico y a la respuesta de validación real.

comprueba las condiciones de aceptación del backend mediante un ejemplo sin conexión

A continuación se ilustra únicamente un comprobador de resultados para una página de pruebas propia. Dicha página configura explícitamente el host como localhost y la acción como test; los valores esperados provienen de la configuración fija del servidor y no de los datos enviados por el usuario. En integraciones reales, el parámetro result recibido debe obtenerse invocando la interfaz de verificación oficial desde tu propio backend, sin confiar ciegamente en el valor success enviado por el cliente.

function acceptOwnTestVerification(result, expected) {
  if (!expected || typeof expected.hostname !== "string" ||
      !expected.hostname.trim() || typeof expected.action !== "string" ||
      !expected.action.trim()) {
    throw new Error("server-side test configuration required");
  }
  if (!result || typeof result !== "object" || Array.isArray(result)) {
    return { accepted: false, reason: "invalid_response" };
  }
  if (result.success !== true) {
    return { accepted: false, reason: "verification_failed" };
  }
  if (result.hostname !== expected.hostname) {
    return { accepted: false, reason: "hostname_mismatch" };
  }
  if (result.action !== expected.action) {
    return { accepted: false, reason: "action_mismatch" };
  }
  return { accepted: true, reason: "verification_only" };
}

// todos los valores son datos de prueba auto-creados; sin solicitudes de red, sin tokens generados.
const expected = { hostname: "localhost", action: "test" };
const synthetic = { success: true, hostname: "localhost", action: "test" };
console.log(acceptOwnTestVerification(synthetic, expected));
// { accepted: true, reason: 'verification_only' }

Este ejemplo emite exclusivamente verification_only: no genera tokens, no invoca Siteverify ni envía formularios. La razón por la que el comprobador exige una acción es que dicha configuración de pruebas lo requiere expresamente; no asumas que todos los productos de desafíos devuelven los mismos campos. Implementa el contrato de validación específico para cada producto en lugar de reutilizar una función genérica que relaje las condiciones de evaluación.

Prueba al menos los casos de éxito, success en falso, success como texto, error de dominio, acción faltante, respuesta vacía y ausencia de configuración en el servidor. Después, verifica la ruta completa desde la página hasta el backend propio utilizando integraciones de prueba oficiales autorizadas. Que una función sin conexión supere la prueba solo demuestra el funcionamiento de esas bifurcaciones lógicas, pero no garantiza la validación de red, la configuración de producción ni el rendimiento ante riesgos.

determina el siguiente paso según dónde se produzca el fallo

• Fase de entrada: discrepancias de tipos, campos obligatorios ausentes o combinaciones de parámetros no admitidas. Corrige el contrato primero en lugar de reenviar la misma solicitud en bucle.
• Fase de capacidad: catálogo desconocido o no disponible en el momento. Detén esa prueba y registra la observación sin reemplazar el producto de desafíos por tu cuenta.
• Fase de llamada: registra por separado los fallos evidentes y las esperas agotadas por tiempo límite. No recibir una respuesta no significa que el servidor no haya actuado; conserva primero los datos de correlación de la solicitud.
• Fase de validación: el backend propio rechaza el resultado. Registra una clasificación de errores segura junto con sus casos de prueba, y revisa el entorno, el dominio y la acción en lugar de flexibilizar los criterios de aceptación.
• Fase de negocio: incluso tras superar la verificación, las solicitudes pueden rechazarse por entradas incorrectas, permisos insuficientes o reenvíos. Gestiona esto mediante los flujos de la aplicación sin fingir que el captcha no se resolvió.

Los costos también deben comprobarse aplicando este desglose por capas. La implementación actual de EveryInfra contempla una devolución de saldo en caso de fallo de resolución, pero un error de validación en el cliente o un rechazo del negocio no equivalen a que la pasarela haya determinado un fallo en la solución. No asumas reembolsos ni recuperación anticipada basándote en avisos en rojo del frontend; es necesario cotejar cada solicitud con su respuesta y los registros contables disponibles. Este artículo no añade ejemplos de recuperación de saldo tras fallos reales ni garantiza que futuros rechazos modifiquen el estado financiero.

deja constancia de un registro de pruebas verificable

Un registro de aceptación útil debe detallar: entorno autorizado, modalidad del producto, marca de tiempo de la observación del catálogo, tipo de configuración de prueba empleada, estructura de entrada, estructura de respuesta, veredicto de validación, veredicto de negocio y veredicto financiero. Omite datos reales en la medida de lo posible y vincula los resultados de cada capa usando identificadores desensibilizados. Especifica claramente qué aspectos quedaron sin cubrir para evitar que futuros equipos confundan una lectura exitosa del catálogo con una validación completa.

Valida tus flujos de éxito y error empleando los mecanismos oficiales de prueba, evalúa después las ramas de API que realmente necesites y amplía la validación dentro de los límites autorizados en último lugar. El criterio para elegir un tipo de captcha no debe ser la similitud de los nombres o la presencia de valores en una respuesta aislada, sino contar con condiciones de entrada claras, formatos de salida interpretables, juicios correctos en el backend y la garantía de no rebasar los límites del negocio cuando ocurran fallos.