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

INDEX_deps.md — Facades y Services

Firmas y propósito de todas las dependencias usadas por public.php y Plugin.php

---

src/Facade/

AbstractMessageNotifierFacade (abstract) — L.1–537

src/Facade/AbstractMessageNotifierFacade.php Base de todas las facades. Maneja lógica de notificación via Callbell/WhatsApp.

Constantes:

• SUBJECT_OF_INSTALLER_CHANGE[] — textos para notificar cambio/desasignación de técnico
• ADDITIONAL_CHANGE_DATA[] — datos adicionales del cambio de técnico

Constructor: (Logger, MessageTextFactory, SmsNumberProvider) + carga $ucrmApi desde config

Métodos públicos:

Método	Descripción
verifyPaymentActionToDo(NotificationData): void	Itera teléfonos por tipo (whatsapp/whatsnotifica/whatsactualiza) y llama notify/update
verifyClientActionToDo(NotificationData): void	Solo onlyUpdate() para tipos whatsapp/whatsactualiza
verifyServiceActionToDo(NotificationData): void	onlyUpdateService() para tipos whatsapp/whatsactualiza
verifyJobActionToDo($jsonData, $reprog, $changeInstaller): void	Notifica instalador anterior, cliente y técnico nuevo; gestiona título del job
verifyInvoiceActionToDo(NotificationData): void	onlyUpdate() sin mostrar balance
notify(NotificationData, $phone): void	Envía notificación de pago vía Callbell (texto o plantilla)
notifyAndUpdate(NotificationData, $phone): void	Notifica + hace PATCH en Callbell
notifyOverDue(NotificationData): void	Notifica factura vencida/por vencer
onlyUpdate(NotificationData, $phone): void	Solo actualiza contacto en Callbell (sin enviar mensaje)
onlyUpdateService(NotificationData, $phone): void	Actualiza status de servicio en Callbell

Métodos protegidos:

Método	Descripción
getVaultCredentialsByClientId($clientId): string	Obtiene pass de antena desde UNMS vault; sincroniza en CRM. Usa GET /nms/api/v2.1/devices?siteId= y GET /nms/api/v2.1/vault/{deviceId}/credentials
syncPasswordWithCrm(int $clientId, string $pass): void	PATCH atributo passwordAntenaCliente en CRM si difiere
generateStrongPassword(int $length=16): string	Genera contraseña segura (lower+upper+digits+@#)
patchClientCustomAttribute(int $clientId, int $attributeId, string $value): bool	PATCH clients/{id} con atributo custom
comparePasswords(?string $crm, ?string $vault): string	Prioriza vault, luego crm, luego mensaje de advertencia
validarNumeroTelefono($n): string	Normaliza teléfono a formato internacional 521XXXXXXXXXX

Abstracto: sendWhatsApp(NotificationData, string $phone): void

---

PluginNotifierFacade extends AbstractStripeOperationsFacade

src/Facade/PluginNotifierFacade.php — L.1–152

Herencia: PluginNotifierFacade → AbstractStripeOperationsFacade → AbstractOxxoOperationsFacade → AbstractMessageNotifierFacade

Constructor: (Logger, MessageTextFactory, SmsNumberProvider, OptionsManager) — carga $pluginData

Métodos propios:

Método	Descripción
updatePasswordAntenaIfNeeded(int $clientId, array $jsonData): void	Llama getVaultCredentialsByClientId() — sincroniza pass antena
processClientPasswordAntenna(int $clientId, array $clientEntity): void	Procesa tag "OBTENER PASSWORD ANTENA": incluye scripts-uisp/audit_client_passwords.php, llama fixClientData(), remueve tag
sendWhatsApp(NotificationData, string $phone): void	Implementación mock (solo log)

Métodos heredados de AbstractStripeOperationsFacade (ver abajo):

• createPaymentIntent(), registerPaymentFromWebhook(), registerPaymentFromIntent()
• ensureStripePaymentAttribute(), createStripeClient(), syncStripeCustomerData()
• createClabeForClient(), removeTagFromClient()

---

AbstractStripeOperationsFacade (abstract)

src/Facade/AbstractStripeOperationsFacade.php — ~45KB

Hereda de AbstractOxxoOperationsFacade. Maneja toda la integración con Stripe y registro de pagos en UCRM.

Métodos clave (firmas aproximadas):

Método	Descripción
createPaymentIntent(array $jsonData): void	Crea PaymentIntent en Stripe desde webhook customer_cash_balance_transaction.funded
registerPaymentFromWebhook(array $jsonData): void	Registra pago en UCRM desde webhook applied_to_payment
registerPaymentFromIntent(array $piData): void	Registra pago en UCRM desde payment_intent.succeeded
ensureStripePaymentAttribute(NotificationData $n): void	Determina si el pago Stripe es OXXO, Transferencia o Tarjeta revisando metadata
createStripeClient(NotificationData $n, string $tag, bool $createClabe): void	Crea cliente en Stripe + opcionalmente genera CLABE
syncStripeCustomerData(int $clientId, string $name, ?string $email): void	Actualiza nombre/email del customer en Stripe
removeTagFromClient(int $clientId, string $tagName): void	Elimina tag del cliente en UCRM

---

AbstractOxxoOperationsFacade (abstract)

src/Facade/AbstractOxxoOperationsFacade.php — ~31KB

Maneja la integración OXXO Pay con Stripe y generación de vouchers.

Métodos clave:

Método	Descripción
createStripeReference(array $jsonData, ?float $amount): array	Crea PaymentIntent OXXO en Stripe. Retorna {hasError, data:{oxxo_reference, url, clientID, clientFullName, amount}}
createOxxoOrder(array $oxxoData): array	Guarda orden OXXO en storage local. Retorna {order_id, oxxo_reference, url, ...}
generateOxxoVoucher(array $responseOxxo, bool $background): void	Llama a Puppeteer para generar imagen del voucher y subirla a MinIO
getOxxoOrderStatus(string $orderId): array	Retorna estado actual de la orden OXXO
createOxxoPaymentIntent(array $clientData, float $amount, bool $notify): array	Flujo completo: crea PI Stripe OXXO + orden + voucher

---

PluginOxxoNotifierFacade extends AbstractOxxoOperationsFacade

src/Facade/PluginOxxoNotifierFacade.php — pequeño

Solo implementa los métodos abstractos. No agrega lógica propia relevante.

---

TwilioNotifierFacade extends AbstractMessageNotifierFacade

src/Facade/TwilioNotifierFacade.php — ~2KB

Implementa sendWhatsApp() usando Twilio (legacy, en desuso). Métodos notificación estándar delegados a la clase base.

---

ClientCallBellAPI

src/Facade/ClientCallBellAPI.php — ~81KB

Cliente completo de la API de Callbell. Usado internamente por las facades vía new ClientCallBellAPI($apitoken, $ipserver, $tokencallbell).

Métodos clave relevantes para el plugin:

Método	Descripción
sendPaymentNotificationWhatsApp($phone, NotificationData): bool	Envía plantilla de pago con template de Callbell
sendTextPaymentNotificationWhatsApp($phone, NotificationData): bool	Envía texto plano de pago
sendOverdueNotificationWhatsApp($phone, NotificationData): bool	Notificación de factura vencida
sendJobNotificationWhatsAppToClient($phone, array $data, $reprog, $changeInst): bool	Notificación de job al cliente
sendJobNotificationWhatsAppToInstaller($phone, array $data, $reprog, $changeInst): void	Notificación de job al técnico
getContactWhatsapp($phone): string	GET contacto en Callbell por teléfono → JSON
patchWhatsapp(array $contact, NotificationData): void	PATCH datos del contacto en Callbell
patchServiceStatusWhatsApp(array $contact, NotificationData): void	PATCH status de servicio en Callbell

---

src/Service/

PaymentIntentService

src/Service/PaymentIntentService.php — 282 líneas

Usado directamente en public.php (no via DI). Constructor: ($ucrmApi, $stripeApiKey, $logger=null)

Método	Descripción
searchClients($query): array	UCRM GET clients?query=q&limit=5 — retorna array simplificado
getClientDetails($clientId): array	UCRM GET clients/{id} — retorna datos + stripeCustomerId + clabeInterbancaria
createPaymentIntent($clientId, $amount, $stripeCustomerId, $adminId): array	Crea PI Stripe tipo customer_balance/bank_transfer/mx_bank_transfer
getLastPayments($stripeCustomerId, $limit=10): array	Stripe paymentIntents.all filtrado a bank_transfer — últimos N
getLastOxxoPayments($stripeCustomerId, $limit=5): array	Stripe paymentIntents.all filtrado a OXXO — últimos N
getCustomerCashBalance($stripeCustomerId): float	Stripe customers.retrieveCashBalance → MXN

---

SmsNumberProvider

src/Service/SmsNumberProvider.php — 160 líneas

Método	Descripción
getUcrmClientNumber(NotificationData): ?string	Primer contacto con tipo aplicable al evento
getUcrmClientNumbers(NotificationData?, array?): array	Retorna ['whatsapp'=>[phones], 'whatsnotifica'=>[phones], 'whatsactualiza'=>[phones]]
getAllUcrmClientNumbers(array): array	Todos los teléfonos del cliente sin filtrar por tipo

Tipos de contacto reconocidos:

• whatsapp — recibe notificación + actualización en Callbell
• whatsnotifica — solo recibe notificación (no actualiza Callbell)
• whatsactualiza — solo actualiza Callbell (no notifica)

---

Logger (src/Service/Logger.php)

Wrapper de PSR-3. Métodos: debug(), info(), warning(), error(). Nivel controlado por config logging_level / debugMode.

OptionsManager (src/Service/OptionsManager.php)

Carga config del plugin. Método: load(): PluginData

PluginDataValidator (src/Service/PluginDataValidator.php)

Valida que la configuración esté completa. Método: validate(): bool

MinioStorageService (src/Service/MinioStorageService.php)

Sube vouchers OXXO a MinIO. Usado por AbstractOxxoOperationsFacade.

CurlExecutor (src/Service/CurlExecutor.php)

Wrapper de cURL para la UcrmApi interna del plugin.

---

src/Data/

PluginData (extends UcrmData)

src/Data/PluginData.php — Propiedades de configuración del plugin:

Propiedad	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 del microservicio Puppeteer
$portPuppeteer	string	Puerto del microservicio Puppeteer
$idPaymentAdminCRM	string	ID admin para registrar pagos
$cashPaymentMethodId	bool	Habilitar notif. efectivo
$courtesyPaymentMethodId	bool	Habilitar notif. cortesía
$bankTransferPaymentMethodId	bool	Habilitar notif. transferencia
$oxxoPayPaymentMethodId	bool	Habilitar notif. OXXO
$creditCardStripePaymentMethodId	bool	Habilitar notif. tarjeta Stripe
$stripeSubscriptionCreditCardPaymentMethodId	bool	Habilitar notif. suscripción Stripe
$notificationTypeText	bool	true=texto plano, false=plantilla Callbell
$installersDataWhatsApp	string	JSON de instaladores
$debugMode	bool	Activa logging DEBUG
$logging_level	bool	Nivel verbose de log
$twilioAccountSid	string|null	Legacy Twilio
$twilioAuthToken	string|null	Legacy Twilio
$twilioSmsNumber	string|null	Legacy Twilio

NotificationData

src/Data/NotificationData.php DTO con propiedades: $uuid, $changeType, $entity, $entityId, $eventName, $clientId, $clientData[], $paymentData[], $invoiceData[]

---

src/Factory/

NotificationDataFactory

src/Factory/NotificationDataFactory.php — 5.8KB

Método	Descripción
getObject(array $jsonData): NotificationData	Construye NotificationData desde el payload del webhook UCRM, cargando datos adicionales de la API

MessageTextFactory

src/Factory/MessageTextFactory.php — 3.7KB Genera textos de mensajes WhatsApp. Usado por las facades para construir el contenido de notificaciones.