siip-whatsapp-notifications-callbell_sync-stripe_payments/PLUGIN_INDEX.md

PLUGIN_INDEX.md — Índice Maestro

Plugin: siip-whatsapp-notifications | Versión actual: ver manifest.json Este archivo es el punto de entrada para cualquier agente IA que trabaje en este plugin.

---

🧭 Guía rápida: ¿Qué índice leer?

Tarea	Índices a leer	Tokens est.
Modificar lógica de hooks UCRM	INDEX_plugin.md + INDEX_deps.md	~4,500
Agregar/modificar endpoint en el portal web	INDEX_public.md	~3,000
Modificar módulo Stripe del portal	INDEX_public.md + leer views/stripe.php directamente	~3,500
Modificar módulo OXXO del portal	INDEX_public.md + leer views/oxxo.php directamente	~3,500
Nueva feature que usa API UCRM	INDEX_api_used.md + INDEX_api_ucrm.md	~3,500
Nueva feature que usa API UNMS	INDEX_api_used.md + INDEX_api_unms.md	~5,000
Bug en llamada API existente	INDEX_api_used.md solo	~1,500
Modificar notificaciones WhatsApp	INDEX_deps.md (sección Facades)	~2,000
Cambiar flujo de pago OXXO/Stripe	INDEX_plugin.md + INDEX_deps.md	~4,500

⚡ Tip: Después de leer el índice correspondiente, usa StartLine/EndLine para leer solo el fragmento del archivo fuente que necesitas modificar, en lugar de leer el archivo completo.

---

📁 Estructura del Plugin

siip-whatsapp-notifications/
│
├── 📄 public.php          (2978 líneas) — Portal web + endpoint HTTP público
├── 📄 src/Plugin.php      (672 líneas)  — Entry point de hooks UCRM
│
├── src/
│   ├── Facade/
│   │   ├── AbstractMessageNotifierFacade.php  — Base notificaciones WhatsApp
│   │   ├── AbstractStripeOperationsFacade.php — Lógica Stripe + registro pagos UCRM
│   │   ├── AbstractOxxoOperationsFacade.php   — Lógica OXXO Pay + vouchers
│   │   ├── PluginNotifierFacade.php           — Facade principal (extiende Stripe)
│   │   ├── PluginOxxoNotifierFacade.php       — Facade OXXO
│   │   ├── TwilioNotifierFacade.php           — Legacy Twilio
│   │   └── ClientCallBellAPI.php              — Cliente Callbell (81KB)
│   │
│   ├── Service/
│   │   ├── PaymentIntentService.php   — Stripe SDK: PIs, historial, balance
│   │   ├── SmsNumberProvider.php      — Extrae teléfonos WhatsApp de contactos UCRM
│   │   ├── Logger.php                 — PSR-3 logger
│   │   ├── OptionsManager.php         — Carga config → PluginData
│   │   ├── MinioStorageService.php    — Sube vouchers a MinIO
│   │   ├── CurlExecutor.php           — Wrapper cURL
│   │   └── PluginDataValidator.php    — Valida configuración
│   │
│   ├── Data/
│   │   ├── PluginData.php             — DTO config del plugin
│   │   ├── NotificationData.php       — DTO payload webhook UCRM
│   │   └── UcrmData.php               — Base DTO
│   │
│   └── Factory/
│       ├── NotificationDataFactory.php — Construye NotificationData desde JSON
│       └── MessageTextFactory.php      — Genera textos de mensajes WhatsApp
│
├── views/
│   ├── stripe.php   (17KB) — HTML+JS del módulo Stripe del portal
│   └── oxxo.php     (12KB) — HTML+JS del módulo OXXO del portal
│
├── scripts-uisp/    — Scripts auxiliares UNMS (audit_client_passwords.php, etc.)
├── data/            — config.json, logs, ordenes OXXO
├── vendor/          — Dependencias Composer
├── img/             — Imágenes del portal (logos, íconos)
└── vouchers_oxxo/   — Vouchers OXXO generados

---

📚 Archivos de Índice

Archivo	Describe	Tamaño
INDEX_plugin.md	src/Plugin.php: flujos, eventos UCRM, UUIDs de métodos de pago	~5KB
INDEX_public.md	public.php: todos los endpoints, acciones JS, módulos UI	~6KB
INDEX_deps.md	Facades y Services: firmas de métodos y propósito	~7KB
INDEX_api_used.md	Todas las llamadas API reales que hace el plugin	~4KB
INDEX_api_ucrm.md	Catálogo de 162 endpoints UCRM CRM v1.0	~10KB
INDEX_api_unms.md	Catálogo de 560 endpoints UNMS NMS v2.1	~74KB

---

🔧 Scripts de utilidad

Script	Uso
.agent/scripts/gen_index_unms_swagger.php	php gen_index_unms_swagger.php — regenera INDEX_api_unms.md desde unms-swagger.json
.agent/scripts/gen_index_ucrm_apib.php	php gen_index_ucrm_apib.php — regenera INDEX_api_ucrm.md desde unmscrm.apib

---

⚙️ Configuración del Plugin (claves en data/config.json)

Clave	Tipo	Descripción
ipserver	string	IP/hostname del servidor UISP
apitoken	string	Token API UCRM
unmsApiToken	string	Token API UNMS/NMS
tokencallbell	string	Token API Callbell
tokenstripe	string	API Key Stripe
ipPuppeteer	string	IP microservicio Puppeteer para vouchers
portPuppeteer	string	Puerto microservicio Puppeteer
idPaymentAdminCRM	string	ID admin UCRM para registrar pagos
installersDataWhatsApp	JSON string	{"instaladores":[{id, nombre, whatsapp}]}
notificationTypeText	bool	true=texto plano, false=plantilla Callbell
debugMode	bool	Activa logging DEBUG
cashPaymentMethodId	bool	Habilitar notif. efectivo
bankTransferPaymentMethodId	bool	Habilitar notif. transferencia bancaria
oxxoPayPaymentMethodId	bool	Habilitar notif. OXXO
creditCardStripePaymentMethodId	bool	Habilitar notif. tarjeta Stripe
(más métodos de pago)	bool	Ver PluginData.php para lista completa

---

🔄 Flujos principales resumidos

Flujo: Pago registrado en UCRM

UCRM → POST public.php (uuid presente) → Plugin::run() → processHttpRequest()
→ NotificationDataFactory::getObject() → event: payment.add
→ switch(methodId) → notifierFacade::verifyPaymentActionToDo()
→ SmsNumberProvider::getUcrmClientNumbers() → ClientCallBellAPI::sendPaymentNotificationWhatsApp()

Flujo: Transferencia bancaria Stripe (SPEI)

Stripe → POST public.php (type: customer_cash_balance_transaction.created → funded)
→ Plugin::run() → pluginNotifierFacade::createPaymentIntent()
→ AbstractStripeOperationsFacade: crea PI en Stripe + registra pago en UCRM

Flujo: Solicitud OXXO Pay

Bot/Cliente → POST public.php (type: oxxo.request)
→ Plugin::run() → pluginOxxoNotifierFacade::createStripeReference()
→ createOxxoOrder() → responde inmediatamente → fastcgi_finish_request()
→ [background] generateOxxoVoucher() → Puppeteer → MinIO

Flujo: Tarea de Instalador

UCRM → POST public.php (uuid, event: job.edit, status 0→1)
→ notifierFacade::verifyJobActionToDo()
→ ClientCallBellAPI: notifica cliente + técnico vía WhatsApp
→ PATCH job title en UCRM (remueve/actualiza prefijo [NOTIFICACION-PENDIENTE])

Flujo: Obtener Password Antena

UCRM client.edit + tag "OBTENER PASSWORD ANTENA" agregado
→ Plugin::processHttpRequest() → pluginNotifierFacade::processClientPasswordAntenna()
→ AbstractMessageNotifierFacade::getVaultCredentialsByClientId()
→ UNMS GET devices?siteId → GET vault/{id}/credentials
→ UCRM PATCH clients/{id} (atributo passwordAntenaCliente)
→ removeTagFromClient("OBTENER PASSWORD ANTENA")