← Documentación

Manual 03 · UniFi (Ubiquiti)

UniFi es el conector más cómodo para una instalación en la nube: el controlador ya sabe aplicar minutos y ancho de banda por invitado, así que IPSmart Z sólo tiene que decirle a quién y cuánto. No hace falta ningún servidor nuestro en el sitio.

Probado en: UniFi Network 7.5 – 9.x, sobre controlador de software, Cloud Key Gen2 y UDM‑Pro.

0. Qué sabor de controlador tienes

Esto decide la mitad de la configuración, y confundirlo es el error clásico:

Sabor Equipos Cómo entra IPSmart Z
UniFi OS UDM, UDM‑Pro, UDM‑SE, Cloud Key Gen2, Dream Router Login en /api/auth/login, todo lo demás bajo /proxy/network/…, exige cabecera CSRF
Clásico Controlador de software en Linux/Windows/Docker, Cloud Key Gen1 Login en /api/login, rutas directas /api/s/<sitio>/…

No tienes que elegir: el conector prueba primero el moderno y cae al clásico solo. Pero si algo falla, saber cuál tienes ahorra una hora.

1. Usuario local para IPSmart Z

⚠️ La cuenta de Ubiquiti (la del correo, la de la nube) no sirve. La API rechaza cuentas con verificación en dos pasos y cuentas de nube. Hay que crear un administrador local.

  1. Settings → Admins & Users → Add New Admin
  2. Marca Restrict to local access only (administrador local).
  3. Usuario: zonaw · una clave larga y propia.
  4. Rol: Site Admin del sitio de esa zona. (Con «Viewer» no puede autorizar invitados; hace falta escritura.)
  5. No actives verificación en dos pasos para este usuario.

El nombre interno del sitio no es el que se ve. Mira la URL cuando estás dentro:

https://controlador:8443/manage/site/ab12cd34/dashboard
                                    ^^^^^^^^
                                    este es el `sitio`

El sitio por defecto se llama default. Uno creado después tendrá un identificador de 8 caracteres. Ese es el valor que va en la configuración del equipo.

2. Red de invitados

Settings → Networks → Create New Network

Campo Valor
Name Zona WiFi
Router / VLAN VLAN propia (ej. 60) — ver Manual 06
Gateway/Subnet 10.60.0.1/22
DHCP Servidor propio, concesión 45 minutos
Network Type Guest ← imprescindible: sin esto no hay portal

Y el SSID: Settings → WiFi → Create New

Campo Valor
Name El nombre que verá la gente
Security Open
Network Zona WiFi
Guest Policy / Hotspot Activado
Band Both (2.4 + 5)
Minimum data rate 12 Mbps en 2,4 · 12 Mbps en 5 (ver Manual 01)
Client Device Isolation Activado

3. Portal externo

Settings → Hotspot / Guest Hotspot → Portal Customization

  1. Enable Guest Portal: activado.
  2. Authentication: External Portal Server.
  3. External Portal Server: zonaw.ipsmart.app
  4. Redirect using hostname: activado, con zonaw.ipsmart.app.
  5. HTTPS redirection: activado.

UniFi redirige al visitante así:

https://zonaw.ipsmart.app/p/plaza-bolivar?id=<mac-del-cliente>&ap=<mac-del-ap>&t=<marca-de-tiempo>&url=<destino-original>&ssid=<nombre-de-la-red>

IPSmart Z entiende id como la MAC del cliente. No hace falta configurar la ruta con el slug si usas un solo portal por sitio, pero es lo recomendado: pon la URL completa con el slug de la zona, así un controlador puede servir varias zonas.

Permisos previos a la autenticación

Settings → Hotspot → Pre-Authorization Access (en versiones nuevas: Allowed Access Before Authorization).

Añade:

zonaw.ipsmart.app
*.ipsmart.app

Sin esto, el visitante no puede cargar el portal: está bloqueado y el portal está fuera de la red. Es exactamente el mismo concepto que el jardín vallado de MikroTik.

No añadas los dominios de detección de red cautiva (captive.apple.com, connectivitycheck.gstatic.com): si los dejas pasar, el teléfono cree que hay internet y no muestra el aviso.

4. Registrar el equipo en IPSmart Z

{
  "nombre": "UniFi Centro Comercial",
  "tipo": "unifi",
  "host": "controlador.tudominio.net",
  "config": {
    "puerto": 443,
    "usuario": "zonaw",
    "secreto": "<se cifra al guardar>",
    "sitio": "default",
    "inseguro": true
  }
}
  • puerto: 443 en UDM/Cloud Key Gen2; 8443 en controlador de software clásico.
  • sitio: el identificador interno de la sección 1.
  • inseguro: true porque el controlador trae certificado autofirmado.

Prueba antes de abrir la zona:

npm run z:probar-conector -- "UniFi Centro Comercial"

Esperado:

✅  Controlador UniFi OS accesible · sitio default
    latencia: 61 ms

5. Qué hace IPSmart Z cuando alguien se registra

POST /proxy/network/api/s/<sitio>/cmd/stamgr
{ "cmd": "authorize-guest", "mac": "aa:bb:cc:dd:ee:ff", "minutes": 30, "up": 1024, "down": 4096 }
  • minutes: 30 para visitante, 120 para cliente (configurable por zona).
  • up / down: en kbps, no en Mbps. 4096 son 4 Mbps.
  • Al vencer, el controlador corta solo. El vigía de IPSmart Z además manda unauthorize-guest para que no queden sesiones fantasma.

Puedes ver a los autorizados en Insights → Guests o en Clients filtrando por la red de invitados.

6. Cuando algo no funciona

Síntoma Causa Arreglo
api.err.Invalid / LoginRequired al probar Cuenta de nube o con 2FA Sección 1: hace falta administrador local
api.err.NoSiteContext El sitio es el nombre visible, no el interno Sección 1, mira la URL
El portal no carga en el teléfono Falta el permiso previo a la autenticación Sección 3
Autoriza pero sigue sin navegar El SSID no está marcado como Guest, o la red no es Guest Network Sección 2
Funciona en 5 GHz y no en 2,4 Velocidad mínima mal puesta, o el AP en canal saturado Manual 01
Deja de autorizar de golpe Cambió la IP de salida o la clave del usuario zonaw Sección 1 y 4

7. Lista de comprobación

  • Administrador local zonaw creado, sin 2FA, con permiso de escritura en el sitio.
  • Identificador interno del sitio anotado (el de la URL).
  • Red marcada como Guest Network con VLAN propia.
  • SSID abierto, con Guest Policy activada y aislamiento de clientes.
  • External Portal Server apuntando a zonaw.ipsmart.app.
  • Permisos previos a la autenticación con zonaw.ipsmart.app y *.ipsmart.app.
  • Equipo registrado en IPSmart Z y z:probar-conector en verde.
  • Prueba con Android y con iPhone: sale el aviso solo, se navega, se corta a tiempo.