SIIP - Buscador de IP's Disponibles UISP

Plugin para UISP CRM (anteriormente UCRM) que permite buscar direcciones IP disponibles en la red UISP/UNMS y asignarlas a clientes, evitando duplicados y mejorando la gestión de direcciones IP.

---

📋 Tabla de Contenidos

• Características
• Requisitos
• Instalación
• Configuración
• Uso del Frontend Web
• API REST
  • Endpoints Disponibles
  • Ejemplos de Uso
• Estructura del Proyecto
• Filtrado de IPs Administrativas
• Logs y Debugging
• Changelog
• Soporte

---

✨ Características

• 🔍 Búsqueda de IPs disponibles por segmento de red (172.16.X.x)
• 🌐 Interfaz web moderna con diseño responsive y atractivo
• 🌓 Modo Claro/Oscuro con toggle y persistencia de preferencia
• 🔌 API REST completa para integraciones externas
• 📋 Copiar al portapapeles con un solo clic
• 🎯 Filtrado inteligente de IPs administrativas vs. IPs para clientes
• 🏓 Verificación por ping para detectar dispositivos no registrados (opcional)
• 🛑 Cancelar verificación en cualquier momento conservando resultados parciales
• 📊 Estadísticas en tiempo real de IPs disponibles y en uso
• 🔐 Integración nativa con UISP CRM y UNMS
• 🪝 Soporte para webhooks y eventos personalizados
• 📝 Sistema de logs detallado para debugging

---

📦 Requisitos

• UISP CRM versión 1.0.0 o superior
• UISP UNMS versión 1.0.0 o superior (opcional)
• PHP 7.2 o superior
• cURL habilitado en PHP
• Token de API de UCRM
• Token de API de UNMS (opcional, para búsqueda de IPs)

---

🚀 Instalación

Método 1: Instalación Manual

1. Descarga o clona este repositorio
2. Comprime la carpeta del plugin en formato .zip
3. En UISP CRM, ve a Sistema → Plugins
4. Haz clic en "Subir nuevo plugin"
5. Selecciona el archivo .zip y súbelo
6. Activa el plugin desde la lista de plugins

Método 2: Instalación desde Git

cd /path/to/ucrm/data/plugins/
git clone <repository-url> siip-available-ips
cd siip-available-ips
composer install

---

⚙️ Configuración

Después de instalar el plugin, configura los siguientes parámetros:

Parámetros Requeridos

Parámetro	Descripción	Ejemplo
Dirección IP o dominio del servidor	IP o dominio donde se ejecuta UISP CRM	172.16.5.120 o sistema.empresa.com
Token de la API UCRM	Token de autenticación de UCRM (36 caracteres)	3d3fa6c9-e268-6e8b-b4d5-aae394d99d7d

Parámetros Opcionales

Parámetro	Descripción	Uso
Token de la API UNMS	Token de UNMS (34 caracteres)	Para búsqueda de IPs en dispositivos de red
Habilitar verificación por Ping	Activa modo de verificación por ping	Permite verificar disponibilidad real de IPs
Inicio primer rango admin	Primera IP del rango administrativo inicial (default: 1)	Define el inicio del primer rango de IPs administrativas
Fin primer rango admin	Última IP del rango administrativo inicial (default: 30)	Define el fin del primer rango de IPs administrativas
Inicio rango admin final	Primera IP del rango administrativo final (default: 254)	Define el inicio del rango final de IPs administrativas
Fin rango admin final	Última IP del rango administrativo final (default: 254)	Define el fin del rango final de IPs administrativas
Usar rangos personalizados por segmento	Habilita configuración avanzada por segmento	Permite definir rangos específicos para cada segmento de red
Configuración JSON de rangos	JSON con rangos por segmento	Configuración detallada de rangos administrativos personalizados
Contraseña de administrador	Contraseña para editor avanzado	Protege el acceso al editor de configuración avanzada
Debug Mode	Modo de depuración	Habilita logs más detallados
Enable debug logs	Logs verbosos	Información adicional en logs

Cómo obtener los tokens:

Token UCRM:

1. Ve a Sistema → Seguridad → Claves de aplicación
2. Crea una nueva clave con permisos de lectura/escritura
3. Copia el token generado

Token UNMS:

1. Accede al módulo UISP Network
2. Ve a Ajustes → Usuarios → API Tokens
3. Genera un nuevo token
4. Copia el token generado

---

🖥️ Uso del Frontend Web

Acceso

El frontend web está disponible en:

• Menú UCRM: Reportes → Consultar IP's Disponibles
• URL directa: https://tu-servidor/plugins/siip-available-ips/public.php

Interfaz de Usuario

La interfaz incluye:

1. Campo de búsqueda: Ingresa el tercer octeto del segmento (ej: 5 para buscar en 172.16.5.x)
2. Botón "Buscar IPs": Ejecuta la búsqueda
3. Tabla de resultados: Muestra las IPs disponibles con:
   • Dirección IP completa
   • Tipo de IP (Cliente / Administración)
   • Botón de copiar al portapapeles
4. Estadísticas: Muestra contadores de IPs disponibles y en uso

Ejemplo de Uso

1. Ingresa "5" en el campo de búsqueda
2. (Opcional) Marca "Verificar con ping" si está habilitado
3. Haz clic en "Buscar IPs"
4. Se mostrarán todas las IPs disponibles en el rango 172.16.5.x
5. Haz clic en el botón "Copiar" junto a la IP deseada
6. La IP se copia automáticamente al portapapeles

Verificación por Ping (Opcional)

Si está habilitada en la configuración, aparecerá un checkbox "🔍 Verificar con ping" (marcado por defecto) y un selector de límite.

Opciones de Límite:

• Todas (Lento): Verifica todas las IPs del segmento.
• 5, 10, 20 IPs (Rápido): Verifica solo las primeras N IPs disponibles para clientes.

Feedback Visual:

• ⏳ Pendiente/Verificando: La IP está siendo analizada.
• ✅ Disponible: La IP está libre en UISP y no responde a ping.
• ⚠️ En uso (Ping): La IP está libre en UISP pero responde a ping (posible conflicto).

Filtrado de IPs

• Ocultar Admin IPs: Checkbox para ocultar/mostrar instantáneamente las IPs reservadas para administración (x.x.x.1-30 y x.x.x.254).

Cancelar Verificación

Durante la verificación por ping, aparece un botón "🛑 Cancelar Verificación" que permite:

• Detener el proceso de verificación en cualquier momento.
• Conservar los resultados ya obtenidos en la tabla.
• Útil cuando se selecciona "Todas" y ya se han verificado suficientes IPs disponibles.

Comportamiento:

1. El botón aparece automáticamente al iniciar la verificación.
2. Al presionarlo, se detiene el proceso inmediatamente.
3. Las IPs ya verificadas permanecen en la tabla.
4. El botón desaparece al finalizar o cancelar.

---

🔌 API REST

El plugin expone una API REST completa para integraciones externas, webhooks y automatizaciones.

Configuración Base

• URL Base: https://tu-servidor/plugins/siip-available-ips/public.php
• Método: POST
• Content-Type: application/json
• Autenticación: No requerida (el plugin usa los tokens configurados internamente)

Endpoints Disponibles

1. Buscar IPs Disponibles

Busca todas las IPs disponibles en un segmento de red específico.

Evento: event.ip_request

Request:

{
  "type": "event.ip_request",
  "segment": "5"
}

Response (Éxito):

{
  "success": true,
  "event": "event.ip_request",
  "segment": "172.16.5.x",
  "data": {
    "available": [
      "172.16.5.31",
      "172.16.5.32",
      "172.16.5.33"
    ],
    "used": [
      "172.16.5.1",
      "172.16.5.2"
    ]
  },
  "count": {
    "available": 223,
    "used": 31,
    "admin_filtered": 31
  },
  "message": "Se encontraron 223 IPs aptas para clientes en el segmento 172.16.5.x (31 IPs administrativas filtradas)"
}

Parámetros:

• type (string, requerido): Tipo de evento, debe ser "event.ip_request"
• segment (string, requerido): Tercer octeto del segmento (0-255)
• verify_ping (boolean, opcional): Si es true, verifica IPs con ping antes de reportarlas
• ping_limit (int, opcional): Cantidad máxima de IPs a verificar (0 = todas, default: 0)

Ejemplo con límite:

{
  "type": "event.ip_request",
  "segment": "5",
  "verify_ping": true,
  "ping_limit": 5
}

Response con ping:

{
  "success": true,
  "event": "event.ip_request",
  "segment": "172.16.5.x",
  "data": {
    "available": ["172.16.5.31", "172.16.5.32"],
    "used": ["172.16.5.1"]
  },
  "ping_verified": true,
  "ping_stats": {
    "total_checked": 5,
    "responding": 0,
    "not_responding": 5,
    "execution_time": "0.8s",
    "limit_applied": 5
  },
  "ping_responding": []
}

Notas:

• Las IPs administrativas (1-30 y 254) son filtradas automáticamente
• Solo se devuelven IPs aptas para asignar a clientes (31-253)
• Si verify_ping es true, las IPs que responden a ping se filtran automáticamente

---

2. Verificar Estado de una IP

Verifica si una IP específica está disponible o en uso.

Evento: event.ip_check

Request:

{
  "type": "event.ip_check",
  "ip": "172.16.5.100"
}

Response (IP Disponible):

{
  "success": true,
  "event": "event.ip_check",
  "ip": "172.16.5.100",
  "status": "available",
  "available": true,
  "used": false,
  "ip_type": {
    "type": "client",
    "label": "Apta para cliente",
    "recommended": true,
    "description": "Recomendada para asignar a clientes"
  }
}

Response (IP en Uso):

{
  "success": true,
  "event": "event.ip_check",
  "ip": "172.16.5.1",
  "status": "IP en uso y además para uso administrativo",
  "available": false,
  "used": true,
  "ip_type": {
    "type": "admin",
    "label": "Administración",
    "recommended": false,
    "description": "No recomendada para clientes"
  }
}

Parámetros:

• type (string, requerido): Tipo de evento, debe ser "event.ip_check"
• ip (string, requerido): Dirección IP completa en formato 172.16.X.X

---

Ejemplos de Uso

cURL - Buscar IPs Disponibles

curl -X POST https://tu-servidor/plugins/siip-available-ips/public.php \
  -H "Content-Type: application/json" \
  -d '{
    "type": "event.ip_request",
    "segment": "5"
  }'

cURL - Verificar IP Específica

curl -X POST https://tu-servidor/plugins/siip-available-ips/public.php \
  -H "Content-Type: application/json" \
  -d '{
    "type": "event.ip_check",
    "ip": "172.16.5.100"
  }'

PHP - Buscar IPs Disponibles

<?php
$url = 'https://tu-servidor/plugins/siip-available-ips/public.php';
$data = [
    'type' => 'event.ip_request',
    'segment' => '5'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>

JavaScript/Node.js - Verificar IP

const axios = require('axios');

const checkIp = async (ip) => {
  try {
    const response = await axios.post(
      'https://tu-servidor/plugins/siip-available-ips/public.php',
      {
        type: 'event.ip_check',
        ip: ip
      },
      {
        headers: {
          'Content-Type': 'application/json'
        }
      }
    );
    
    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.message);
  }
};

checkIp('172.16.5.100');

Python - Buscar IPs Disponibles

import requests
import json

url = 'https://tu-servidor/plugins/siip-available-ips/public.php'
payload = {
    'type': 'event.ip_request',
    'segment': '5'
}

response = requests.post(
    url,
    json=payload,
    headers={'Content-Type': 'application/json'},
    verify=False
)

result = response.json()
print(json.dumps(result, indent=2))

---

Códigos de Error

Código	Descripción	Solución
Missing event type	No se especificó el campo type	Incluye "type" en el JSON
Unknown event type	Tipo de evento no soportado	Usa event.ip_request o event.ip_check
Missing segment	Falta el campo segment	Incluye "segment" en el request
Missing IP address	Falta el campo ip	Incluye "ip" en el request
Invalid IP format	Formato de IP inválido	Usa formato 172.16.X.X
Plugin not configured	Configuración incompleta	Verifica tokens en configuración del plugin
IP search failed	Error en búsqueda	Revisa logs del plugin

---

📁 Estructura del Proyecto

siip-available-ips/
├── manifest.json              # Configuración del plugin
├── composer.json              # Dependencias PHP
├── main.php                   # Punto de entrada principal
├── public.php                 # Frontend web + API REST
├── README.md                  # Este archivo
├── src/                       # Código fuente
│   ├── ApiHandlers.php        # Manejadores de API REST
│   ├── IpSearchService.php    # Servicio de búsqueda de IPs
│   └── PingService.php        # Servicio de verificación por ping
├── data/                      # Datos del plugin
│   ├── config.json            # Configuración (generado automáticamente)
│   └── plugin.log             # Archivo de logs
└── vendor/                    # Dependencias de Composer

Archivos Principales

public.php

• Punto de entrada para frontend web y API REST
• Detecta automáticamente el tipo de petición (HTML vs JSON)
• Maneja errores globales y logging

src/ApiHandlers.php

Funciones para manejar peticiones API:

• handleApiRequest(): Router principal de eventos
• handleIpRequest(): Procesa event.ip_request
• handleIpCheck(): Procesa event.ip_check

src/IpSearchService.php

Clase de servicio para búsqueda de IPs:

• buscarIpsDisponibles(): Busca IPs en un segmento
• obtenerIpsEnUso(): Obtiene IPs desde API UNMS
• isAdminIp(): Determina si una IP es administrativa
• getIpType(): Obtiene información del tipo de IP

src/PingService.php

Clase de servicio para verificación por ping:

• pingMultipleIps(): Ping paralelo a múltiples IPs
• pingIp(): Ping a una sola IP
• processPingResults(): Procesa resultados de ping
• isAvailable(): Verifica si ping está disponible

---

🎯 Filtrado de IPs Administrativas

El plugin implementa un sistema inteligente de filtrado de IPs:

Rangos de IPs

Rango	Tipo	Uso	Recomendación
.1 - .30	Administrativa	Gateways, servidores, equipos de red	❌ No asignar a clientes
.31 - .253	Cliente	Dispositivos de clientes finales	✅ Apto para clientes
.254	Broadcast	Dirección de broadcast	❌ No asignar

Comportamiento

• Frontend Web: Muestra todas las IPs con etiquetas de tipo
• API REST: Filtra automáticamente IPs administrativas
• event.ip_check: Indica el tipo de IP en la respuesta

---

📝 Logs y Debugging

Ubicación de Logs

Los logs se guardan en:

/data/plugin.log

Habilitar Debug Mode

1. Ve a la configuración del plugin
2. Activa "Debug Mode"
3. Activa "Enable debug logs"
4. Los logs incluirán información detallada de:
   • Peticiones recibidas
   • Respuestas de API UNMS
   • Errores y excepciones
   • Tiempos de ejecución

Ejemplo de Log

[2025-11-26 11:30:15] >>> Petición recibida en public.php
[2025-11-26 11:30:15] Método: POST
[2025-11-26 11:30:15] Content-Type: application/json
[2025-11-26 11:30:15] Procesando evento API: event.ip_request
[2025-11-26 11:30:15] API: Buscando IPs en segmento 5
[2025-11-26 11:30:16] Respuesta HTTP: 200
[2025-11-26 11:30:16] IPs obtenidas exitosamente: 254 direcciones
[2025-11-26 11:30:16] Búsqueda de IPs en segmento 172.16.5.x - Disponibles: 223, En uso: 31

---

📜 Changelog

Para ver el historial completo de cambios y versiones, consulta el archivo CHANGELOG.md.

Versión Actual: 1.2.0 (2025-11-26)

Cambios destacados:

• 🏓 Verificación por ping para detectar dispositivos no registrados
• ⚡ Ping paralelo de hasta 30 IPs simultáneamente
• 🎛️ Control opcional vía configuración
• 📊 Estadísticas detalladas de verificación
• ✨ API REST completa con endpoints event.ip_request y event.ip_check
• 🔌 Soporte para webhooks y eventos personalizados
• 🎯 Filtrado automático de IPs administrativas
• 📚 Documentación completa con ejemplos en múltiples lenguajes

Ver changelog completo →

---

🆘 Soporte

Problemas Comunes

Error: "Plugin not configured"

Solución: Verifica que hayas configurado correctamente los tokens de API en la configuración del plugin.

Error: "Error al conectar con la API de UISP"

Solución:

• Verifica que el servidor UNMS esté accesible
• Comprueba que el token de API UNMS sea válido
• Revisa los logs para más detalles

No se muestran IPs disponibles

Solución:

• Verifica que el segmento ingresado sea válido (0-255)
• Comprueba que existan dispositivos en ese segmento en UNMS
• Revisa los logs con debug mode activado

Contacto

• Sitio web: https://siip.mx
• Autor: SIIP Internet

---

📄 Licencia

Este plugin es propiedad de SIIP Internet. Todos los derechos reservados.

---

Versión: 1.5.0
Última actualización: 27 de noviembre de 2025