> ## Documentation Index
> Fetch the complete documentation index at: https://docs.senhalivre.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Controladora UniFi

> Configuração de redes e portal externo na UniFi Controller para integração com SenhaLivre.

## Sobre este Guia

Este guia explica como configurar a UniFi Controller para criar redes Wi-Fi e configurar o portal externo que redireciona visitantes para o SenhaLivre.

## Acesso à UniFi Controller

### Credenciais de Acesso

Acesse a interface web da UniFi Controller:

* **URL:** `https://<IP_OU_HOSTNAME_DA_CONTROLADORA>:8443`
* **Username:** (configurado durante a instalação)
* **Password:** (configurado durante a instalação)

<Info>
  A porta padrão da UniFi Controller é `8443` para HTTPS. Se você estiver usando Docker, o IP da controladora será o IP do host Docker. Se não souber o endereço, consulte a documentação da sua instalação ou verifique nas configurações de rede.
</Info>

## Criar Redes Wi-Fi

Você precisará criar pelo menos uma rede para o hotspot público que será usada pelos visitantes.

### 1. Rede Hotspot (pública)

Rede aberta que será usada pelos visitantes e conectada ao SenhaLivre.

**Configuração:**

1. Acesse **Settings → Wireless Networks** (ou **Configurações → Redes Sem Fio**)
2. Clique em **Create New Wireless Network** (ou **Criar Nova Rede Sem Fio**)
3. Configure:
   * **Name (SSID):** Nome da rede (ex.: "SenhaLivre")
   * **Enabled:** Ativado
   * **Security:** Open (sem senha)
   * **Network:** Selecione ou crie uma VLAN para o hotspot
   * **Guest Policy:** Habilitado (se disponível)

<Warning>
  **Importante:** A rede do hotspot deve estar configurada como **Open** (sem senha) para que o portal cativo funcione corretamente.
</Warning>

### 2. Rede Interna (opcional)

Rede privada para uso interno da equipe ou funcionários.

**Configuração:**

* **Name (SSID):** Nome da rede interna
* **Security:** WPA2/WPA3 com senha
* **Network:** VLAN separada da rede do hotspot

## Configurar Portal Externo

O portal externo é a funcionalidade que redireciona os visitantes para o SenhaLivre quando eles se conectam à rede Wi-Fi.

### Passo 1: Acessar Configurações de Portal

1. Acesse **Settings → Guest Control** (ou **Configurações → Controle de Convidados**)
2. Vá para a aba **Guest Portal** (ou **Portal de Convidados**)

### Passo 2: Configurar Portal Externo

1. Selecione **External Portal Server** (ou **Servidor de Portal Externo**)
2. Configure os seguintes campos:

**Configurações do Portal:**

* **Portal Type:** External Portal Server
* **Portal Server IP:** `<IP_PUBLICO_DO_SERVIDOR_SENHALIVRE>` (IP público do servidor onde o SenhaLivre está hospedado)
* **Portal Server Port:** `80` (ou `443` se usar HTTPS)
* **Portal Server Protocol:** HTTP (ou HTTPS)

<Warning>
  **Atenção:** O campo "Portal Server IP" aceita apenas endereços IPv4. Não é possível usar um domínio neste campo. Você precisará descobrir o IP público do servidor onde o SenhaLivre está hospedado. Para descobrir o IP, você pode:

  * Consultar o painel de controle do seu provedor de hospedagem
  * Usar ferramentas como `nslookup` ou `dig` para resolver o domínio do SenhaLivre
  * Verificar nas configurações do servidor web (Nginx/Apache)
</Warning>

### Passo 3: Aplicar Configurações

1. Clique em **Apply Changes** (ou **Aplicar Alterações**)
2. Aguarde a aplicação das configurações
3. Verifique se o portal está ativo

<Info>
  O UniFi Controller enviará os parâmetros necessários (MAC do cliente, MAC do AP, SSID, etc.) para o SenhaLivre através do portal externo. O sistema detecta automaticamente que é uma requisição UniFi e processa corretamente.
</Info>

## Configurar Hotspot na Rede

Após configurar o portal externo, você precisa aplicar essa configuração à rede Wi-Fi do hotspot:

1. Acesse **Settings → Wireless Networks**
2. Edite a rede do hotspot criada anteriormente
3. Em **Guest Control** ou **Controle de Convidados**, selecione:
   * **Enable Guest Portal:** Ativado
   * **Portal Type:** External Portal Server
4. Salve as alterações

## Adotar o AP na Controladora

Se o AP ainda não foi adotado, siga estes passos:

### Passo 1: Localizar o AP

1. Na UniFi Controller, acesse **Devices** (ou **Dispositivos**)
2. O AP deve aparecer como **Pending Adoption** (ou **Aguardando Adoção**)
3. Se não aparecer, verifique se o Inform URL foi configurado corretamente no AP

### Passo 2: Adotar o Equipamento

1. Selecione o AP na lista
2. Clique em **Adopt** (ou **Adotar**)
3. Se solicitado, informe as credenciais SSH do AP:
   * **Username:** `ubnt` (ou o configurado)
   * **Password:** (senha do AP)
4. Aguarde a adoção ser concluída

### Passo 3: Verificar Status

Após a adoção, o AP deve aparecer como **Connected** (ou **Conectado**) na controladora e estar pronto para uso.

## Testar o Portal

Após configurar tudo, teste o portal:

1. Conecte-se à rede Wi-Fi do hotspot (sem senha)
2. Abra um navegador e tente acessar qualquer site
3. Você deve ser redirecionado automaticamente para o portal do SenhaLivre
4. Complete o fluxo da campanha
5. Ao final, você deve ser autorizado e ter acesso à internet

<Note>
  Se o redirecionamento não funcionar, verifique:

  * Se o portal externo está configurado corretamente
  * Se o IP do servidor está correto
  * Se o firewall não está bloqueando as conexões
  * Se a rede Wi-Fi está configurada como "Open" (sem senha)
</Note>

## Parâmetros Enviados pelo UniFi

O UniFi Controller envia os seguintes parâmetros para o SenhaLivre:

* `ap` — MAC address do Access Point
* `id` — MAC address do dispositivo do cliente
* `ssid` — Nome da rede Wi-Fi
* `url` — URL original solicitada pelo cliente
* `t` — Timestamp Unix
* `site` — Nome do site na UniFi Controller

<Info>
  O SenhaLivre detecta automaticamente esses parâmetros e processa a requisição corretamente, identificando que é uma requisição do UniFi Controller.
</Info>

## Próximo Passo

Após configurar tudo na controladora, prossiga para:

* [Cadastro no SenhaLivre](/guia-instalacao/cadastro-senhalivre) — Adicionar o ponto de acesso ao sistema