Manual de integração — UniFi Cloud

Integração do CaptiveWeb com equipamentos UniFi gerenciados pelo UniFi Site Manager (UI.com — cloud). O CaptiveWeb autoriza os convidados via API Key do UI.com, sem precisar de acesso direto à rede local do controller. Ideal para múltiplos sites remotos gerenciados pela mesma conta UI.com.

Atenção: MFA obrigatório nas contas UI.com

Desde julho de 2024, a Ubiquiti exige MFA em todas as contas UI.com. Credenciais de conta cloud não funcionam para integrações automáticas — a API retorna erro api.err.Ubic2faTokenRequired. A solução correta é usar a API Key descrita abaixo, que não exige MFA.

1. Gerar API Key no UI.com

1. Acesse account.ui.com

   Faça login em account.ui.com com a conta proprietária do site UniFi.

2. Vá em My Account → API Keys

   No menu superior direito, clique no seu avatar e vá em My Account → API Keys.

3. Crie uma nova API Key

   Clique em Create API Key. Dê um nome descritivo (ex.: CaptiveWeb — Nome do Local) e confirme.

4. Copie a chave imediatamente

   A chave é exibida uma única vez. Copie-a agora e guarde em local seguro. Se perder, será necessário gerar uma nova e atualizar no painel CaptiveWeb.

2. Cadastrar no painel CaptiveWeb

1. Acesse Equipamentos → Nova controladora

   No painel CaptiveWeb, vá em Equipamentos → Nova controladora.

2. Selecione o tipo UniFi Cloud / UI.com

   Escolha o tipo UniFi Cloud / UI.com e cole a API Key gerada no passo anterior.

3. Selecione o site

   O painel consultará a API e listará todos os sites disponíveis na conta. Selecione o site correto onde estão os APs de convidados.

4. Salve e copie a Bridge URL

   Após salvar, copie a URL para External Portal Server. Formato: https://portal.captiveweb.com.br/public/portal-connect/unifi-redirect?key=SUA_CHAVE

3. Criar SSID de convidados no UI.com

1. Acesse o site no UI.com

   Em unifi.ui.com, selecione o site e entre no painel Network.

2. Crie a rede de convidados

   Em Settings → Networks → Create New, crie uma rede isolada (VLAN separada, ex.: 10.100.0.0/24, Client Isolation ON).

3. Crie o SSID aberto

   Em Settings → WiFi → Create New: nome do Wi-Fi (ex.: "WiFi Convidados"), senha em branco (rede aberta — obrigatório para o redirect funcionar), associe à rede de convidados, Client Isolation ON.

4. Ative o Hotspot Portal no SSID

   Na configuração do SSID, role até Hotspot e ative o toggle "Hotspot Portal".

4. Configurar External Portal Server no UI.com

1. Acesse Insights → Hotspot → Landing Page

   No painel Network do site, clique em Insights no menu lateral e depois em Hotspot → Landing Page.

2. Selecione External Portal Server

   Na aba Authentication, em Type, selecione External Portal Server. Em Template, selecione Custom.

3. Configure o endereço do portal

   Em IPv4 Address, informe o IP do servidor CaptiveWeb. Em Redirect Hostname, informe portal.captiveweb.com.br. Ative Use Secure Portal.

4. Configure a expiração padrão

   Na aba Settings, ajuste Default Expiration conforme o plano (ex.: 480 minutos). Clique em Apply Changes.

5. Walled Garden — Pre-Authorization

Em Insights → Hotspot → Landing Page → aba Pre-Authorization, clique em "Add Hostname, IP or Subnet" e adicione:

portal.captiveweb.com.br
*.captiveweb.com.br
fonts.googleapis.com
fonts.gstatic.com
*.mercadopago.com
*.mercadolibre.com
*.asaas.com

Modelos compatíveis