145 lines
11 KiB
Markdown
Executable File
145 lines
11 KiB
Markdown
Executable File
# SIIP - WhatsApp Notifications & Integrated Payment Portal
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Este plugin es una solución integral que transforma tu UCRM en un **Portal Administrativo de Última Generación**. No solo automatiza la comunicación por WhatsApp, sino que integra un Dashboard completo para la gestión de pagos online (Stripe/OXXO), visualización de comprobantes y coordinación de equipos técnicos.
|
|
|
|
## ✨ Novedades v4.7.4 (Offline CPE Password Preservation Hotfix)
|
|
|
|
- **🔑 Preservación de Clave de Antena Desconectada**: Se añadió una capa de validación que detecta si el CPE del cliente en UISP está fuera de línea. Si ya existía una contraseña válida en UCRM, el script evita sobrescribirla con la leyenda de error por desconexión. Esto preserva la credencial de acceso para que los instaladores puedan conectarse físicamente al equipo y alinearlo o repararlo en sitio.
|
|
|
|
## ✨ Novedades v4.7.3 (Antenna Password Tag Fixes, Overwrite Protections & Sync)
|
|
|
|
- **🔄 Sincronización CallBell Inmediata**: Los datos del cliente se refrescan de forma activa en el objeto de notificación antes de llamar a la sincronización, garantizando que el nuevo Site y contraseña de la antena se actualicen en CallBell inmediatamente en el mismo evento del webhook.
|
|
- **🏷️ Robustez en Detección de Etiquetas**: Modificada la detección de tags en `client.edit` (`OBTENER PASSWORD ANTENA`, etc.) para leer directamente del objeto `$notification->clientData['tags']`, logrando compatibilidad con los webhooks estándar de producción en UCRM (los cuales no proveen la clave `extraData`).
|
|
- **🛡️ Protección contra Sobrescrituras de Red**: Agregadas validaciones inteligentes en los actualizadores (`audit_client_passwords.php` y `ejemplo_script_actualizador.php`) para evitar que caídas de red o errores de asociación de la API de UISP reemplacen atributos del CRM con valores genéricos destructivos (como `"Sin SITE"` o `"REPETIDOR"`) si ya existían datos de sector válidos.
|
|
- **📝 Integración de Log de Errores**: Integrado el logger principal del plugin con el script de auditoría de UISP para mostrar de forma amigable cualquier error de conexión con la API en el panel del plugin de UCRM (`data/plugin.log`).
|
|
- **📡 Resolución Inteligente de Site (AP Fallback)**: En redes de UISP sin jerarquías Padre-Hijo estructuradas (donde no hay parent site directo en el dispositivo del cliente), el plugin ahora recupera y asocia dinámicamente el Site de la Torre a partir del AP (Access Point) al que está conectada la antena.
|
|
|
|
|
|
## ✨ Novedades v4.7.1 (Robustness & Scheduling Filters)
|
|
|
|
- **🛡️ Robustez de UI de Pestañas**: Se eliminó la búsqueda y dependencias en los eventos `onclick` inline (que se bloqueaban por CSP o eran alterados por minificadores de HTML de UCRM en producción) y se implementó un sistema basado en atributos nativos `data-tab` para la navegación segura entre los módulos del portal.
|
|
- **👷 Filtro de Tareas de Técnicos**: Se actualizó la llamada de API de scheduling para traer únicamente los tickets que se encuentran en estatus **Abierto** (`0`) o **En curso/Pendiente** (`1`), ocultando correctamente aquellos tickets ya solucionados o cerrados (`2`).
|
|
|
|
## ✨ Novedades v4.7.0 (Payment Events & Size Optimization)
|
|
|
|
- **🔄 Sincronización Completa de Eventos de Pagos**: Soporte para la sincronización automática en Callbell ante eventos de edición (`payment.edit`), desvinculación (`payment.unmatch`) y eliminación (`payment.delete`) de pagos en UCRM, manteniendo los saldos de clientes siempre actualizados.
|
|
- **🛡️ Estabilidad Anti-404**: Mapeo directo de la entidad desde el payload del webhook para evitar errores HTTP 404 al consultar pagos que ya fueron eliminados.
|
|
- **⚡ Reducción Masiva de Tamaño**: Eliminación del SDK de Google no utilizado y optimización de exclusiones en el script de empaquetado, reduciendo la carpeta `vendor` a 28 MB y el tamaño del archivo ZIP empaquetado a solo **8.1 MB** (anteriormente ~45 MB).
|
|
|
|
## ✨ Novedades v4.6.0 (Stripe & OXXO Stability)
|
|
|
|
- **🛡️ Estabilidad en Pagos (Stripe CashBalance)**: Nuevo sistema para comprobar fondos y validación contra intención de pagos para evitar las intenciones huérfanas o duplicadas tras recibir transferencias SPEI.
|
|
- **🧹 Limpieza y Auditoría Local**: Integración local de scripts `audit_incomplete_pi` y `clean_incomplete_pi` para mantenimiento seguro de intenciones de pago incompletas sin afectar comprobantes de OXXO vigentes.
|
|
- **🖼️ Interfaz OXXO Optimizada**: Rediseño interno y de contenedores CSS + validación del microservicio `puppeteer-server` para devolver fichas OXXO perfectamente legibles.
|
|
|
|
## ✨ Novedades v4.4.0 (Resend Job Notifications)
|
|
|
|
- **📋 Tabla de Tareas Activas por Instalador**: Nuevo módulo dentro de "Gestión de Instaladores" que muestra los jobs "En curso" de cada técnico con datos de cliente, fecha y descripción.
|
|
- **📨 Reenvío Manual de Notificaciones**: Botón para reenviar la notificación WhatsApp de asignación de tarea a cualquier instalador desde la interfaz del plugin.
|
|
- **🔗 Integración con API de Scheduling**: Consulta dinámica de `GET /scheduling/jobs?assignedUserId=X&statuses[]=1` para listar tareas activas en tiempo real.
|
|
|
|
## 🐛 Hotfix v4.3.1 (Installer Notification Fix)
|
|
|
|
- **🔧 Fix Cambio de Instalador**: Corregido bug donde el nuevo técnico recibía mensaje de desasignación en vez de asignación al cambiar instalador en una tarea "En curso".
|
|
|
|
## 🔐 Novedades v4.3.0 (Security & Premium UI)
|
|
|
|
- **🛡️ Sistema de Acceso Seguro**: Implementada validación híbrida (Server + Client). El plugin ahora protege las URLs públicas mediante una pantalla de inicio de sesión que requiere credenciales de Administrador de UCRM o autenticación 2FA.
|
|
- **💎 Autenticación Premium (Glassmorphism)**: Nueva pantalla de inicio de sesión con una interfaz elegante y de lujo basada en Glassmorphism interactivo (esferas flotantes, desenfoques profundos, switch animado tipo iOS para modo oscuro).
|
|
- **🚀 Single-Sign-On Ciego**: Si el administrador ya ingresó desde el portal interno UCRM, la capa de seguridad detecta la sesión local y le otorga acceso sin pedir credenciales, optimizando el flujo de trabajo.
|
|
|
|
## 🚀 Novedades v4.2.0 (Analytics & Sync)
|
|
|
|
- **📊 Visualizador de Pagos Mensuales**: Nueva herramienta de análisis que permite seleccionar cualquier mes y visualizar gráficamente:
|
|
- Estadísticas de clientes activos vs clientes que pagaron
|
|
- Gráfica de dona interactiva con Chart.js
|
|
- Listado detallado de clientes pendientes con saldos
|
|
- Porcentajes de cobranza en tiempo real
|
|
- **🔄 Sincronización Mejorada CallBell**: Fix crítico que garantiza la actualización automática del saldo y estado del cliente en CallBell cuando se agregan facturas o se modifican servicios.
|
|
- **🎯 Categorización Inteligente de Pagos**: Nuevo microservicio con acceso directo a la base de datos para obtener metadata de Stripe (tipo de pago) y asignar correctamente los atributos incluso cuando la API de UCRM no tiene la información.
|
|
- **⚙️ Configuración para Producción**: Sistema de `.env` implementado para gestión segura de credenciales de base de datos.
|
|
|
|
## 🚀 Novedades v4.1.0 (Performance & Storage)
|
|
|
|
- **⚡ Microservicio PDF (`pdf-cropper`)**: Nuevo motor de renderizado externo (Python/FastAPI) que reemplaza librerías legacy, aumentando la velocidad y eliminando problemas de memoria en el servidor principal.
|
|
- **📦 MinIO / S3 Storage**: Migración completa del almacenamiento de comprobantes. Adiós FTP, hola almacenamiento de objetos seguro y escalable con URLs firmadas y limpieza automática.
|
|
- **🖼️ Smart Image Processing**: Generación de imágenes "Full Mode" (sin recortes) y capacidad de **Edición Dinámica de Texto** (Overlay) para personalizar métodos de pago en los comprobantes.
|
|
|
|
## 🚀 Novedades v4.0.0 (Portal Dashboard)
|
|
|
|
- **🖥️ Dashboard de Pagos Integrado**: Nueva interfaz visual dentro de UCRM para gestionar cobros de Stripe y OXXO sin salir de la plataforma.
|
|
- **🏪 OXXO Pay Híbrido & Visual**: Generación de fichas OXXO con dos modos inteligentes:
|
|
- **Inline (Admin)**: Visualización inmediata del voucher (local) para máxima velocidad.
|
|
- **FTP (Webhook)**: Carga automática a servidor externo para compartir links públicos.
|
|
- **🌑 UI/UX Premium**: Interfaz rediseñada con Sidebar expandible, cabecera global "Sticky", Modo Oscuro automático y componentes responsivos.
|
|
|
|
---
|
|
|
|
## ⚡ Funcionalidades Principales
|
|
|
|
### 1. Gestión de Cobranza Avanzada
|
|
|
|
- **Pagos SPEI**: Instrucciones inmediatas con CLABE personalizada.
|
|
- **Vouchers OXXO**: Generación instantánea de códigos de barras con vista previa "Split-Screen" (Datos + Imagen).
|
|
- **Historial en Tiempo Real**: Consulta los últimos 10 pagos de cualquier cliente al instante.
|
|
|
|
### 2. Automatización WhatsApp (CallBell)
|
|
|
|
- **Notificaciones Dinámicas**: Envío automático de facturas, recordatorios de pago y avisos de corte.
|
|
- **Re-envío Manual**: Herramienta para disparar notificaciones específicas desde el Dashboard si el proceso automático falla.
|
|
- **Sincronización Total**: Mantiene los contactos de CallBell siempre actualizados con los datos del CRM.
|
|
|
|
### 3. Coordinación Técnica (Jobs/Tasks)
|
|
|
|
- **Agenda Inteligente**: Notifica a instaladores sobre nuevas tareas y reprogramaciones.
|
|
- **Datos para Técnicos**: Envía coordenadas GPS y contraseñas de equipos (formato impresora térmica) directamente al WhatsApp del técnico.
|
|
|
|
---
|
|
|
|
## 🏗️ Arquitectura del Sistema
|
|
|
|
El plugin utiliza una arquitectura modular basada en **Facades** y **Servicios** para garantizar estabilidad y escalabilidad.
|
|
|
|
### Componentes Clave
|
|
|
|
- **Frontend (`public.php`)**: Una Single Page Application (SPA) ligera incrustada en UCRM, construida con Vanilla JS y CSS moderno (Variables, Flexbox/Grid).
|
|
- **Despachador (`Plugin.php`)**: Router de eventos que delega acciones a los controladores específicos.
|
|
- **Motor de Pagos (`PaymentIntentStripe`)**: Servicio robusto que se comunica con la API de Stripe para crear intenciones de pago y métodos.
|
|
- **Generador OXXO (`AbstractOxxoOperationsFacade`)**: Orquesta el flujo complejo: Stripe -> Puppeteer (Screenshot) -> FTP/Local Storage -> Respuesta JSON.
|
|
|
|
---
|
|
|
|
## 🛠️ Requisitos e Integraciones
|
|
|
|
Para desbloquear todo el potencial, el plugin requiere:
|
|
|
|
1. **UISP/UCRM**: Versión 2.1.0 o superior.
|
|
2. **Stripe API**: Keys de producción/test para procesar pagos.
|
|
3. **CallBell API**: Token para el envío de mensajes de WhatsApp.
|
|
4. **Microservicio Puppeteer**: Contenedor Docker para renderizar los vouchers de OXXO a imagen.
|
|
5. **Servidor FTP (Opcional)**: Requerido solo si se desea generar URLs públicas para compartir los vouchers externamente.
|
|
|
|
---
|
|
|
|
## 🏷️ Configuración Rápida
|
|
|
|
El plugin se configura directamente desde el panel de UCRM (`Ajustes -> Plugins -> siip-whatsapp-notifications`).
|
|
|
|
### Parámetros Críticos
|
|
|
|
- `ipserver`: Tu dominio UCRM.
|
|
- `tokenstripe`: Tu Secret Key de Stripe.
|
|
- `tokencallbell`: Tu API Key de CallBell.
|
|
- `hostServerFTP` / `user` / `pass`: Credenciales para el almacenamiento de vouchers remotos.
|
|
|
|
---
|
|
|
|
## 📝 Registro de Cambios
|
|
|
|
Para consultar la evolución detallada del proyecto, ver el archivo [CHANGELOG.md](./CHANGELOG.md).
|