Documentación

Magicgate separa el tráfico de bots de los usuarios reales al evaluar a cada visitante con un conjunto de filtros configurables. La plataforma arroja un veredicto, ya sea "blanco" (bot/crawler/unwanted) u "oferta" (usuario real), en menos de 10 milisegundos.

Hay dos modos de integración. API Mode le permite enviar atributos de visitante a través de un punto final REST y recibir un veredicto JSON sobre el que actúa su aplicación. Direct Mode maneja todo automáticamente: apunta tu dominio a Magicgate y los visitantes serán filtrados y redirigidos sin ningún cambio de código por tu parte.

Este inicio rápido se centra en API Mode porque le brinda el mayor control y el ciclo de retroalimentación más rápido durante el desarrollo. Una vez que se sienta cómodo, puede cambiar a Direct Mode para implementaciones de producción donde se prefiere la integración sin código.

Magicgate evalúa a cada visitante entrante comparándolo con un proceso de detección de múltiples capas. Cada filtro se ejecuta de forma independiente y contribuye al veredicto final. Toda la evaluación se completa en menos de 10 milisegundos, lo que garantiza una latencia cero perceptible para los usuarios reales.

El proceso de detección se divide en varias categorías: comprobaciones a nivel de red (reputación de IP, GeoIP, detección de VPN/proxy/Tor, identificación de centros de datos), comprobaciones a nivel de navegador (análisis de agente de usuario, huellas dactilares de JavaScript, coherencia de encabezados), comprobaciones de comportamiento (patrones de clics, velocidad de sesión, validación de referencias) y comprobaciones basadas en listas (listas bloqueadas, listas permitidas, filtrado de ISP).

Cada filtro se puede habilitar o deshabilitar individualmente por flujo. Este control granular le permite ajustar la detección para diferentes fuentes de tráfico. Por ejemplo, una campaña dirigida a usuarios de dispositivos móviles de EE. UU. podría habilitar GeoIP (solo en EE. UU.), detección de VPN/proxy y verificación de dispositivos móviles, mientras deshabilita el filtrado de ISP.

El filtrado GeoIP utiliza bases de datos MaxMind alojadas localmente y actualizadas semanalmente para búsquedas con latencia cero. Puede orientar o excluir el tráfico por país, región o ciudad. La base de datos cubre direcciones IPv4 e IPv6 con una precisión del 99,8% a nivel de país.

La detección de VPN, proxy y Tor combina múltiples bases de datos comerciales y de código abierto. Magicgate mantiene una lista continuamente actualizada de nodos de salida VPN conocidos, servidores proxy públicos y privados, relés de salida Tor y redes proxy residenciales. La detección cubre rangos tanto de IPv4 como de IPv6.

La detección del centro de datos identifica el tráfico que se origina en proveedores de la nube (AWS, GCP, Azure, DigitalOcean, OVH, Hetzner y más de 200 más). Esto es particularmente eficaz para detectar scripts automatizados y navegadores sin cabeza que se ejecutan en máquinas virtuales.

El análisis de agente de usuario analiza la cadena de agente de usuario del visitante con una base de datos de rastreadores, bots y herramientas automatizadas conocidos. También detecta inconsistencias; por ejemplo, un agente de usuario que dice ser Chrome en Windows pero envía encabezados específicos de Linux.

El filtro de lista de bloqueo le permite mantener listas personalizadas de direcciones IP, rangos de IP (notación CIDR) y patrones de agentes de usuario que siempre deben clasificarse como bots. Por el contrario, el filtro de lista permitida le permite incluir en la lista blanca las IP confiables (como su propia infraestructura de prueba) que siempre deben pasar.

La validación del referente compara el encabezado HTTP Referer con los patrones esperados. Puede exigir que el tráfico provenga de dominios específicos (por ejemplo, Google, Facebook) o bloquear el tráfico con referencias vacías, faltantes o sospechosas.

En esencia, Magicgate es un enrutador de tráfico. Cada visitante es evaluado según sus filtros configurados y se le asigna un veredicto: 'oferta' (usuario legítimo) o 'blanco' (bot, rastreador o tráfico no deseado). El veredicto determina hacia dónde se redirige al visitante.

La página de oferta es su página de destino, página de oferta o embudo de conversión real: la página que desea que vean los visitantes humanos reales. La página blanca es un señuelo o una página benigna que se muestra a los bots, rastreadores y revisores de redes publicitarias. Las páginas blancas comunes incluyen publicaciones de blogs simples, artículos de noticias o contenido informativo genérico.

Esta separación es esencial para la protección de la campaña. Los revisores de cumplimiento de la red publicitaria, los robots de fraude de clics y los competidores ven la página blanca, mientras que los usuarios genuinos de su público objetivo llegan a la página de oferta. El enrutamiento se realiza de forma transparente y a la velocidad del cable.

En Direct Mode, el enrutamiento es completamente automático. Apunta el DNS de su dominio al Magicgate y la plataforma maneja todo el ciclo de vida de la solicitud: recibe al visitante, evalúa los filtros y emite una redirección HTTP (302 de forma predeterminada) al destino apropiado. El visitante nunca ve una página intermedia.

En API Mode, su aplicación llama al punto final /api/v1/check con atributos de visitante y recibe una respuesta JSON que contiene el veredicto y la URL de redireccionamiento recomendada. Luego, su aplicación maneja la redirección por sí misma. Esto le brinda control total sobre la experiencia del usuario: puede agregar lógica personalizada, registro o pruebas A/B antes de redirigir.

Magicgate admite tres modos de visualización para enrutar a los visitantes. 'Redireccionar' (predeterminado) emite una redirección HTTP a la URL de destino. 'Proxy' muestra el contenido de la página de destino en la URL original sin cambiar la barra de direcciones del navegador. 'Iframe' carga la página de destino dentro de un iframe en la URL original. El modo de visualización es configurable por flujo.

Los veredictos se procesan sincrónicamente y se almacenan en caché brevemente para manejar solicitudes sucesivas y rápidas del mismo visitante (por ejemplo, carga de recursos de la página después de la redirección inicial). El TTL de caché se puede configurar por flujo, con un valor predeterminado de 30 segundos.

Magicgate ofrece dos modos de integración distintos, cada uno diseñado para diferentes casos de uso y requisitos técnicos. Elegir el modo correcto afecta la complejidad de la implementación, el control sobre la experiencia del usuario y la sobrecarga operativa.

API Mode es una integración programática. Su aplicación envía una solicitud POST al punto final /api/v1/check con atributos de visitante (dirección IP, agente de usuario, referente, etc.) y recibe una respuesta JSON que contiene el veredicto. Luego, su código maneja el enrutamiento: redirigir los robots a la página blanca y permitir el paso a usuarios reales. Este modo requiere que escriba un código de integración pero le brinda control total sobre el flujo de solicitudes.

Direct Mode es una integración de nivel DNS. Usted configura los registros DNS de su dominio (CNAME a proxy.magicgate.io, o ALIAS/ANAME para dominios raíz) para que apunten a Magicgate. Cuando llega un visitante, Magicgate intercepta de forma transparente la solicitud, evalúa al visitante y emite una redirección HTTP a la página de oferta o a la página blanca. No se necesitan cambios de código en su aplicación: toda la capa de filtrado y enrutamiento se encuentra frente a su servidor de origen.

Ventajas de API Mode: Control total sobre la lógica de enrutamiento. Puede agregar procesamiento personalizado entre la recepción del veredicto y la redirección del usuario: registro, asignación de pruebas A/B, configuración de cookies, eventos analíticos o lógica condicional basada en los metadatos del veredicto. API Mode funciona con cualquier pila de backend y no requiere cambios de DNS. También es ideal para aplicaciones de una sola página (SPA) donde JavaScript del lado del cliente realiza la llamada de verificación.

API Mode desventajas: Requiere cambios de código en su aplicación. Debe manejar la llamada API, los casos de error (tiempos de espera, límites de velocidad) y la lógica de redireccionamiento. La llamada API agrega un viaje de ida y vuelta de la red al tiempo de carga de su página (normalmente entre 10 y 50 ms, dependiendo de la proximidad geográfica al borde de Magicgate).

Ventajas de Direct Mode: Cero cambios de código. Apunte su DNS y configure su flujo: los visitantes se filtran y redirigen automáticamente. Direct Mode es más rápido para el usuario final porque no hay un viaje de ida y vuelta de API adicional; el filtrado ocurre en el borde como parte de la resolución DNS y la solicitud HTTP inicial. También maneja todos los casos extremos (tiempos de espera, reintentos) de forma transparente.

Direct Mode desventajas: Menos control sobre el proceso de enrutamiento. No puede inyectar lógica personalizada entre el veredicto y la redirección. DNS los cambios se propagan lentamente (de minutos a horas), lo que hace que las pruebas y la reversión sean más lentas. Direct Mode requiere que se pueda acceder a su página blanca y a su página de oferta a través de URL públicas.

También es posible un enfoque híbrido. Utilice Direct Mode para sus páginas de destino principales (donde la integración sin código es una prioridad) y API Mode para puntos finales específicos que necesitan un manejo de veredicto personalizado (por ejemplo, envíos de formularios, puntos finales API o flujos de pago).

Cada cuenta de Magicgate tiene acceso a un dominio compartido (go.magicgate.io) para uso inmediato. Los planes Starter y superiores pueden agregar dominios personalizados para URL de marca y señales de confianza mejoradas con redes publicitarias.

Los dominios personalizados le permiten usar su propia URL (por ejemplo, track.yourbrand.com) en lugar del dominio compartido. Esto es importante para el cumplimiento de la publicidad: muchas redes publicitarias son más indulgentes con el tráfico proveniente de dominios de marca en lugar de dominios de seguimiento compartidos.

Magicgate admite subdominios (track.yourbrand.com) y dominios raíz (yourbrand.com). Se recomiendan los subdominios porque no interfieren con la configuración DNS de su sitio web principal y son más fáciles de administrar.

La verificación del dominio utiliza registros CNAME que apuntan a proxy.magicgate.io. Cuando agrega un dominio, configura un registro CNAME de su dominio en proxy.magicgate.io. Para dominios raíz que no admiten registros CNAME, utilice un registro ALIAS o ANAME que apunte a proxy.magicgate.io. Magicgate verifica la propiedad comprobando que el registro DNS se resuelva correctamente en el punto final del proxy.

Los certificados SSL se aprovisionan automáticamente a través de Let's Encrypt una vez que se completa la propagación de DNS. Magicgate se encarga de la emisión, renovación e instalación de certificados. Su dominio personalizado atenderá el tráfico a través de HTTPS con un certificado válido a los pocos minutos de la configuración de DNS.

Para los usuarios de Cloudflare, asegúrese de que el proxy (nube naranja) esté deshabilitado para el registro CNAME que apunta a Magicgate. El proxy de Cloudflare intercepta el tráfico antes de que llegue a Magicgate, lo que puede interferir con la evaluación de los visitantes. Configure el registro en modo 'Solo DNS' (nube gris).

También puedes comprar dominios directamente a través del mercado de Magicgate. Estos dominios están preconfigurados y listos para usar de inmediato, no se requiere configuración ni verificación de DNS. El mercado ofrece una selección de dominios limpios adecuados para campañas de tráfico.

Webhooks le permite recibir notificaciones POST HTTP en tiempo real cuando ocurren eventos importantes en su cuenta Magicgate, como cambios de flujo, verificación de dominio o actualizaciones de pagos.

Magicgate admite eventos de webhook en múltiples categorías: eventos de flujo (flow.created, flow.updated, flow.deleted), eventos de dominio (domain.added, domain.verified, domain.deleted, domain.registration_failed), eventos de página blanca (white_page.ready, white_page.failed, white_page.deleted), eventos de lista negra (blacklist.created, blacklist.updated, blacklist.deleted), eventos API key (apikey.created, apikey.deleted, apikey.activated, apikey.deactivated), eventos de billetera (wallet.credited, wallet.debited), eventos de suscripción (subscription.changed, subscription.canceled, suscripción.plan_changed y más), eventos de facturación (payment.completed, payment.failed) y eventos de soporte (ticket.created, ticket.replied, ticket.resolved, ticket.closed).

Cada entrega de webhook incluye tres encabezados de seguridad: X-Webhook-Signature (resumen hexadecimal HMAC-SHA256), X-Webhook-Timestamp (marca de tiempo de Unix) y X-Webhook-ID (identificador de punto final). La firma cubre la marca de tiempo y el cuerpo juntos, calculados como HMAC-SHA256 (secreto, marca de tiempo + '.' + cuerpo), lo que evita ataques de manipulación y repetición. Debe verificar la firma y rechazar las solicitudes con marcas de tiempo de más de 5 minutos. El secreto de firma se genera cuando crea el punto final del webhook y se muestra una vez; guárdelo de forma segura.

Magicgate reintenta entregas fallidas de webhook. Si su punto final devuelve un código de estado que no es 2xx o no responde dentro de los 10 segundos, se vuelve a intentar la entrega. Una vez agotados todos los reintentos, el evento se marca como fallido y se incrementa el recuento de errores del punto final.

Las cargas útiles Webhook están codificadas en JSON con la estructura: { id, event, timestamp, data }. El campo 'evento' contiene la cadena del tipo de evento (por ejemplo, 'domain.verified'), 'id' es un ID de entrega único para idempotencia, 'marca de tiempo' es una fecha y hora ISO 8601 y 'datos' contiene detalles específicos del evento.

Puede configurar varios puntos finales de webhook por cuenta, cada uno de los cuales está suscrito a diferentes tipos de eventos. Esto le permite enrutar eventos de dominio a su proceso de implementación y eventos de facturación a su sistema de contabilidad, por ejemplo.

Magicgate utiliza un modelo de facturación basado en billetera. Agrega fondos a su billetera mediante depósitos criptográficos y su suscripción se renueva automáticamente desde el saldo de la billetera en cada ciclo de facturación. Esto elimina la necesidad de realizar cargos recurrentes en la tarjeta y proporciona un control total sobre sus gastos.

Se admiten tres proveedores de pago: CCPayment, NowPayments y TransVoucher. Cada proveedor admite Bitcoin, Ethereum, USDT, USDC y más de 50 criptomonedas adicionales. Cuando inicia un depósito, se generan una dirección de pago y un monto. Una vez que blockchain confirma la transacción, el saldo de su billetera se actualiza automáticamente.

Los planes determinan los límites de sus funciones: comprobaciones por mes, cantidad de flujos, reglas por flujo, acceso a API, dominios personalizados y más. Puede ver los planes disponibles sin autenticación. La actualización o degradación entra en vigor de inmediato: el saldo no utilizado del período actual se prorratea y se acredita en su billetera.

Las suscripciones pueden ser mensuales o anuales. Las suscripciones anuales ofrecen un descuento. Puede cancelar en cualquier momento: la suscripción permanece activa hasta el final del período de facturación actual. Reanudar una suscripción cancelada la restaura sin crear una nueva.

La billetera rastrea todas las transacciones: depósitos, cargos de suscripción, reembolsos y créditos de prorrateo. Cada transacción incluye un tipo de referencia y un ID que la vincula con el evento que la origina (depósito, renovación de suscripción, cambio de plan, etc.).

El panel de Magicgate es su panel de control central para administrar los flujos de tráfico, monitorear análisis y configurar los ajustes de la cuenta. Después de iniciar sesión, accederá a la página Descripción general que muestra un resumen de las métricas clave de su cuenta.

La página Descripción general muestra el total de cheques procesados, la distribución de veredictos (oferta versus blanco), flujos activos y actividad reciente. Un gráfico de serie temporal muestra el volumen de tráfico durante las últimas 24 horas, 7 días o 30 días. Esto le brinda una idea inmediata del estado del tráfico y la eficacia del filtrado.

La sección Flujos es donde crea y administra los flujos de tráfico. Cada flujo representa una configuración de filtrado distinta: un conjunto de filtros, una URL de página de oferta, una URL de página blanca y configuraciones de integración (API Mode o Direct Mode). Puede tener varios flujos para diferentes campañas, páginas de destino o fuentes de tráfico.

Dentro de la vista detallada de cada flujo, puede ver análisis por flujo: verificaciones totales, desglose de veredictos, tasas de aciertos de filtros, distribución geográfica y principales referentes. Estos datos granulares le ayudan a optimizar la configuración de filtro para cada campaña específica.

La sección Análisis proporciona una vista completa de todos los flujos. Los gráficos incluyen tendencias de veredicto a lo largo del tiempo, efectividad de los filtros (qué filtros activan con mayor frecuencia), mapas de calor geográficos que muestran el origen del tráfico, averías de dispositivos y navegadores, y patrones de tráfico por hora. Todos los gráficos admiten filtrado de rango de fechas y filtrado específico de flujo.

La sección Dominios enumera todos los dominios configurados (compartidos y personalizados). Para cada dominio, puede ver su estado (activo, pendiente de verificación, error de DNS), el estado del certificado SSL y los flujos asociados. Las comprobaciones del estado del dominio se ejecutan automáticamente y le avisan si se detectan problemas de DNS o SSL.

La sección Configuración contiene configuración para toda la cuenta. Claves API: genere y administre API key con fechas de vencimiento opcionales. Webhooks: configurar puntos finales de webhook y ver registros de entrega. Proveedores: agregue y administre pagos y proveedores DNS. Facturación: vea el saldo de la billetera, el historial de recargas y el estado de la suscripción. Equipo: invite a miembros del equipo con acceso basado en roles (usuario, administrador).

El panel admite temas claros y oscuros, con el tema para alternar en la esquina superior derecha. Todas las páginas responden y funcionan en dispositivos móviles, aunque la experiencia de escritorio proporciona las vistas de datos más completas.