73 lines
3.9 KiB
Markdown
Executable File
73 lines
3.9 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
|
|
|
|
### 📅 Notificación de Visitas Técnicas
|
|
Cuando se asigna o reprograma una tarea:
|
|
1. El plugin detecta el cambio en el `assignedUserId` o la fecha.
|
|
2. Envía un mensaje al cliente con el nombre del técnico y la fecha (sin hora, por privacidad/logística).
|
|
3. Envía un mensaje al técnico con la dirección, ubicación en Google Maps y la contraseña de la antena obtenida de la bóveda de UISP.
|
|
|
|
### 💳 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). |