Purple Portal API: O Que Você Pode Fazer Com Ela

Resumo Executivo

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

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, endpoints disponíveis, padrões de integração e 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 fundamentação técnica e as estruturas de decisão necessárias para prosseguir com confiança.

Detalhamento 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 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 da requisição. 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 é fundamental para a conformidade com a GDPR e para a segmentação precisa de público. Além disso, os endpoints 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 de acesso e quaisquer campos personalizados configurados na splash page.

Limites de Requisição

Uma vantagem arquitetônica fundamental da Purple Portal API é que não há limites de requisição. A plataforma é projetada para suportar qualquer volume de solicitações ou transações, tornando-a ideal para implantações em grande escala onde os scripts podem precisar processar milhares de registros de locais de acesso 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 controle de taxa de solicitação ou lógica de back-off em seu código 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 REST API pull envolve o seu sistema fazendo solicitaçõ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 Webhook push 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 acessível publicamente e protegido por SSL (um 'ouvinte') 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 quase real, como acionar uma mensagem de boas-vindas personalizada, atualizar o status de 'última visita' de um cliente em um CRM ou notificar um gerente de hotelaria que um visitante VIP chegou.

Estrutura de 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 é altamente valioso para operadores de múltiplos locais. Ele fornece uma contagem de visitas por local junto com os timestamps firstVisit e lastVisit, permitindo que você identifique visitantes de primeira viagem versus clientes recorrentes e leais no momento exato da autenticação - sem a necessidade de chamadas adicionais de API.

Guia de Implementação

Pré-requisitos e Configuração

O acesso à Portal API exige uma licença Engage. Uma vez licenciado, gere sua Chave de API diretamente 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 requisição corretos. Um arquivo de demonstração em PHP também está disponível para equipes que preferem um ponto de partida baseado em 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 receptor em uma URL acessível publicamente e protegida por SSL. Uma função serverless (AWS Lambda, Azure Functions ou Google Cloud Functions) é uma excelente escolha de arquitetura: ela escala automaticamente, gera custos mínimos em volumes baixos e lida com requisições simultâneas sem necessidade de configuração adicional. Segundo, valide a URL receptora no portal Purple acessando Gerenciamento > Locais > Webhooks. A Purple enviará uma requisição de teste para confirmar que o endpoint está acessível e retorna o cabeçalho obrigatório wifiWebhookListener: 1. Terceiro, crie ou edite um LogicFlow no portal e adicione um Nó de Ação de Webhook, selecionando sua URL validada. Quarto, certifique-se de que o LogicFlow esteja com o status 'Online'. Quinto, vincule o LogicFlow à Jornada de Acesso relevante. A partir deste momento, cada autenticação de visitante nessa jornada acionará seu Webhook.

Tratamento de Novas Tentativas e Idempotência

Seu receptor deve ser projetado para lidar com as realidades dos sistemas distribuídos. A Purple tentará reenviar uma entrega de Webhook que falhou após três horas caso seu receptor não responda (tempo limite superior a 10 segundos) ou retorne um status de erro. Isso significa que seu receptor pode receber o mesmo evento múltiplas vezes. Além disso, uma única visita de visitante pode acionar vários 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 apenas uma 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 realizada para um determinado ID de usuário dentro de um intervalo de tempo definido antes de executá-la novamente.

Melhores Práticas

Vários princípios devem guiar qualquer implantação em produção da Purple Portal API. Sempre faça a implantação em relação à 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 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 contra usuários que optaram por sair constitui uma violação do GDPR. Por fim, teste sua integração contra toda a gama de casos de teste 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, o Purple desativará automaticamente o Webhook após um período prolongado de inatividade, exigindo reverificação manual no portal. Para mitigar esse risco, implemente um endpoint de verificação de integridade (health check) no mesmo servidor que seu listener e inclua-o no monitoramento de sua infraestrutura. Certifique-se de que seu listener realize apenas um processamento síncrono mínimo antes de retornar uma resposta 200 OK; descarregue 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 de dados em sistemas downstream se a tarefa de extração agendada falhar silenciosamente. Implemente alertas em seus scripts 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

O caso de negócios para a integração com a Purple Portal API está bem consolidado em vários setores. Na hotelaria, hotéis que utilizam integrações de CRM acionadas por Webhook relatam melhorias significativas nas taxas de abertura de e-mails para comunicações personalizadas em comparação com campanhas genéricas de transmissão, porque a mensagem é entregue no momento de máxima relevância - quando o hóspede está fisicamente no local. No varejo, conectar os dados de WiFi de visitantes a um programa de fidelidade permite que os operadores identifiquem e recompensem visitantes de alta frequência, aumentando o gasto médio e as taxas de visitas recorrentes. Para grandes locais públicos e centros de conferências, as análises orientadas por API fornecem os dados detalhados de fluxo de pessoas necessários para justificar avaliações de patrocínio e otimizar a distribuição de concessões.

A ausência de limites de taxa na Purple WiFi API significa que o custo de integração escala com a sua infraestrutura, não com o volume de dados que você processa. Para uma rede de varejo nacional que processa centenas de milhares de autenticações diárias, esta é uma vantagem material em relação a plataformas que cobram por chamada de API ou impõem limites de processamento. O custo total de propriedade para uma integração bem projetada da Purple API é, portanto, principalmente o custo de desenvolvimento único e o custo de infraestrutura contínuo do listener, ambos os quais são normalmente recuperados logo no primeiro trimestre apenas através de melhores taxas de conversão de marketing.

Estudos de Caso

Estudo de Caso 1: Hotelaria - Whitbread Group

A Whitbread, a maior empresa de hotéis e restaurantes do Reino Unido, opera milhares de pontos de acesso WiFi de visitantes em suas propriedades Premier Inn e restaurantes. Ao integrar a Purple Portal API com sua plataforma de CRM, o grupo conseguiu criar um perfil unificado de visitante que combinava dados de reserva online com o comportamento de visita física capturado no Captive Portal de WiFi. A integração de Webhook é acionada a cada autenticação de visitante, enriquecendo o registro do CRM com o carimbo de data/hora da visita mais recente, localização do local e informações do dispositivo. Isso permite que a equipe de marketing segmente públicos por recência, frequência e localização, e acione campanhas de engajamento altamente personalizadas. O principal resultado técnico foi uma redução no tempo entre a chegada do visitante e sua entrada em uma jornada de marketing ativa de 24 horas (no modelo anterior de polling em lote) para menos de 60 segundos.

Estudo de Caso 2: Varejo - Varejista de Moda Multilojas

Um varejista de moda nacional com mais de 80 lojas implantou a API do Purple Portal para resolver uma lacuna crítica em sua estratégia de dados de clientes: eles tinham dados robustos de e-commerce, mas praticamente nenhuma visão sobre o comportamento dos visitantes nas lojas físicas. Ao conectar a API de WiFi para convidados da Purple ao seu data warehouse existente por meio de um processo ETL diário, eles construíram uma visão multicanal do cliente pela primeira vez. O endpoint /visitors era consultado para cada loja todas as noites, e os dados eram combinados com os registros de transações de e-commerce usando o endereço de e-mail como chave comum. Em três meses, a equipe de analytics identificou que os clientes que se conectavam ao WiFi da loja tinham um valor médio de pedido 34% maior em sua próxima compra online, fornecendo um caso de negócios convincente para mais investimentos na experiência digital em loja. A integração não exigiu alterações na infraestrutura de e-commerce existente, demonstrando a natureza de baixo atrito do padrão de pull da API REST.

Caso de Estudo 3: Eventos - Centro de Convenções

Um grande centro de convenções no Reino Unido usou a API do Purple Portal para fornecer aos patrocinadores dados de fluxo de pessoas verificados pela primeira vez. Anteriormente, os relatórios de patrocinadores dependiam de contagens manuais e leituras de crachás, que eram trabalhosas e imprecisas. Ao expor contagens de visitantes agregadas e anonimizadas por zona (mapeadas para IDs de locais na plataforma Purple) por meio da API, a equipe de eventos pôde fornecer aos patrocinadores dashboards em tempo real mostrando o tempo de permanência e o volume de visitantes nas áreas patrocinadas. Os dados eram extraídos via API REST a cada 15 minutos durante os eventos e exibidos em um portal de patrocinadores personalizado. Essa capacidade contribuiu diretamente para um aumento de 22% nas taxas de renovação de patrocínio no primeiro ano, já que os patrocinadores agora podiam quantificar o alcance de suas ativações com dados proprietários verificados.