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