API de Purple Hub: Qué se puede hacer con ella

Resumen Ejecutivo

Para los líderes de TI en recintos multi-sitio - hoteles, cadenas de tiendas, estadios y centros de conferencias - la red WiFi para invitados es más que un simple servicio. Es una fuente rica y constantemente actualizada de datos de primera mano que puede impulsar un impacto comercial medible en marketing, operaciones y 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 tableros de analítica integrados y crear integraciones sólidas y automatizadas que alimentan datos de visitantes que cumplen con el GDPR directamente en los sistemas de negocio principales, desde plataformas CRM y herramientas de automatización de marketing hasta programas de lealtad y almacenes de inteligencia de negocios.

Esta guía es una referencia práctica y accionable para arquitectos de soluciones, gerentes de TI y desarrolladores senior. Detalla el modelo de autenticación, los endpoints disponibles, los patrones de integración y los escenarios de implementación del mundo real que demuestran cómo la API de Purple WiFi puede transformar una implementación de WiFi de un centro de costos a un activo de datos estratégico. Ya sea que esté evaluando la API por primera vez o planeando una integración de nivel de producción, este documento proporciona el sustento técnico 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 API Key, un modelo sencillo y seguro muy adecuado para integraciones de servidor a servidor. A diferencia de los flujos de OAuth 2.0, que requieren intercambio de tokens y ciclos de renovación, la autenticación por API Key consiste en incluir un secreto estático en los encabezados de la solicitud. Esta simplicidad reduce la complejidad de la integración sin comprometer la seguridad, siempre que la clave se almacene 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, la cual introdujo varias mejoras importantes sobre la v1.6.2. De manera muy significativa, la propiedad unsubscribed en el objeto de datos del usuario ahora distingue claramente entre un usuario que canceló activamente su suscripción de marketing después de haber estado suscrito previamente, y un usuario que nunca se suscribió. Esta distinción es crítica para el cumplimiento de 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 monitoreo y manejo de errores.

Endpoints Disponibles

La API de la empresa del portal expone tres categorías principales de endpoints con las que los equipos de TI interactuarán regularmente.

Todos los endpoints devuelven datos en formato JSON. El endpoint de 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, apellido, dirección de correo electrónico, género, fecha de nacimiento, número de teléfono móvil, código postal, proveedor de autenticación (por ejemplo, formulario de registro, inicio de sesión social), recuentos de visitas por sucursal y cualquier campo personalizado configurado en la splash page.

Límites de velocidad

Una ventaja arquitectónica clave de la API de Purple Portal es que no hay 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 sucursales o millones de perfiles de visitantes. Esto elimina una restricción común que complica el diseño de integración con otras plataformas y elimina la necesidad de limitar las solicitudes o implementar lógica de back-off en su código de cliente.

Patrones de integración: Pull vs. Push

La API de Purple WiFi admite dos patrones de integración fundamentalmente diferentes, cada uno adecuado para diferentes 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 de extracción REST API (pull) 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, informes e inteligencia de negocios. 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 control total sobre cuándo y cuántos datos recupera.

El patrón de inserción Webhook (push) implica que Purple envíe datos a su sistema en el momento en que ocurre un evento específico - específicamente, cuando un invitado se autentica en la red WiFi. Su sistema debe exponer un endpoint HTTP accesible públicamente y protegido por SSL (un "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 hotelería que ha llegado un invitado VIP.

Estructura de la carga útil de Webhook

La carga útil JSON entregada por un Webhook de Purple está estructurada 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 sucursales. Proporciona un conteo de visitas por sucursal junto con las marcas de tiempo de firstVisit y lastVisit, lo que le permite identificar a los visitantes primerizos frente a los clientes recurrentes leales en el momento de la autenticación - sin necesidad de realizar llamadas API adicionales.

Guía de implementación

Prerrequisitos y configuración

El acceso a la API del portal requiere una licencia de Purple Engage. Una vez obtenida la licencia, genere su clave API desde la configuración del portal de Purple. Para el desarrollo y las pruebas iniciales, Postman es la herramienta recomendada; Purple proporciona una guía de configuración dedicada para configurar las variables de entorno y los encabezados de solicitud correctos. También está disponible un archivo de demostración en PHP para los equipos que prefieran un punto de partida de programación del lado del servidor.

Configuración de una integración de Webhook

La implementación de una integración de Webhook consta de cinco pasos. Primero, compile e implemente su endpoint de escucha en una URL de acceso público y protegida por SSL. Una función sin servidor (AWS Lambda, Azure Functions o Google Cloud Functions) es una opción de arquitectura sólida: se escala automáticamente, incurre en un costo mínimo con volúmenes bajos y gestiona solicitudes concurrentes sin necesidad de configuración. Segundo, valide la URL del endpoint de escucha en el portal de Purple navegando a Administración > Sucursales > Webhooks. Purple enviará una solicitud de prueba para confirmar que el endpoint está accesible y devuelve el encabezado requerido wifiWebhookListener: 1. Tercero, cree o edite un LogicFlow en el portal y agregue un nodo de acción de Webhook, seleccionando su URL validada. Cuarto, asegúrese de que el estado del LogicFlow esté configurado como "En línea". Quinto, asocie el LogicFlow al proceso de acceso (Access Journey) correspondiente. A partir de este momento, cada autenticación de invitado en ese proceso activará su Webhook.

Gestión de reintentos e idempotencia

Su endpoint de escucha debe estar diseñado para hacer frente a las realidades de los sistemas distribuidos. Purple reintentará la entrega de un Webhook fallido después de tres horas si su endpoint de escucha no responde (el tiempo de espera supera los 10 segundos) o si devuelve un estado de error. Esto significa que su endpoint de escucha puede recibir el mismo evento varias veces. Además, una sola visita de un invitado puede activar múltiples eventos de autenticación - por ejemplo, cuando un dispositivo se vuelve a conectar después de que la pantalla se bloquea, o cuando un usuario realiza roaming entre 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 común consiste en verificar 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 periodo de tiempo definido antes de ejecutarla.

Mejores prácticas

Varios principios deben guiar cualquier implementación en producción de la Purple Portal API. Siempre realice la implementación apuntando a la versión más reciente de la API (v1.7) y actualice sus rutas de URL y la lógica de análisis de respuestas cuando se lancen nuevas versiones. Trate su API Key como una credencial confidencial: almacénela en un administrador de secretos (como AWS Secrets Manager o Azure Key Vault) en lugar de hacerlo 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 los seguimientos 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 no participar constituye una infracción del GDPR. Finalmente, pruebe su integración con 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 del 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 Webhook 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 después de un período prolongado de falta de respuesta, lo que requerirá una verificació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 el monitoreo de su infraestructura. Asegúrese de que su oyente realice solo un procesamiento síncrono mínimo antes de devolver una respuesta 200 OK; delegue cualquier cálculo pesado o llamadas de API secundarias a una cola asíncrona.

Para las integraciones de la REST API, 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 de ETL para notificar al equipo de operaciones si una ejecución falla o no genera resultados de manera inesperada. Al migrar de la API v1.6.2 a la v1.7, audite todo el código que hace 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 comercial

El caso de negocio para la integración con la Purple Portal API está bien consolidado en múltiples sectores verticales. En el sector de la hospitalidad, los hoteles que utilizan integraciones de CRM activadas por Webhooks reportan mejoras significativas en las tasas de apertura de correos electrónicos para comunicaciones personalizadas en comparación con las campañas de difusión 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 a un programa de fidelidad permite a los operadores identificar y recompensar a los visitantes de alta frecuencia, incrementando el gasto promedio y las tasas de visitas recurrentes. Para grandes recintos públicos y centros de conferencias, los análisis impulsados 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 Purple WiFi API significa que el costo de la integración se escala con su infraestructura, no con el volumen de datos que procesa. Para una cadena minorista nacional que procesa cientos de miles de autenticaciones diarias, esta es una ventaja material frente a las plataformas que cobran por llamada de API o imponen límites de rendimiento. Por lo tanto, el costo total de propiedad para una integración de Purple API bien estructurada consiste principalmente en el costo de desarrollo de una sola vez y el costo de infraestructura continuo del receptor, los cuales se recuperan típicamente dentro del primer trimestre únicamente a través de la mejora en las tasas de conversión de marketing.

Casos de estudio

Caso de estudio 1: Hospitalidad - Whitbread Group

Whitbread, la compañía de hoteles y restaurantes más grande del Reino Unido, opera miles de puntos de acceso WiFi para invitados en todas sus propiedades de Premier Inn y restaurantes. Al integrar la Purple Portal API con su plataforma de CRM, el grupo pudo crear un perfil de invitado unificado que combinaba los datos de reservaciones en línea con el comportamiento de visitas físicas registrado en el Captive Portal de WiFi. La integración de Webhook 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 entre la llegada de un invitado y su ingreso a un flujo de marketing activo 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 multisitio

Un minorista nacional de moda con más de 80 tiendas implementó la Purple Portal API para resolver una brecha crítica en su estrategia de datos de clientes: tenían datos sólidos de comercio electrónico pero prácticamente ninguna información sobre el comportamiento de los visitantes en la tienda. Al conectar la API de WiFi para invitados de Purple a su almacén de datos existente mediante un proceso ETL nocturno, crearon una vista de cliente omnicanal por primera vez. Se consultaba el 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 tres meses, el equipo de analítica identificó que los clientes que se conectaban al WiFi de la tienda tenían un valor promedio de pedido un 34% más alto en su siguiente compra en línea, lo que proporcionó un caso de negocio sólido para una mayor inversión en la experiencia digital dentro de la 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 en el Reino Unido utilizó la Purple Portal API para proporcionar a los patrocinadores datos verificados de afluencia por primera vez. Anteriormente, los informes de los patrocinadores dependían de recuentos manuales y escaneo de credenciales, lo que requería mucha mano de obra y era impreciso. Al exponer recuentos de visitantes agregados y anonimizados por zona (mapeados a IDs de ubicaciones en la plataforma Purple) a través de la API, el equipo de eventos pudo proporcionar a los patrocinadores tableros en tiempo real que mostraban el tiempo de permanencia y el volumen de visitantes en las áreas patrocinadas. Los datos se extraían a través de la API REST cada 15 minutos durante los eventos y se mostraban en un portal de patrocinadores personalizado. Esta capacidad contribuyó directamente a un aumento del 22% en las tasas de renovación de patrocinios en el primer año, ya que los patrocinadores ahora podían cuantificar el alcance de sus activaciones con datos de primera parte verificados.