DANYDHSV/siip-whatsapp-notifications-callbell_sync-stripe_payments
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
e1937f9ac3
siip-whatsapp-notifications.../README.md
DANYDHSV f851ea6d7d feat: soporte multi-servicio, optimización lazy loading y sincronización avanzada con CallBell 
- 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.
2026-01-03 11:07:29 -06:00

4.5 KiB
Executable File
Raw Blame History

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.