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).

Cada inicio de sesión queda registrado para reconocer accesos normales y cerrar los sospechosos. Todos los perfiles pueden abrir Mis dispositivos desde la cabecera del panel y ver exclusivamente las sesiones de su propia cuenta. El administrador también dispone de la auditoría completa en Ajustes → Usuarios → Sesiones y dispositivos.

Cada usuario puede cerrar una sesión propia concreta o elegir Cerrar mis otras sesiones para conservar únicamente el dispositivo que está usando. No puede consultar ni cerrar dispositivos de otras cuentas. El administrador sí puede auditar todas las cuentas. Cambiar, recuperar o eliminar una contraseña invalida las sesiones anteriores de esa cuenta.

Cambiar la contraseña propia

Los usuarios técnicos y de finanzas pueden actualizar su contraseña sin solicitar ayuda al administrador:

1. Inicia sesión y, en la cabecera del panel, selecciona Cambiar contraseña.
2. Escribe tu Contraseña actual.
3. Escribe una Nueva contraseña de al menos 6 caracteres y repítela en Confirmar nueva contraseña.
4. Presiona Guardar. El dispositivo actual seguirá abierto y las demás sesiones de tu cuenta se cerrarán.

El administrador debe cambiarla desde Ajustes → Usuarios, editando su propia cuenta, escribiendo la nueva contraseña en el campo Contraseña y presionando Guardar.

Perfiles disponibles

Asignar uno o varios sitios

En Ajustes → Usuarios, al crear o editar una cuenta puedes mantener Acceso a todos los sitios o desmarcarlo y seleccionar una o varias zonas. El administrador siempre conserva acceso global.

• Los usuarios existentes mantienen acceso a todos los sitios hasta que se configure una restricción.
• Una cuenta restringida solo ve clientes, mapa, instalaciones, tickets, facturas y cobros de sus zonas.
• El servidor también bloquea accesos directos a registros de otros sitios; no es únicamente un filtro visual.
• No se puede guardar una cuenta restringida sin seleccionar al menos un sitio.

La pestaña Clientes usa una lista compacta, igual que la demostración, para localizar personas con rapidez. Cada tarjeta muestra el estado online/offline, la deuda y los datos esenciales. Al pulsar Ver cliente se abre una ficha separada con sus acciones y cobros reales.

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
• Ver cliente: abre inmediatamente debajo de la tarjeta seleccionada una ficha con información, servicios y acciones
• Cobrar: abre la misma ficha directamente en las facturas pendientes
• Dentro de la ficha: WhatsApp, Editar, Cobrar total, Cortar / Reactivar y demás acciones reales

Búsqueda

El buscador propio de Clientes filtra las tarjetas por nombre, teléfono, IP, dirección o zona. Los chips se pueden combinar con la búsqueda y con el selector Todas las zonas, que también permite encontrar clientes sin zona asignada.

El selector de orden permite acomodar los resultados por nombre de A a Z o de Z a A, mayor o menor deuda, y por zona. A la derecha se muestra cuántos clientes cumplen todos los filtros aplicados. En celulares estos controles se acomodan verticalmente para facilitar su uso.

Las opciones de exportación, importación, cortes y suspensión manual están agrupadas en Herramientas para mantener la pantalla despejada.

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:

Desde Mapa, el cobrador puede activar Mi ubicación y ver los clientes ordenados por distancia. En celulares, la lista inferior permite buscar por nombre, dirección o zona y filtrar Con deuda o Cerca de mí (hasta 5 km).

• Cada cliente moroso muestra el total pendiente y la cantidad de facturas.
• Cómo llegar abre la navegación de Google Maps hasta las coordenadas guardadas.
• WhatsApp abre el contacto del cliente sin salir del recorrido.

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 flujo guiado de pagos está disponible dentro de la ficha de cada cliente. Permite cobrar una factura, varias o toda la deuda en una sola operación.

Cobrar una factura

Liquidar toda la deuda

Dentro de Registrar pago, pulsa Pagar toda la deuda. Todas las facturas quedarán seleccionadas y podrás revisar el total antes de confirmar.

Pagar y dar de baja el servicio

Si el cliente únicamente llega a cancelar lo que debe y ya no continuará, en Después del pago selecciona Paga su deuda y ya no continuará. El panel exige liquidar toda la deuda, conserva el historial, marca al cliente como Retirado, corta el acceso y deja de generar nuevas mensualidades.

Reconectar aunque todavía tenga deuda

En la ficha de un cliente suspendido con deuda aparece Reconectar junto a un selector de 1, 3, 7 o 15 días. La deuda no se elimina ni se marca como pagada; solamente se concede acceso temporal. Cuando vence el plazo, el siguiente control de cortes vuelve a suspenderlo si continúa sobre su límite.

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:

La pestaña Soporte centraliza incidencias de clientes, seguimiento interno y resolución. Cada ticket guarda el cliente, la categoría, la prioridad, comentarios y estado de atención.

Los tickets no se eliminan al cerrarlos: quedan como historial permanente en la ficha del cliente. En Clientes → Ver cliente → Tickets anteriores se muestran hasta los últimos 100 reportes con fecha, estado, descripción, técnico asignado, comentarios y fecha de cierre.

Flujo básico

Campos del ticket

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 alcanzaron el período mensual 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. También puedes confirmar o cambiar la Zona / Nodo del cliente antes de cobrar.
3. Se actualiza ultima_actualizacion en la base de datos
4. 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.

Los clientes antiguos que todavía no tienen una zona asignada se administran desde la primera zona configurada. Al usar Exportar reglas en esa zona también se sincronizan esos clientes.

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.

LibreNMS es la fuente del estado visible de disponibilidad. El panel evita consultar continuamente cada cliente desde MikroTik, reduciendo trabajo en los routers incluso cuando la red crece a cientos o miles de abonados.

Usa el botón LibreNMS de la cabecera o la tarjeta Monitoreo de red de Inicio. Se abrirá el servidor dedicado, donde puedes consultar disponibilidad, CPU, memoria, interfaces, tráfico y gráficas históricas.

La pestaña Clientes muestra un bloque rojo únicamente cuando el último sondeo de LibreNMS marca clientes sin respuesta. Las caídas se ordenan por nombre, se acomodan en dos columnas en computadora y en una columna en celular. Para conservar espacio se muestran primero 5 clientes; usa Ver caídas más para desplegar el resto. El badge indica cuántas caídas existen y se actualiza cada minuto. Una caída permanece visible hasta que un sondeo posterior confirme la recuperación; entonces aparece la alerta verde Conexión recuperada. La primera consulta solo establece la línea base y no repite avisos antiguos. Los clientes nuevos con IP válida se sincronizan con LibreNMS cada hora.

La campana combina las notificaciones administrativas de facturación, cobros, suspensiones, reactivaciones y errores de WhatsApp con las caídas activas y reconexiones detectadas por LibreNMS. Cada cliente caído aparece con su nombre e IP; cuando vuelve a estar en línea se retira de las caídas y se agrega un evento verde de recuperación.

Tipos de notificaciones

Historial

Haz clic en la campana para ver primero las caídas activas y después las últimas 50 notificaciones administrativas. Abrir la campana marca como leídos los avisos administrativos, pero el contador de caídas permanece visible mientras existan clientes sin conexión.

La pestaña Inicio muestra métricas administrativas y un acceso directo a LibreNMS.

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 personalizada que muestra su nombre, el total adeudado, sus facturas pendientes, datos de contacto y métodos de pago.

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/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/proxy/access para esa IP específica con action=redirect a la URL del portal.
5. Se cierran las conexiones activas del cliente para evitar que FastTrack mantenga tráfico anterior al corte.

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”
• Total pendiente destacado
• 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 ajustes están organizados en pestañas. Selecciona una categoría en la barra superior para ver solamente sus opciones; la última pestaña utilizada queda recordada para la próxima visita.

En Ajustes → Publicidad puedes cambiar el anuncio que aparece al final de cada recibo impreso y PDF.

La vista previa cambia mientras escribes. Presiona Guardar Ajustes para aplicar el anuncio a los siguientes recibos.

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)
• Alertas de red y disponibilidad → se administran desde LibreNMS

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 puede detectar como spam los envíos repetitivos o demasiado rápidos. El sistema reduce el riesgo con una cola de envío: aplica una pausa aleatoria mínima de 12 segundos, descansa de 3 a 5 minutos después de cada lote de 20 mensajes, varía el cierre y registra cada destinatario enviado para no repetirlo durante el mismo mes.

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 2 tareas automáticas propias. LibreNMS ejecuta por separado sus tareas de descubrimiento y sondeo:

¿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.

¿Dónde reviso si un router o enlace está fuera de línea?

Abre LibreNMS desde la cabecera del panel. Allí se centralizan la disponibilidad, interfaces, tráfico, CPU, memoria y gráficas históricas.

¿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.