DANYDHSV
f851ea6d7d
- Implementación de gestión multi-servicio para contraseñas de antena con etiquetas condicionales. - Optimización de rendimiento mediante lazy loading para evitar llamadas redundantes a la API de UISP. - Mejora de sincronización con CallBell: contraseñas en formato JSON, unificación de peticiones PATCH y corrección de comparación de saldo. - Generación de contraseñas printer-friendly (alfanuméricas + @, #) sin caracteres ambiguos. - Validación granular de provisionamiento para evitar errores en sitios inactivos. - Actualización de CHANGELOG.md y README.md.
80 lines
4.5 KiB
Markdown
Executable File
80 lines
4.5 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 & Etiquetas Inteligentes**:
|
|
- El plugin identifica todos los servicios del cliente.
|
|
- Si hay **más de un servicio**, utiliza el formato: `Servicio 1: <pass> Servicio 2: ...`.
|
|
- Si hay **solo un servicio**, muestra la contraseña directamente sin etiquetas para mayor claridad.
|
|
2. **Sincronización CallBell Avanzada**:
|
|
- Los datos técnicos y financieros se sincronizan en una sola petición optimizada.
|
|
- Las contraseñas se envían como un objeto JSON estructurado al campo `Password Antena`.
|
|
3. **Validación de Provisionamiento**: Antes de actuar, verifica en UISP si el sitio tiene dispositivos vinculados (evitando errores en estados "Location Inactive").
|
|
- 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). |