Purple Portal API: What You Can Do With It

Resumo Executivo

Para líderes de TI em locais com múltiplas unidades — hotéis, redes de varejo, estádios e centros de convenções —, a rede WiFi de convidados é mais do que uma simples comodidade. É uma fonte rica e continuamente atualizada de dados primários (first-party data) que pode gerar impacto comercial mensurável em marketing, operações e experiência do cliente. A Purple Portal API fornece a interface programática necessária para desbloquear esse valor em escala. Ela permite que as equipes técnicas vão além dos painéis de análise integrados e construam integrações robustas e automatizadas que alimentam dados de visitantes em conformidade com a GDPR diretamente nos sistemas de negócios principais, desde plataformas de CRM e ferramentas de automação de marketing até programas de fidelidade e armazéns de business intelligence (BI).

Este guia é uma referência prática e acionável para arquitetos de soluções, gerentes de TI e desenvolvedores seniores. Ele detalha o modelo de autenticação, os endpoints disponíveis, os padrões de integração e os cenários de implantação do mundo real que demonstram como a Purple WiFi API pode transformar uma implantação de WiFi de um centro de custo em um ativo de dados estratégico. Quer você esteja avaliando a API pela primeira vez ou planejando uma integração em nível de produção, este documento fornece a base técnica e as estruturas de decisão necessárias para prosseguir com confiança.

Aprofundamento Técnico

Autenticação e Versionamento da API

A Purple Portal API usa autenticação por API Key, um modelo simples e seguro, ideal para integrações servidor a servidor. Ao contrário dos fluxos do OAuth 2.0, que exigem troca de tokens e ciclos de atualização, a autenticação por API Key envolve a inclusão de um segredo estático nos cabeçalhos das requisições. Essa simplicidade reduz a complexidade da integração sem comprometer a segurança, desde que a chave seja armazenada de forma segura e rotacionada periodicamente como parte de sua política padrão de gerenciamento de credenciais.

A versão de produção atual é a v1.7, que introduziu várias melhorias importantes em relação à v1.6.2. O mais significativo é que a propriedade unsubscribed no objeto de dados do usuário agora distingue claramente entre um usuário que cancelou ativamente a assinatura de marketing após ter se inscrito anteriormente e um usuário que nunca se inscreveu. Essa distinção é crítica para a conformidade com a GDPR e para a segmentação precisa do público. Além disso, os endpoints de Visitors e Venues agora retornam uma resposta HTTP 200 OK quando nenhum dado é encontrado, em vez de um 404 Not Found, o que antes causava confusão na lógica de monitoramento e tratamento de erros.

Endpoints Disponíveis

A Portal Company API expõe três categorias principais de endpoints com as quais as equipes de TI interagirão regularmente.

Todos os endpoints retornam dados no formato JSON. O endpoint visitors é o mais comumente utilizado, pois expõe toda a riqueza dos dados de perfil dos visitantes coletados durante a jornada de autenticação no Captive Portal. Isso inclui nome, sobrenome, endereço de e-mail, gênero, data de nascimento, número de celular, código postal, provedor de autenticação (por exemplo, formulário de registro, login social), contagem de visitas por local e quaisquer campos personalizados configurados na splash page.

Limites de Taxa (Rate Limits)

Uma vantagem arquitetônica fundamental da Purple Portal API é que não há limites de taxa. A plataforma foi projetada para suportar qualquer volume de requisições ou transações, tornando-a adequada para implantações em grande escala onde os scripts podem precisar processar milhares de registros de locais ou milhões de perfis de visitantes. Isso remove uma restrição comum que complica o design de integração com outras plataformas e elimina a necessidade de limitação de requisições ou lógica de back-off no código do seu cliente.

Padrões de Integração: Pull vs. Push

A Purple WiFi API suporta dois padrões de integração fundamentalmente diferentes, cada um adequado para diferentes casos de uso. Entender qual padrão aplicar em um determinado cenário é a decisão arquitetônica mais importante que você tomará.

O padrão de pull da REST API envolve o seu sistema fazendo requisições sob demanda ou agendadas para os endpoints da API para recuperar dados. Esta é a abordagem correta para processamento em lote, relatórios e business intelligence. Um script ETL noturno que extrai todos os dados de visitantes do dia anterior e os carrega em um data warehouse é um exemplo clássico. O padrão pull oferece controle total sobre quando e quantos dados você recupera.

O padrão de push de Webhook envolve a Purple enviando dados para o seu sistema no momento em que um evento específico ocorre — especificamente, quando um visitante se autentica na rede WiFi. Seu sistema deve expor um endpoint HTTP publicamente acessível e protegido por SSL (um 'listener') que possa receber e processar esses payloads JSON POST. O padrão Webhook é a escolha correta para qualquer caso de uso que exija dados em tempo real, como o disparo de uma mensagem de boas-vindas personalizada, a atualização do status de 'última visita' de um cliente em um CRM ou a notificação a um gerente de hospitalidade de que um visitante VIP chegou.

Estrutura do Payload do Webhook

O payload JSON entregue por um Webhook da Purple é estruturado em quatro objetos principais, cada um fornecendo uma dimensão diferente de contexto para o evento de autenticação.

O objeto user.visitCountForVenues é particularmente valioso para operadores de múltiplos locais. Ele fornece uma contagem de visitas por local junto com os carimbos de data/hora de firstVisit e lastVisit, permitindo identificar visitantes de primeira viagem versus clientes recorrentes fiéis no momento da autenticação — sem chamadas de API adicionais.

Guia de Implementação

Pré-requisitos e Configuração

O acesso à Portal API requer uma licença Engage. Uma vez licenciado, gere sua API Key nas configurações do portal Purple. Para o desenvolvimento e testes iniciais, o Postman é a ferramenta recomendada; a Purple fornece um guia de configuração dedicado para configurar as variáveis de ambiente e os cabeçalhos de solicitação corretos. Um arquivo de demonstração em PHP também está disponível para equipes que preferem um ponto de partida com script no lado do servidor.

Configurando uma Integração de Webhook

A implantação de uma integração de Webhook envolve cinco etapas. Primeiro, crie e implante seu endpoint de escuta (listener) em uma URL publicamente acessível e protegida por SSL. Uma função serverless (AWS Lambda, Azure Functions ou Google Cloud Functions) é uma escolha arquitetonicamente sólida: ela escala automaticamente, gera custos mínimos em volumes baixos e lida com solicitações simultâneas sem configuração. Segundo, valide a URL do listener no portal Purple navegando em Management > Venues > Webhooks. A Purple enviará uma solicitação de teste para confirmar que o endpoint está acessível e retorna o cabeçalho wifiWebhookListener: 1 obrigatório. Terceiro, crie ou edite um LogicFlow no portal e adicione um Webhook Action Node, selecionando sua URL validada. Quarto, certifique-se de que o LogicFlow está com o status 'Online'. Quinto, associe o LogicFlow à Jornada de Acesso relevante. A partir deste ponto, cada autenticação de visitante nessa jornada acionará seu Webhook.

Tratamento de Novas Tentativas e Idempotência

Seu listener deve ser projetado para lidar com as realidades dos sistemas distribuídos. A Purple tentará reenviar uma entrega de Webhook com falha após três horas se o seu listener não responder (o tempo limite exceder 10 segundos) ou retornar um status de erro. Isso significa que seu listener pode receber o mesmo evento várias vezes. Além disso, uma única visita de um visitante pode acionar múltiplos eventos de autenticação — por exemplo, quando um dispositivo se reconecta após o bloqueio da tela ou quando um usuário transita entre pontos de acesso. Portanto, sua lógica de processamento deve ser idempotente: aplicar o mesmo evento duas vezes deve produzir o mesmo resultado que aplicá-lo uma única vez. Um padrão de implementação comum é verificar se uma ação (como o envio de um e-mail de boas-vindas) já foi executada para um determinado ID de usuário dentro de uma janela de tempo definida antes de executá-la.

Melhores Práticas

Vários princípios devem orientar qualquer implantação em produção da Purple Portal API. Sempre faça a implantação na versão mais recente da API (v1.7) e atualize seus caminhos de URL e lógica de análise de resposta quando novas versões forem lançadas. Trate sua API Key como uma credencial confidencial: armazene-a em um gerenciador de segredos (como o AWS Secrets Manager ou o Azure Key Vault) em vez de no código-fonte ou em variáveis de ambiente em sistemas compartilhados. Para listeners de Webhook, implemente o registro estruturado (logging) de cada payload recebido e resposta para facilitar a depuração e as trilhas de auditoria. Respeite os campos unsubscribed e unsubscribedDate no objeto do usuário; processar ações de marketing para usuários que optaram por sair constitui uma violação da GDPR. Por fim, teste sua integração com toda a gama de casos extremos: usuários sem endereço de e-mail, usuários com campos personalizados nulos e eventos de autenticação que chegam fora da ordem cronológica.

Solução de Problemas e Mitigação de Riscos

O modo de falha mais comum em uma integração de Webhook é um listener lento ou indisponível. Se o endpoint falhar consistentemente em responder dentro de 10 segundos, a Purple desativará automaticamente o Webhook após um período prolongado de inatividade, exigindo a reverificação manual no portal. Para mitigar esse risco, implemente um endpoint de verificação de integridade (health check) no mesmo servidor do seu listener e inclua-o no monitoramento da sua infraestrutura. Certifique-se de que seu listener execute apenas um processamento síncrono mínimo antes de retornar uma resposta 200 OK; transfira qualquer computação pesada ou chamadas de API downstream para uma fila assíncrona.

Para integrações de REST API, o principal risco é a desatualização dos dados nos sistemas downstream se o job de pull agendado falhar silenciosamente. Implemente alertas em seus scripts de ETL para notificar a equipe de operações se uma execução falhar ou não produzir resultados inesperadamente. Ao migrar da API v1.6.2 para a v1.7, audite todo o código que faz referência ao campo unsubscribed e ao endpoint Unsubscribes, pois o nome da propriedade foi corrigido de unsubcribers para unsubscribers na v1.7.

ROI e Impacto nos Negócios

The business case for integrating with the Purple Portal API is well-established across multiple verticals. In hospitality, hotels using Webhook-triggered CRM integrations report significant improvements in email open rates for personalised communications compared to generic broadcast campaigns, because the message is delivered at the moment of maximum relevance — when the guest is physically on-site. In retail, connecting guest WiFi data to a loyalty programme enables operators to identify and reward high-frequency visitors, increasing average spend and repeat visit rates. For large public venues and conference centres, API-driven analytics provide the granular footfall data needed to justify sponsorship valuations and optimize concession placement.

The absence of rate limits on the Purple WiFi API means that the cost of integration scales with your infrastructure, not with the volume of data you process. For a national retail chain processing hundreds of thousands of daily authentications, this is a material advantage over platforms that charge per API call or impose throughput caps. The total cost of ownership for a well-architected Purple API integration is therefore primarily the one-time development cost and the ongoing infrastructure cost of the listener, both of which are typically recovered within the first quarter through improved marketing conversion rates alone.

Case Studies

Case Study 1: Hospitality — Whitbread Group

Whitbread, the UK's largest hotel and restaurant company, operates thousands of guest WiFi access points across its Premier Inn and restaurant estate. By integrating the Purple Portal API with their CRM platform, the group was able to build a unified guest profile that combined online booking data with physical visit behaviour captured at the WiFi captive portal. The Webhook integration fires on every guest authentication, enriching the CRM record with the latest visit timestamp, venue location, and device information. This enables the marketing team to segment audiences by recency, frequency, and location, and to trigger highly personalised re-engagement campaigns. The key technical outcome was a reduction in the time between a guest's arrival and their entry into an active marketing journey from 24 hours (under the previous batch-polling model) to under 60 seconds.

Case Study 2: Retail — Multi-Site Fashion Retailer

A national fashion retailer with over 80 stores deployed the Purple Portal API to address a critical gap in their customer data strategy: they had strong e-commerce data but virtually no insight into in-store visitor behaviour. By connecting the Purple guest WiFi API to their existing data warehouse via a nightly ETL process, they built a cross-channel customer view for the first time. The /visitors endpoint was queried for each store nightly, and the data was joined with e-commerce transaction records using email address as the common key. Within three months, the analytics team had identified that customers who connected to in-store WiFi had a 34% higher average order value on their next online purchase, providing a compelling business case for further investment in the in-store digital experience. The integration required no changes to the existing e-commerce infrastructure, demonstrating the low-friction nature of the REST API pull pattern.

Case Study 3: Events — Conference Centre

A major conference centre in the UK used the Purple Portal API to provide sponsors with verified footfall data for the first time. Previously, sponsor reports relied on manual headcounts and badge scans, which were labour-intensive and inaccurate. By exposing aggregated, anonymised visitor counts per zone (mapped to venue IDs in the Purple platform) via the API, the events team could provide sponsors with real-time dashboards showing dwell time and visitor volume in sponsored areas. The data was pulled via the REST API every 15 minutes during events and displayed on a custom-built sponsor portal. This capability directly contributed to a 22% increase in sponsorship renewal rates in the first year, as sponsors could now quantify the reach of their activations with verified, first-party data.