siip-available-ips/README.md

# SIIP - Buscador de IP's Disponibles UISP

[![Version](https://img.shields.io/badge/version-1.6.1-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
- 🌓 **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

```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 |
| **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 (se gestiona desde el editor visual) |
| **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 detallados en consola del navegador para diagnóstico |
| **Enable debug logs** | Logs verbosos | Información adicional en logs del servidor |

> **💡 Tip**: Para configurar rangos personalizados por segmento, marca el checkbox "Usar rangos personalizados por segmento" y haz clic en el botón ⚙️ (Configuración Avanzada) en la interfaz principal. Necesitarás la contraseña de administrador configurada.

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

### Sistema de Validación Multi-Capa de IPs

El plugin implementa un **sistema de validación de 4 capas** para garantizar que solo se muestren IPs 100% disponibles:

#### 🔍 Capa 1: Filtrado UISP (Dispositivos Registrados)
- **Endpoint**: `/nms/api/v2.1/devices/ips`
- **Función**: Filtra IPs de dispositivos registrados en UISP
- **Incluye**: 
  - Dispositivos activos y suspendidos
  - Dispositivos de gestión
  - Dispositivos obsoletos
- **Resultado**: Elimina IPs que ya están asignadas a dispositivos en UISP

#### 🏢 Capa 2: Filtrado CRM (Servicios Suspendidos/Finalizados)
- **Endpoint**: `/crm/api/v1.0/clients/services`
- **Función**: Filtra IPs de clientes con servicios problemáticos
- **Estados filtrados**:
  - `status=2`: Servicios finalizados (Ended)
  - `status=3`: Servicios suspendidos (Suspended)
- **Proceso**:
  1. Obtiene servicios con estados 2 y 3
  2. Extrae `unmsClientSiteId` de cada servicio
  3. Mapea IPs de UISP a sitios
  4. Filtra IPs que pertenecen a sitios bloqueados
- **Resultado**: Elimina IPs de clientes con servicios suspendidos o finalizados (aunque el dispositivo aún esté en UISP)

#### 🌐 Capa 3: Validación por Búsqueda de Sitios (Clientes Activos)
- **Endpoint**: `/nms/api/v2.1/sites/search?type=subscriber`
- **Función**: Detecta IPs de clientes activos que no aparecen en `/devices/ips`
- **Proceso**:
  1. Para cada IP "disponible", busca sitios de tipo `subscriber`
  2. Si encuentra un sitio, obtiene sus dispositivos
  3. Verifica si algún dispositivo tiene exactamente esa IP
  4. Si encuentra coincidencia exacta, marca la IP como "en uso"
- **Casos detectados**:
  - IPs secundarias de dispositivos (no aparecen en IP principal)
  - Dispositivos con IPs en `ipAddressList`
  - Clientes activos con dispositivos no sincronizados
- **Resultado**: Elimina IPs que están en uso por clientes activos pero no detectadas por las capas anteriores

#### 🏓 Capa 4: Verificación por Ping (Opcional)
- **Función**: Detecta dispositivos de terceros no registrados en UISP
- **Proceso**:
  1. Usuario marca checkbox "Verificar con ping"
  2. Selecciona cantidad de IPs a verificar (10, 20, 50, Todas)
  3. El sistema hace ping a cada IP progresivamente
  4. Marca como "En uso (Ping)" las IPs que responden
- **Casos detectados**:
  - Dispositivos de terceros (no clientes)
  - Equipos de red no registrados
  - Dispositivos temporales
- **Resultado**: Solo muestra IPs que NO responden a ping

### Flujo Completo de Validación

```
┌─────────────────────────────────────────────────────────────┐
│ Usuario busca IPs en segmento 172.16.54.x                  │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│ CAPA 1: Filtrado UISP                                       │
│ ✓ Obtiene IPs de /devices/ips                              │
│ ✓ Filtra IPs en uso por dispositivos registrados           │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│ CAPA 2: Filtrado CRM                                        │
│ ✓ Obtiene servicios suspendidos/finalizados                │
│ ✓ Mapea IPs a sitios bloqueados                            │
│ ✓ Filtra IPs de servicios problemáticos                    │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│ CAPA 3: Validación por Búsqueda de Sitios                  │
│ ✓ Para cada IP "disponible":                               │
│   - Busca sitio con /sites/search?type=subscriber          │
│   - Verifica dispositivos del sitio                        │
│   - Comprueba coincidencia exacta de IP                    │
│ ✓ Filtra IPs de clientes activos                           │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│ CAPA 4: Verificación por Ping (Opcional)                   │
│ ✓ Usuario marca "Verificar con ping"                       │
│ ✓ Hace ping a cada IP progresivamente                      │
│ ✓ Filtra IPs que responden                                 │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│ RESULTADO: Solo IPs 100% Disponibles                       │
│ ✅ No están en UISP                                         │
│ ✅ No pertenecen a servicios suspendidos/finalizados       │
│ ✅ No están en uso por clientes activos                    │
│ ✅ No responden a ping (si está habilitado)                │
└─────────────────────────────────────────────────────────────┘
```

### Configuración de Filtros

#### Filtrado Administrativo
- **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.

### ⚙️ Configuración Avanzada de Rangos por Segmento

A partir de la versión 1.5.0, puedes definir rangos de IPs administrativas específicos para cada segmento de red.

**Acceso:**
1. Marca el checkbox **"Usar rangos personalizados por segmento"** en la configuración del plugin
2. Configura una **"Contraseña de administrador"** en la configuración del plugin
3. Haz clic en el botón **⚙️** (Configuración Avanzada) en la esquina superior derecha de la interfaz principal
4. Ingresa la contraseña configurada

**Características del Editor:**
- **Interfaz visual**: No necesitas editar JSON manualmente
- **Múltiples rangos**: Define varios rangos iniciales y finales por segmento
- **Validación automática**: El sistema valida que los rangos sean correctos
- **Indicador de modo**: Badge visual que muestra si los rangos personalizados están activos
- **CRUD Completo** (v1.5.1):
  - ✅ **Crear**: Agregar nuevos segmentos
  - ✅ **Leer**: Ver segmentos en tabla
  - ✅ **Actualizar**: Editar segmentos existentes con botón "✏️ Editar"
  - ✅ **Eliminar**: Borrar segmentos con botón "🗑️ Eliminar"

**Gestión de Segmentos:**
1. **Agregar**: Completa el formulario y haz clic en "✅ Agregar Segmento"
2. **Editar**: Haz clic en "✏️ Editar" en la tabla, modifica los rangos y haz clic en "💾 Actualizar Segmento"
3. **Eliminar**: Haz clic en "🗑️ Eliminar" y confirma la acción

**Ejemplo de Configuración:**
- **Segmento 13**: IPs administrativas del 2 al 60 y del 253 al 255
- **Segmento 15**: IPs administrativas del 2 al 30 y del 253 al 255
- **Segmento 18**: IPs administrativas del 1 al 50 y del 253 al 255
- **Otros segmentos**: Usan los rangos globales configurados

**Fallback Inteligente:**
Los segmentos no configurados en el editor avanzado usarán automáticamente los rangos globales definidos en la configuración básica del plugin.

---

## 🔌 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`
- `verify_ping` (boolean, opcional): Si es `true`, verifica si la IP responde a ping (default: `false`)

**Ejemplo con verificación de ping**:
```json
{
  "type": "event.ip_check",
  "ip": "172.16.5.70",
  "verify_ping": true
}
```

**Response con ping**:
```json
{
  "success": true,
  "event": "event.ip_check",
  "ip": "172.16.5.70",
  "status": "available",
  "available": true,
  "used": false,
  "ip_type": {
    "type": "client",
    "label": "Apta para cliente",
    "recommended": true,
    "description": "Recomendada para asignar a clientes"
  },
  "ping_verified": true,
  "ping_responds": false
}
```

> **Nota**: Si `ping_responds` es `true` pero `available` también es `true`, se incluirá un campo `warning` indicando que la IP responde a ping pero no está registrada en UISP (posible conflicto).

---

### 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

---

**Versión 1.5.1** - Diciembre 2025  
Desarrollado por [SIIP Internet](https://siip.mx)

---

## 📄 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