Panel ISP — Manual de uso

El sistema incluye una página de presentación pública accesible en /presentacion. Esta página usa el diseño Hyperspace con la paleta de colores de Ixtanet y sirve como punto de entrada para visitantes que aún no tienen sesión iniciada.

Comportamiento

• Cualquier visitante que intenta acceder al panel sin sesión activa es redirigido automáticamente a /presentacion.
• Si el usuario ya tiene sesión iniciada, la página muestra el botón "Ir al panel" en lugar de "Iniciar sesión".
• La página es accesible por cualquier persona en la red — no requiere login.

Secciones de la landing page

El panel es accesible desde cualquier navegador en la red local (o desde internet si se configura el router).

La pestaña Clientes unifica el directorio, el estado de deuda y el monitoreo en tiempo real en una sola vista. Cada tarjeta de cliente muestra su estado online/offline, si está al día o en mora, y tiene acceso directo a todas las acciones.

Chips de filtro

Cuatro chips en la parte superior filtran la vista al instante:

Tarjeta de cliente

Cada cliente se muestra como una tarjeta con:

• Punto de estado ● verde (en línea) / ● rojo (offline o suspendido)
• Badges: Suspendido, N fact · Q X o Al día
• Meta: plan, IP, velocidad y dirección
• Facturas detalladas con botón cobrar individual (solo si tiene mora)
• Acciones: WhatsApp, Editar, Cobrar total, Cortar / Reactivar

Búsqueda

El campo de búsqueda en la barra superior filtra las tarjetas visibles por texto (nombre, IP, dirección).

Campos del cliente

Importar desde CSV

Usa el botón Importar CSV para cargar tu directorio existente. El archivo debe tener columnas: nombre, ip, telefono, direccion, monto_mensual, velocidad_mbps.

Cuando conectas un cliente nuevo, sigue estos pasos en el panel:

Facturación masiva automática

El sistema genera facturas automáticamente el día configurado en Ajustes → Facturación. No requiere intervención.

Facturación masiva manual

En la pestaña Facturas, el botón "Facturar todos" genera facturas pendientes para todos los clientes con monto > 0. Es idempotente: si ya existe la factura del mes actual, no crea una duplicada.

Facturación por tipo de zona (Prepago / Postpago)

El concepto de cada factura generada automáticamente depende del tipo de cobro configurado en la zona del cliente:

Los clientes sin zona asignada son tratados como postpago.

Factura individual

En la pestaña Facturas → Emitir Factura Individual, selecciona el cliente y genera la factura si lo necesitas fuera del ciclo normal.

El registro de pagos se hace desde la pestaña Clientes o desde Facturas.

Cobrar una factura

Liquidar toda la deuda

En la tarjeta del cliente (tab Clientes), el botón Total cobra todas las facturas pendientes del cliente de una sola vez.

Historial de pagos

La pestaña Pagos muestra todos los cobros registrados con fecha, monto y método. Cada pago tiene tres acciones rápidas:

Permite registrar el pago de uno o varios meses futuros de un cliente. Las facturas se crean directamente con estado Pagada y la facturación automática las saltará cuando llegue su fecha.

Cómo registrar un pago adelantado

¿Desde qué mes empieza?

El sistema toma como punto de partida la última factura registrada del cliente y genera los meses siguientes. Ejemplo:

Efecto en la facturación automática

Cuando el scheduler genera la facturación mensual, verifica si ya existe una factura del mes para ese cliente. Como las facturas adelantadas ya existen (aunque sean Pagadas, el concepto del mes coincide), no se duplican.

Cuando esta opción está activa, el sistema verifica que el teléfono y la dirección del cliente estén actualizados antes de registrar cualquier cobro. Si los datos tienen más días de antigüedad que el período configurado, aparece un modal pidiendo confirmar o corregir la información.

Configurar el período

¿Cómo funciona al cobrar?

Al hacer clic en cualquier botón de cobro (factura individual, cobrar total o desde la pestaña Facturas), el panel consulta /api/check_actualizacion/<nombre> antes de enviar el formulario:

Modal de actualización

El modal muestra el nombre del cliente (no editable), el teléfono actual y la dirección actual, listos para confirmar o corregir. Al hacer clic en "Guardar y Cobrar":

1. Se guardan los datos actualizados del cliente (POST /api/actualizar_datos_cliente)
2. Se actualiza ultima_actualizacion en la base de datos
3. Se envía el formulario de cobro original automáticamente

¿Cuándo se reinicia el contador?

La fecha de ultima_actualizacion se actualiza en dos momentos:

• Al guardar el formulario del cliente (editar desde el acordeón)
• Al confirmar el modal de actualización antes de cobrar

Corte automático

El sistema evalúa el estado del cliente cada vez que se crea o cobra una factura. Si las facturas pendientes superan el límite configurado (por defecto 3), el cliente es suspendido automáticamente en MikroTik.

Corte manual

En la pestaña Clientes, cada tarjeta tiene el botón Cortar para suspender manualmente sin importar la deuda. También hay un formulario rápido con el botón Suspender manual en la barra de herramientas.

Reactivación

Al cobrar suficientes facturas para bajar la deuda por debajo del límite, el sistema reactiva automáticamente al cliente. También puedes reactivar manualmente con el botón Reactivar en la tarjeta del cliente (tab Clientes).

Corte masivo

El día de corte configurado en Ajustes, el job automático de las 6 AM evalúa a todos los clientes y aplica suspensiones masivas según su deuda acumulada.

El monitoreo de conectividad está integrado directamente en el tab Clientes. No hay pestaña Monitor separada.

Panel de caídas

Al detectar una antena caída, aparece el panel de alertas en la parte superior del tab Clientes, con nombre del cliente y hora exacta de cada caída.

Actualizaciones

El estado se refresca cada 3 segundos en el frontend (vía /api/estado) y el backend verifica cambios cada 1 minuto para generar notificaciones persistentes.

Notificación WA por caída de servicio

Cuando el sistema confirma que un cliente ha perdido conexión (tras 2 ciclos consecutivos offline), puede enviarle automáticamente un mensaje personalizado por WhatsApp informándole del corte — ideal para avisar que si hay apagón eléctrico el servicio volverá solo cuando regrese la luz.

Actívalo en Ajustes → Automatización → Notificar al cliente cuando pierde conexión (WA). Personaliza el mensaje con los comodines {cliente} e {ip}.

Anti-spam: caída de sitio completo

Si en un mismo ciclo caen ≥ N clientes simultáneamente (umbral configurable, por defecto 3), el sistema interpreta que es un corte eléctrico por zona y omite los WA individuales. En su lugar genera una única alerta interna: "Caída masiva: N clientes sin internet — posible corte eléctrico por zona". Esto evita spam masivo cuando se va la luz en una colonia entera.

El panel tiene un sistema de notificaciones persistentes. La campana 🔔 en la barra superior muestra las alertas no leídas.

Tipos de notificaciones

Historial

Haz clic en la campana para abrir el panel de historial con las últimas 50 notificaciones. Las notificaciones se marcan como leídas al recuperarlas.

La pestaña Inicio muestra métricas en vivo del sistema.

El panel se conecta al router MikroTik vía API RouterOS (puerto 8728 por defecto). Soporta RouterOS 6 y 7.

Configurar la conexión

Cuando un cliente está suspendido, cualquier página web que intente visitar (HTTP) es redirigida automáticamente a una página de aviso personalizada que muestra sus facturas pendientes, datos de contacto y métodos de pago — igual al sistema de WispHub.

Cómo funciona

El sistema usa el Web Proxy de MikroTik (RouterOS), que intercepta el tráfico HTTP y envía al cliente un redirect HTTP 302 a la URL del portal con su nombre incluido:

Lo que ocurre al suspender un cliente:

1. La IP del cliente se agrega a clientes_suspendidos (address-list del firewall).
2. El panel habilita el Web Proxy en MikroTik (/ip/web-proxy enabled=yes) si no estaba activo.
3. Se crea (si no existe) la regla NAT que redirige el tráfico HTTP de clientes suspendidos al proxy.
4. Se agrega una regla en /ip/web-proxy/access para esa IP específica con action=redirect a la URL del portal.

Al reactivar, la regla del web proxy se elimina automáticamente.

Configurar en Ajustes

Lo que ve el cliente

• Nombre de la empresa y del cliente
• Mensaje: “Tu servicio ha sido suspendido por falta de pago”
• Tabla con sus facturas pendientes (concepto, monto, fecha)
• Botones de Llamar y WhatsApp
• Bloque personalizable: dirección, horario, email, métodos de pago

El botón "Exportar MikroTik" en la pestaña Clientes sincroniza todos los clientes al router como Simple Queues. Si tienes varias Zonas configuradas, la exportación agrupa los clientes por zona y sincroniza cada router por separado — todo en un solo clic.

Úsalo cuando:

• El router fue reseteado y perdió la configuración
• Quieres aplicar cambios de velocidad masivos
• Acabas de migrar de otro sistema

Clientes sin plan asignado

Si algún cliente tiene velocidad_mbps = 0, el sistema muestra un modal para asignar plan antes de exportar.

Clientes sin cola en el router

Si un cliente existe en la DB pero no tiene cola en MikroTik (nunca fue instalado), aparece en la lista "Sin cola". Debes crear la cola manualmente o registrar la instalación del cliente con una IP válida.

Colas dinámicas

MikroTik genera colas dinámicas para conexiones DHCP y PPPoE (nombres como <pppoe-oficina> o dhcp-ds<MAC>). Estas colas no se pueden editar. El panel las detecta y las salta automáticamente durante la exportación — no generan error.

El sistema de zonas permite gestionar múltiples routers MikroTik simultáneamente. Cada zona representa un nodo de red — por ejemplo, cada enlace Starlink con su propio MikroTik. Cada cliente se asigna a una zona y todas las operaciones (colas, cortes, reactivaciones, exportaciones) se ejecutan automáticamente en el router de esa zona.

Crear una zona

Comportamiento por operación

Badge de zona en el directorio

Cada tarjeta de cliente muestra el nombre de su zona bajo el nombre del cliente con el ícono de antena cell_tower. Si la zona es prepago, también se muestra el badge PREPAGO. Esto permite identificar a qué nodo y modelo de cobro pertenece cada cliente de un vistazo.

Tipo de cobro: Prepago vs Postpago

Cada zona puede configurarse como postpago (predeterminado) o prepago. Esto cambia el comportamiento de la facturación automática y el umbral de corte para todos los clientes de esa zona.

Configurar el tipo de cobro de una zona

Gestión de zonas

Monitoreo de switches MikroTik con puertos POE. El link Powerbox POE solo aparece en el menú si tienes al menos un switch registrado.

Agregar un switch POE

Ve a Ajustes → Powerbox POE y registra el switch con su nombre y datos de conexión al router. Desde ese momento el panel tomará lecturas cada 5 minutos.

Información por puerto

Historial gráfico

Selecciona el período: diario, semanal, mensual o trimestral. Los datos se muestrean cada 5 minutos.

Si tienes routers MikroTik en ubicaciones remotas que se conectan a internet vía Starlink, no tienen IP pública fija (CGNAT). El panel no puede alcanzarlos directamente. La solución es crear una VPN WireGuard donde el servidor del panel actúa de hub y cada MikroTik se conecta como cliente.

Arquitectura

Paso 1 — Instalar WireGuard en el servidor Linux

apt install wireguard -y
cd /etc/wireguard

# Llave del servidor
wg genkey | tee server_priv | wg pubkey > server_pub

# Una llave por cada MikroTik
wg genkey | tee mt1_priv | wg pubkey > mt1_pub
wg genkey | tee mt2_priv | wg pubkey > mt2_pub

[Interface]
Address = 10.200.0.1/24
ListenPort = 51820
PrivateKey = <contenido de server_priv>

# MikroTik 1
[Peer]
PublicKey = <contenido de mt1_pub>
AllowedIPs = 10.200.0.2/32

# MikroTik 2
[Peer]
PublicKey = <contenido de mt2_pub>
AllowedIPs = 10.200.0.3/32

systemctl enable --now wg-quick@wg0
ufw allow 51820/udp

Paso 2 — Configurar WireGuard en cada MikroTik (RouterOS 7)

Ejecuta esto en la terminal de cada MikroTik (Winbox → Terminal o SSH). Reemplaza los valores entre < >:

# ── MikroTik 1 (repite en MikroTik 2 cambiando la IP a 10.200.0.3) ──

/interface/wireguard/add \
    name=wg-panel \
    listen-port=13231 \
    private-key="<contenido de mt1_priv>"

/interface/wireguard/peers/add \
    interface=wg-panel \
    public-key="<contenido de server_pub>" \
    endpoint-address=<IP_PUBLICA_SERVIDOR> \
    endpoint-port=51820 \
    allowed-address=10.200.0.0/24 \
    persistent-keepalive=25

/ip/address/add address=10.200.0.2/24 interface=wg-panel

Paso 3 — Habilitar API en cada MikroTik

El panel se conecta a los routers vía la API RouterOS (puerto 8728). Asegúrate de que la API esté habilitada y acepte conexiones desde la VPN:

/ip/service/set api disabled=no
# Opcional: restringir a solo la IP del servidor VPN
/ip/service/set api address=10.200.0.1/32

Paso 4 — Apuntar el panel al router remoto

Una vez activo el túnel, el router responde en su IP WireGuard. Para operarlo desde el panel:

1. Ve a Ajustes → MikroTik
2. Cambia el Host a la IP WireGuard del router deseado (ej. 10.200.0.2)
3. Ingresa usuario y contraseña del router remoto
4. Guarda — el panel apuntará a ese router

¿Por qué persistent-keepalive?

Starlink usa CGNAT, lo que significa que el NAT cierra sesiones UDP inactivas. El parámetro persistent-keepalive=25 hace que el MikroTik envíe un paquete al servidor cada 25 segundos, manteniendo el túnel siempre abierto aunque no haya tráfico real de clientes.

Los planes se administran en Ajustes → Planes de Servicio. Cada plan tiene:

• Nombre: identificador del plan (ej. "Básico 10 Mbps")
• Velocidad (Mbps): se aplica como max-limit en la cola MikroTik
• Monto mensual: cuota que se cobra al cliente

Al seleccionar un plan en el formulario de cliente, se rellenan automáticamente velocidad y monto.

El panel puede enviar mensajes a través de cualquier API de WhatsApp (CallMeBot, UltraMsg, Twilio, etc.).

Configuración

En Ajustes → WhatsApp:

Cuándo se envían mensajes

• Al cobrar una factura → mensaje de recibo de pago
• Último día del mes → recordatorio de pago a clientes con deuda
• Manual desde el historial de pagos → recibo en PDF (requiere URL de documentos)
• Al detectar caída de conexión → aviso personalizado al cliente (si activado y no es caída masiva por zona)

Envío de recibo PDF

El botón PDF en cada fila de la pestaña Pagos genera el recibo en PDF y lo envía vía API. Para usarlo, configura:

Los headers y el método se heredan de la configuración principal de WhatsApp.

Si WhatsApp falla

Los errores de envío no bloquean el cobro. El pago se registra igualmente y el detalle completo del error de la API aparece en la campana de notificaciones con el título "Fallo WA — [nombre del cliente]".

Recordatorios masivos — prevenir bloqueo de cuenta

WhatsApp detecta como spam cuando se envían muchos mensajes seguidos en segundos. Para evitar que tu número sea bloqueado, el sistema agrega automáticamente una pausa aleatoria de 8 a 18 segundos entre cada recordatorio masivo del fin de mes. Esto imita el comportamiento humano y reduce la probabilidad de bloqueo.

El sistema puede enviar una copia de la base de datos por correo electrónico de forma automática.

Configura el servidor SMTP en Ajustes → SMTP con host, puerto, usuario y contraseña. Selecciona la frecuencia (diaria, cada 3 días, semanal).

El panel ejecuta 4 tareas automáticas en segundo plano:

¿Qué pasa si el MikroTik se apaga?

El panel sigue funcionando. Los datos de clientes, facturas y pagos están en la base de datos local (SQLite). Al volver el router, usa Exportar MikroTik para resincronizar las colas.

¿Puedo tener varios routers MikroTik?

Sí. El panel soporta múltiples routers simultáneamente mediante el sistema de Zonas. Crea una zona por router en Ajustes → Zonas / Nodos Starlink, ingresa las credenciales de cada MikroTik y asigna los clientes a su zona correspondiente. Si los routers están detrás de Starlink (CGNAT), conéctalos al servidor con WireGuard VPN y usa la IP del túnel como host de la zona. Consulta la sección Zonas / Nodos Starlink y MikroTik remoto (WireGuard) del manual.

¿Cómo actualizo el panel?

cd ~/panel-isp-ixtanet
bash start.sh

El script de inicio hace git pull automáticamente y reinicia la aplicación.

¿Dónde está la base de datos?

Archivo pagos.db en la carpeta del proyecto. Es un SQLite estándar — puedes abrirlo con cualquier cliente SQLite (DB Browser, TablePlus, etc.).

¿Por qué me llegó la misma notificación varias veces?

Ocurre si el servidor fue iniciado más de una vez sin detener el proceso anterior, generando múltiples schedulers. Solucionado con bash start.sh que mata procesos previos antes de arrancar.

Un cliente está en línea pero aparece como offline

El estado se basa en la tabla ARP del MikroTik. Si el cliente no está en ARP (por ejemplo, su equipo está inactivo), aparecerá offline. Revisa en el router: IP → ARP.

¿Puedo acceder desde el celular?

Sí. La interfaz es responsive y funciona bien en dispositivos móviles. Las tarjetas de clientes, facturas y pagos se adaptan a pantallas pequeñas. Asegúrate de acceder desde la red local o configurar acceso remoto en tu router.

¿Cómo importo clientes desde WispHub?

Descarga el backup desde WispHub (CSV de clientes + historial de pagos). Copia los archivos a la carpeta del proyecto y ejecuta en la terminal:

python _importar_wisphub.py

El script importa clientes, facturas y pagos; y agrega columnas extra a la tabla clientes: ip, cedula, fecha_instalacion, id_wisphub, zona. Edita la ruta del backup dentro del script antes de ejecutarlo.

La deuda pendiente muestra un monto muy alto

Si importaste historial desde otro sistema, la DB contiene facturas pendientes de años anteriores. El dashboard filtra la deuda al año actual para mostrar solo lo relevante. El historial completo sigue disponible en la pestaña Facturas.