siip-available-ips/README.md

# SIIP - Buscador de IP's Disponibles UISP

[![Version](https://img.shields.io/badge/version-1.3.2-blue.svg)](manifest.json)
[![UCRM](https://img.shields.io/badge/UCRM-Compatible-green.svg)](https://uisp.com/)
[![UNMS](https://img.shields.io/badge/UNMS-Compatible-green.svg)](https://uisp.com/)

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](#-características)
- [Requisitos](#-requisitos)
- [Instalación](#-instalación)
- [Configuración](#️-configuración)
- [Uso del Frontend Web](#-uso-del-frontend-web)
- [API REST](#-api-rest)
  - [Endpoints Disponibles](#endpoints-disponibles)
  - [Ejemplos de Uso](#ejemplos-de-uso)
- [Estructura del Proyecto](#-estructura-del-proyecto)
- [Filtrado de IPs Administrativas](#-filtrado-de-ips-administrativas)
- [Logs y Debugging](#-logs-y-debugging)
- [Changelog](#-changelog)
- [Soporte](#-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
- 🔌 **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)
- 📊 **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

```bash
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 |
| **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**:
```json
{
  "type": "event.ip_request",
  "segment": "5"
}
```

**Response (Éxito)**:
```json
{
  "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**:
```json
{
  "type": "event.ip_request",
  "segment": "5",
  "verify_ping": true,
  "ping_limit": 5
}
```

**Response con ping**:
```json
{
  "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**:
```json
{
  "type": "event.ip_check",
  "ip": "172.16.5.100"
}
```

**Response (IP Disponible)**:
```json
{
  "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)**:
```json
{
  "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

```bash
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

```bash
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
<?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

```javascript
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

```python
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](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 →](CHANGELOG.md)

---

## 🆘 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](https://siip.mx)
- **Autor**: SIIP Internet

---

## 📄 Licencia

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


---

**Versión**: 1.3.0  
**Última actualización**: 26 de noviembre de 2025