Purple Portal API: qué se puede hacer con ella

Resumen ejecutivo

Para los responsables de TI en centros con múltiples ubicaciones (hoteles, cadenas de retail, estadios y centros de conferencias), la red WiFi para invitados es más que un simple servicio. Es una fuente rica y continuamente actualizada de datos de primera mano que puede generar un impacto empresarial medible en el marketing, las operaciones y la experiencia del cliente. La API de Purple Portal proporciona la interfaz programática necesaria para liberar este valor a escala. Permite a los equipos técnicos ir más allá de los paneles de análisis integrados y crear integraciones sólidas y automatizadas que introducen datos de visitantes que cumplen con el GDPR directamente en los sistemas empresariales principales, desde plataformas CRM y herramientas de automatización de marketing hasta programas de fidelización y almacenes de inteligencia empresarial.

Esta guía es una referencia práctica y útil para arquitectos de soluciones, responsables de TI y desarrolladores sénior. Detalla el modelo de autenticación, los endpoints disponibles, los patrones de integración y los escenarios de implementación en el mundo real que demuestran cómo la API de Purple WiFi puede transformar una implementación WiFi de un centro de costes a un activo de datos estratégico. Tanto si está evaluando la API por primera vez como si está planificando una integración de nivel de producción, este documento le proporciona la base técnica y los marcos de decisión que necesita para proceder con confianza.

Análisis técnico detallado

Autenticación y control de versiones de la API

La API de Purple Portal utiliza autenticación por clave API, un modelo sencillo y seguro muy adecuado para integraciones de servidor a servidor. A diferencia de los flujos de OAuth 2.0, que requieren ciclos de intercambio y actualización de tokens, la autenticación por clave API consiste en incluir un secreto estático en las cabeceras de la solicitud. Esta simplicidad reduce los costes de integración sin comprometer la seguridad, siempre que la clave se guarde de forma segura y se rote periódicamente como parte de su política estándar de gestión de credenciales.

La versión de producción actual es la v1.7, que introdujo varias mejoras importantes con respecto a la v1.6.2. Lo más significativo es que la propiedad unsubscribed en el objeto de datos del usuario ahora distingue claramente entre un usuario que canceló activamente la suscripción al marketing después de haber estado suscrito previamente y un usuario que nunca se suscribió. Esta distinción es fundamental para cumplir con el GDPR y para una segmentación precisa de la audiencia. Además, los endpoints de Visitors y Venues ahora devuelven una respuesta HTTP 200 OK cuando no se encuentran datos, en lugar de un 404 Not Found, lo que anteriormente causaba confusión en la lógica de monitorización y gestión de errores.

Endpoints disponibles

La API de Purple Portal expone tres categorías principales de endpoints con las que los equipos de TI interactuarán de forma habitual.

Todos los endpoints devuelven datos en formato JSON. El endpoint visitors es el más utilizado, ya que expone toda la riqueza de los datos del perfil de invitado recopilados durante el proceso de autenticación del Captive Portal. Esto incluye nombre, apellidos, dirección de correo electrónico, género, fecha de nacimiento, número de móvil, código postal, proveedor de autenticación (por ejemplo, formulario de registro, inicio de sesión social), recuento de visitas por ubicación y cualquier campo personalizado configurado en la página de inicio (splash page).

Límites de velocidad

Una ventaja arquitectónica clave de la API de Purple Portal es que no existen límites de velocidad. La plataforma está diseñada para admitir cualquier volumen de solicitudes o transacciones, lo que la hace adecuada para implementaciones a gran escala donde los scripts pueden necesitar procesar miles de registros de ubicaciones o millones de perfiles de visitantes. Esto elimina una restricción común que complica el diseño de la integración con otras plataformas y evita la necesidad de limitar las solicitudes o implementar una lógica de retroceso en su código de cliente.

Patrones de integración: Pull frente a Push

La API de Purple WiFi admite dos patrones de integración fundamentalmente diferentes, cada uno adecuado para distintos casos de uso. Comprender qué patrón aplicar en un escenario determinado es la decisión arquitectónica más importante que tomará.

El patrón pull de la REST API implica que su sistema realice solicitudes bajo demanda o programadas a los endpoints de la API para recuperar datos. Este es el enfoque correcto para el procesamiento por lotes, la generación de informes y la inteligencia empresarial. Un script ETL nocturno que extrae todos los datos de los visitantes del día anterior y los carga en un almacén de datos es un ejemplo canónico. El patrón pull le brinda un control total sobre cuándo y cuántos datos recupera.

El patrón push de Webhook implica que Purple envía datos a su sistema en el momento en que ocurre un evento específico, concretamente, cuando un invitado se autentica en la red WiFi. Su sistema debe exponer un endpoint HTTP accesible públicamente y protegido por SSL (un "oyente" o listener) que pueda recibir y procesar estas cargas útiles JSON POST. El patrón Webhook es la opción correcta para cualquier caso de uso que requiera datos casi en tiempo real, como activar un mensaje de bienvenida personalizado, actualizar el estado de "última visita" de un cliente en un CRM o notificar a un gerente de hostelería que ha llegado un invitado VIP.

Estructura de la carga útil del Webhook

La carga útil JSON entregada por un Webhook de Purple se estructura en cuatro objetos principales, cada uno de los cuales proporciona una dimensión diferente de contexto para el evento de autenticación.

El objeto user.visitCountForVenues es especialmente valioso para los operadores con múltiples sedes. Proporciona un recuento de visitas por sede junto con las marcas de tiempo de firstVisit y lastVisit, lo que le permite identificar a los visitantes que vienen por primera vez frente a los clientes habituales fidelizados en el momento de la autenticación, sin necesidad de realizar llamadas de API adicionales.

Guía de implementación

Prerrequisitos y configuración

El acceso a la API del portal requiere una licencia Engage. Una vez que tenga la licencia, genere su clave de API desde los ajustes del portal de Purple. Para el desarrollo y las pruebas iniciales, se recomienda la herramienta Postman; Purple proporciona una guía de configuración específica para configurar las variables de entorno y las cabeceras de solicitud correctas. También hay disponible un archivo de demostración en PHP para los equipos que prefieran un punto de partida basado en scripts del lado del servidor.

Configuración de una integración de Webhook

La implementación de una integración de Webhook implica cinco pasos. En primer lugar, cree y despliegue su endpoint receptor en una URL accesible públicamente y protegida por SSL. Una función sin servidor (AWS Lambda, Azure Functions o Google Cloud Functions) es una opción de arquitectura excelente: se escala automáticamente, genera un coste mínimo con volúmenes bajos y gestiona solicitudes simultáneas sin necesidad de configuración. En segundo lugar, valide la URL del receptor en el portal de Purple accediendo a Gestión > Sedes > Webhooks. Purple enviará una solicitud de prueba para confirmar que se puede acceder al endpoint y que este devuelve la cabecera wifiWebhookListener: 1 requerida. En tercer lugar, cree o edite un LogicFlow en el portal y añada un nodo de acción de Webhook, seleccionando su URL validada. En cuarto lugar, asegúrese de que el estado de LogicFlow esté establecido en "Online". En quinto lugar, asocie el LogicFlow a la página de inicio de sesión de acceso correspondiente. A partir de ese momento, cada autenticación de invitado en ese proceso activará su Webhook.

Gestión de reintentos e idempotencia

Su receptor debe estar diseñado para hacer frente a las realidades de los sistemas distribuidos. Purple volverá a intentar el envío de un Webhook fallido transcurridas tres horas si su receptor no responde (el tiempo de espera supera los 10 segundos) o si devuelve un estado de error. Esto significa que su receptor puede recibir el mismo evento varias veces. Además, una sola visita de un invitado puede desencadenar varios eventos de autenticación, por ejemplo, cuando un dispositivo se vuelve a conectar después de que se bloquee la pantalla o cuando un usuario se desplaza entre diferentes puntos de acceso. Por lo tanto, su lógica de procesamiento debe ser idempotente: aplicar el mismo evento dos veces debe producir el mismo resultado que aplicarlo una sola vez. Un patrón de implementación habitual consiste en comprobar si ya se ha realizado una acción (como enviar un correo electrónico de bienvenida) para un ID de usuario determinado dentro de un intervalo de tiempo definido antes de ejecutarla.

Prácticas recomendadas

Varios principios deben guiar cualquier despliegue en producción de la Purple Portal API. Despliegue siempre apuntando a la última versión de la API (v1.7) y actualice las rutas de sus URL y la lógica de análisis de respuestas cuando se publiquen nuevas versiones. Trate su API Key como una credencial sensible: almacénela en un gestor de secretos (como AWS Secrets Manager o Azure Key Vault) en lugar de en el código fuente o en variables de entorno en sistemas compartidos. Para los oyentes de Webhooks, implemente un registro estructurado de cada carga útil entrante y respuesta para facilitar la depuración y las pistas de auditoría. Respete los campos unsubscribed y unsubscribedDate en el objeto de usuario; procesar acciones de marketing dirigidas a usuarios que han optado por excluirse constituye una infracción del GDPR. Por último, pruebe su integración frente a toda la gama de casos límite: usuarios sin dirección de correo electrónico, usuarios con campos personalizados nulos y eventos de autenticación que llegan fuera de orden cronológico.

Resolución de problemas y mitigación de riesgos

El modo de fallo más común en una integración de Webhooks es un oyente lento o no disponible. Si el punto de conexión falla sistemáticamente al responder en un plazo de 10 segundos, Purple desactivará automáticamente el Webhook tras un periodo prolongado de falta de respuesta, lo que requerirá una reverificación manual en el portal. Para mitigar este riesgo, implemente un punto de conexión de comprobación de estado en el mismo servidor que su oyente e inclúyalo en la monitorización de su infraestructura. Asegúrese de que su oyente realice solo un procesamiento síncrono mínimo antes de devolver una respuesta 200 OK; descargue cualquier cálculo pesado o llamadas a API secundarias en una cola asíncrona.

Para las integraciones de la API REST, el riesgo principal es la obsolescencia de los datos en los sistemas secundarios si el trabajo de extracción programado falla de forma silenciosa. Implemente alertas en sus scripts ETL para notificar al equipo de operaciones si una ejecución falla o no produce resultados de forma inesperada. Al migrar de la API v1.6.2 a la v1.7, audite todo el código que haga referencia al campo unsubscribed y al punto de conexión Unsubscribes, ya que el nombre de la propiedad se corrigió de unsubcribers a unsubscribers en la v1.7.

ROI e impacto empresarial

La justificación comercial para la integración con la API de Purple Hub está plenamente consolidada en múltiples sectores. En el sector hotelero, los hoteles que utilizan integraciones CRM activadas por Webhooks informan de mejoras significativas en las tasas de apertura de correo electrónico para comunicaciones personalizadas en comparación con las campañas genéricas, ya que el mensaje se entrega en el momento de máxima relevancia: cuando el huésped se encuentra físicamente en el establecimiento. En el sector minorista, conectar los datos de WiFi de invitados con un programa de fidelización permite a los operadores identificar y recompensar a los visitantes de alta frecuencia, incrementando el gasto medio y las tasas de visitas repetidas. Para grandes recintos públicos y centros de conferencias, las analíticas impulsadas por API proporcionan los datos detallados de afluencia necesarios para justificar las valoraciones de patrocinios y optimizar la ubicación de las concesiones.

La ausencia de límites de tarifa en la API de Purple WiFi significa que el coste de la integración escala con su infraestructura, no con el volumen de datos que procese. Para una cadena minorista nacional que procesa cientos de miles de autenticaciones diarias, esto representa una ventaja sustancial frente a las plataformas que cobran por llamada a la API o imponen límites de rendimiento. Por lo tanto, el coste total de propiedad para una integración de la API de Purple bien estructurada consiste principalmente en el coste de desarrollo de una sola vez y el coste de infraestructura continuo del receptor, los cuales se recuperan normalmente durante el primer trimestre únicamente a través de la mejora en las tasas de conversión de marketing.

Casos de estudio

Caso de estudio 1: Hostelería - Whitbread Group

Whitbread, la mayor empresa de hoteles y restaurantes del Reino Unido, opera miles de puntos de acceso WiFi para invitados en todo su patrimonio de Premier Inn y restaurantes. Al integrar la API de Purple Hub con su plataforma CRM, el grupo pudo crear un perfil de invitado unificado que combinaba los datos de reserva en línea con el comportamiento de visita física capturado en el Captive Portal de WiFi. La integración de Webhooks se activa con cada autenticación de invitado, enriqueciendo el registro del CRM con la marca de tiempo de la última visita, la ubicación del establecimiento y la información del dispositivo. Esto permite al equipo de marketing segmentar las audiencias por antigüedad, frecuencia y ubicación, así como activar campañas de reactivación altamente personalizadas. El resultado técnico clave fue una reducción en el tiempo transcurrido entre la llegada de un invitado y su incorporación a un flujo de marketing activo, pasando de 24 horas (bajo el modelo anterior de consulta por lotes) a menos de 60 segundos.

Caso de estudio 2: Comercio minorista - Distribuidor de moda con múltiples tiendas

Un minorista nacional de moda con más de 80 tiendas implementó la API de Purple Portal para solucionar una brecha crítica en su estrategia de datos de clientes: disponían de sólidos datos de comercio electrónico, pero prácticamente no tenían información sobre el comportamiento de los visitantes en las tiendas físicas. Al conectar la API de WiFi para invitados de Purple con su almacén de datos existente mediante un proceso ETL nocturno, crearon una vista de cliente multicanal por primera vez. Se realizaban consultas al endpoint /visitors para cada tienda todas las noches, y los datos se unían con los registros de transacciones de comercio electrónico utilizando la dirección de correo electrónico como clave común. En un plazo de tres meses, el equipo de analítica identificó que los clientes que se conectaban al WiFi de la tienda tenían un valor medio de pedido un 34% mayor en su siguiente compra online, lo que proporcionó un caso de negocio convincente para realizar más inversiones en la experiencia digital en tienda. La integración no requirió cambios en la infraestructura de comercio electrónico existente, lo que demuestra la naturaleza de baja fricción del patrón de extracción de la API REST.

Caso de estudio 3: Eventos - Centro de conferencias

Un importante centro de conferencias del Reino Unido utilizó la API de Purple Portal para proporcionar por primera vez a los patrocinadores datos verificados de afluencia. Anteriormente, los informes de los patrocinadores dependían de recuentos manuales y lecturas de acreditaciones, métodos que requerían mucha mano de obra y resultaban imprecisos. Al exponer recuentos de visitantes agregados y anonimizados por zona (asociados a IDs de ubicaciones en la plataforma Purple) a través de la API, el equipo de eventos pudo ofrecer a los patrocinadores paneles de control en tiempo real que mostraban el tiempo de permanencia y el volumen de visitantes en las zonas patrocinadas. Los datos se extraían mediante la API REST cada 15 minutos durante los eventos y se mostraban en un portal de patrocinadores creado a medida. Esta capacidad contribuyó directamente a un aumento del 22% en las tasas de renovación de patrocinio en el primer año, ya que los patrocinadores ahora podían cuantificar el alcance de sus activaciones con datos de primera mano verificados.