DANYDHSV
761cd667b5
- Implementado soporte multi-servicio para antenas con formato "Servicio X: <pass>". - Añadido sistema de "Lazy Check" para evitar llamadas redundantes a la API de UISP si ya existe una contraseña válida. - Refinado algoritmo de generación de contraseñas: ahora son "Printer-Friendly" (alfanumérico + @, #) y sin caracteres ambiguos. - Mejorada la lógica de detección de antenas: validación por etapas (Servicio -> Sitio -> Dispositivo) para evitar errores en sitios inactivas. - Agregados mensajes informativos de estado en el CRM (⚠️ Sin sitio, ⚠️ Sin antena). - Corregido bucle infinito de webhooks en entornos de prueba mediante validación de idempotencia. - Actualizada documentación (README.md y CHANGELOG.md) a la versión 3.0.0.
76 lines
4.3 KiB
Markdown
Executable File
76 lines
4.3 KiB
Markdown
Executable File
# SIIP - WhatsApp Notifications & Stripe Payments for UCRM
|
|
|
|
Este plugin es una solución integral para automatizar la comunicación con clientes y la gestión de pagos en UISP/UCRM. Actúa como puente entre el CRM, Stripe y la plataforma de mensajería CallBell.
|
|
|
|
## 🚀 Funcionalidades Principales
|
|
|
|
- **Notificaciones Dinámicas**: Envío automático de mensajes por WhatsApp para facturas, pagos, suspensiones y reactivaciones.
|
|
- **Gestión de Agenda (Jobs/Tasks)**: Notificación inteligente a técnicos e instaladores sobre nuevas tareas, reprogramaciones y desasignaciones.
|
|
- **Pagos con Stripe & OXXO**: Generación automatizada de referencias de OXXO con captura de pantalla (Puppeteer) y alojamiento en la nube (WordPress).
|
|
- **Sincronización CallBell**: Mantenimiento de la información del cliente actualizada en la plataforma de chat CallBell.
|
|
- **Resolución Dinámica**: Detección automática de métodos de pago y atributos personalizados para máxima portabilidad.
|
|
|
|
---
|
|
|
|
## 🏗️ Arquitectura del Sistema
|
|
|
|
El plugin utiliza un patrón de diseño basado en **Facades** para desacoplar la lógica de despacho de los servicios externos.
|
|
|
|
### Componentes Clave
|
|
|
|
- **Despachador Central (`Plugin.php`)**: Gestiona tanto los webhooks internos de UCRM como los externos (Stripe). Controla el estado de las notificaciones de tareas mediante prefijos en los títulos (`[NOTIFICACION-PENDIENTE]`).
|
|
- **Fachada de Mensajería (`AbstractMessageNotifierFacade`)**: Contiene la lógica de negocio para decidir qué notificar, cuándo y a quién.
|
|
- **Interfaz CallBell (`ClientCallBellAPI`)**: Encapsula las llamadas a la API de CallBell, manejando plantillas y mensajes multimedia.
|
|
- **Operaciones OXXO (`AbstractOxxoOperationsFacade`)**: Orquesta el flujo de pago: Stripe (Referencia) -> Puppeteer (Screenshot) -> WordPress (Hosting) -> CallBell (WhatsApp).
|
|
|
|
---
|
|
|
|
## 🛠️ Requisitos e Integraciones
|
|
|
|
Para un funcionamiento óptimo, el plugin requiere:
|
|
|
|
1. **UISP/UCRM**: Versión compatible con el SDK de Ubiquiti.
|
|
2. **Stripe API**: Token y Webhooks configurados para transacciones en tiempo real.
|
|
3. **CallBell API**: Token de acceso para el envío de mensajes a través de plantillas de WhatsApp.
|
|
4. **Microservicio Puppeteer**: Un contenedor Docker con la API de Puppeteer para capturar vouchers.
|
|
5. **Hosting WordPress (FTP)**: Para alojar temporalmente las imágenes de los vouchers enviadas a los clientes.
|
|
|
|
---
|
|
|
|
## 🏷️ Configuración de UCRM
|
|
|
|
### Contactos y Etiquetas
|
|
El plugin selecciona los números de destino basándose en el **Tipo de Contacto** definido en UCRM:
|
|
- `WhatsApp`: Recibe notificaciones y actualizaciones de datos.
|
|
- `WhatsNotifica`: Recibe solo notificaciones.
|
|
- `WhatsActualiza`: Utilizado solo para sincronizar datos con CallBell.
|
|
|
|
### Atributos Personalizados
|
|
Es necesario configurar los siguientes atributos en UCRM:
|
|
- `stripeCustomerId`: ID del cliente en Stripe.
|
|
- `clabeInterbancaria`: CLABE personalizada para transferencias.
|
|
- `passwordAntenaCliente`: Almacena la contraseña del equipo del cliente (sincronizada con la bóveda).
|
|
|
|
---
|
|
|
|
## 🔄 Flujos de Trabajo Destacados
|
|
|
|
### 📅 Gestión de Contraseñas y Visitas Técnicas
|
|
Cuando se asigna o reprograma una tarea:
|
|
1. **Detección Multi-Servicio**: El plugin identifica todos los servicios del cliente y formatea sus contraseñas como `Servicio 1: <pass> Servicio 2: ...`.
|
|
2. **Validación de Provisionamiento**: Antes de actuar, verifica en UISP si el sitio tiene dispositivos vinculados (evitando errores en estados "Location Inactive").
|
|
3. **Lazy Loading**: Si el CRM ya tiene una contraseña válida, el plugin omite llamadas redundantes a la API para ahorrar recursos.
|
|
4. **Notificación**:
|
|
- Envía un mensaje al cliente con el nombre del técnico y la fecha (sin hora).
|
|
- Envía un mensaje al técnico con la dirección, ubicación en Google Maps y las contraseñas de las antenas optimizadas para lectura en impresoras térmicas (alfanumérico + `@`, `#`).
|
|
|
|
### 💳 Registro de Pagos por Transferencia
|
|
1. Stripe envía un webhook de saldo aplicado (`customer_cash_balance_transaction.created`).
|
|
2. El plugin resuelve dinámicamente el ID del método "Transferencia bancaria".
|
|
3. Registra el pago automáticamente en UCRM vinculado al `clientId` en los metadatos.
|
|
|
|
---
|
|
|
|
## 📝 Registro de Cambios
|
|
|
|
Para consultar la evolución del proyecto, ver el archivo [CHANGELOG.md](./CHANGELOG.md). |