imagy-notifications — Servicio de Notificaciones
Proposito
imagy-notifications es el servicio compartido de notificaciones de la plataforma Imagy. Centraliza el envio de mensajes a traves de multiples canales (SMS, Email, WhatsApp, Push, Webhook) para todos los dominios de la plataforma. Provee dos modos de operacion: sincronico para OTP (envio y verificacion) y asincronico para notificaciones basadas en eventos. Cada tenant configura sus canales disponibles, credenciales de proveedor y plantillas personalizadas.
Responsabilidades
| Responsabilidad | Descripcion |
|---|---|
| Envio multicanal | Despachar notificaciones por SMS, Email, WhatsApp, Push y Webhook |
| OTP | Generar, enviar y verificar codigos de un solo uso |
| Plantillas | Gestionar plantillas configurables por tenant con interpolacion de variables |
| Configuracion por tenant | Cada tenant define canales habilitados y credenciales de proveedor |
| Notificaciones por evento | Consumir eventos de otros dominios y disparar notificaciones automaticas |
| Envio masivo | Despachar notificaciones en lote (bulk) |
| Registro de envios | Almacenar log de cada notificacion enviada con estado y respuesta del proveedor |
| Localizacion | Soporte de plantillas en multiples idiomas (locale) |
Canales Soportados
| Canal | Proveedor(es) | Uso principal |
|---|---|---|
| SMS | Twilio, Amazon SNS | OTP, alertas de estado |
| Amazon SES | Verificacion de contacto, notificaciones de estado | |
| Meta Business API | Notificaciones interactivas, alertas | |
| Push | Firebase Cloud Messaging (FCM), APNs | Notificaciones en app movil |
| Webhook | HTTP callback | Integracion con sistemas externos del tenant |
Modos de Operacion
Sincronico (OTP)
Para operaciones que requieren respuesta inmediata. El servicio consumidor invoca via HTTP y espera la respuesta.
Asincronico (Event-Driven)
Para notificaciones que no requieren respuesta inmediata. El servicio publica un evento y imagy-notifications lo consume y despacha la notificacion correspondiente.
Modos de Envio
imagy-notifications soporta tres modos de envio para cubrir diferentes necesidades:
| Modo | Endpoint | Quien decide el canal | Cuando usar |
|---|---|---|---|
| Explicito | POST /send con channel: "sms" | El caller | OTP, envios puntuales, integraciones especificas |
| Multi-canal | POST /send con channel: ["sms", "email"] | El caller | Cuando se quiere enviar por canales especificos simultaneamente |
| Dispatch | POST /dispatch con subject_id | El servicio (automatico) | Notificaciones de negocio donde el servicio resuelve los canales disponibles |
Modo Explicito (canal unico)
El caller especifica exactamente: template + canal + destinatario + variables. Control total.
Modo Multi-Canal (canales explicitos)
El caller especifica un array de canales. El servicio busca la plantilla para cada canal y despacha a todos. Si un canal no tiene plantilla o no esta activo, se salta sin fallar.
Modo Dispatch (resolucion automatica)
El caller solo dice: template + subject_id + variables. El servicio:
- Busca los datos de contacto del sujeto (telefono, email, device tokens)
- Determina que canales estan activos para el tenant
- Verifica que exista plantilla para cada canal + locale
- Despacha por todos los canales que cumplan las condiciones
Este modo es ideal para notificaciones de negocio (credito aprobado, pago vencido, firma completada) donde el servicio consumidor no deberia preocuparse por los canales.
Sistema de Plantillas
Las plantillas permiten definir el contenido de cada notificacion de forma configurable por tenant, canal e idioma.
Estructura de una Plantilla
{
"code": "loan_approved",
"channel": "sms",
"locale": "es",
"subject": null,
"body": "Hola {{borrower_name}}, tu credito por {{amount}} ha sido aprobado. Ref: {{loan_id}}",
"variables": ["borrower_name", "amount", "loan_id"],
"tenant_id": "uuid-tenant-001"
}Interpolacion de Variables
El motor de plantillas reemplaza las variables delimitadas por con los valores proporcionados en el payload de envio. Si una variable requerida no se proporciona, el envio falla con error de validacion.
Jerarquia de Resolucion
- Plantilla especifica del tenant + canal + locale
- Plantilla especifica del tenant + canal + locale por defecto (
es) - Plantilla global del sistema (fallback)
Configuracion de Proveedores por Tenant
Cada tenant configura independientemente que canales tiene habilitados y con que credenciales de proveedor opera.
La tabla notification_channels almacena la configuracion de cada canal por tenant, incluyendo credenciales cifradas con KMS.
Integracion con Otros Dominios
imagy-notifications como proveedor de servicios
| Consumidor | Uso | Modo |
|---|---|---|
| ImagSign | Envio de OTP para firma electronica | Sincronico (HTTP) |
| ImagLend | Verificacion de contacto (OTP), alertas de estado de credito | Sincronico + Asincronico |
| ImagFlow | Notificaciones de paso completado, recordatorios | Asincronico (eventos) |
| ImagID | Verificacion de email/telefono | Sincronico (HTTP) |
imagy-notifications como consumidor de eventos
| Evento | Origen | Accion |
|---|---|---|
lend.loan.approved | ImagLend | Notificar al solicitante que su credito fue aprobado |
lend.loan.disbursed | ImagLend | Notificar desembolso exitoso |
lend.loan.rejected | ImagLend | Notificar rechazo con motivo |
lend.payment.reminder | ImagLend | Recordatorio de pago proximo |
lend.payment.overdue | ImagLend | Alerta de pago vencido |
flow.step.completed | ImagFlow | Notificar avance en el flujo |
flow.step.requires_action | ImagFlow | Notificar que se requiere accion del usuario |
flow.request.expired | ImagFlow | Notificar expiracion del flujo |
sign.signature.completed | ImagSign | Confirmar firma exitosa al firmante |
sign.signature.expired | ImagSign | Notificar que la solicitud de firma expiro |
id.verification.completed | ImagID | Confirmar verificacion de identidad |
Arquitectura Interna
Repositorio
- Repo:
imagy-notifications - Base de datos:
imagy_notifications - Puerto local: 4005
- Equipo: Team Platform
Documentos Relacionados
- Modelo de Datos — Tablas, plantillas, logs, OTP
- API Reference — Endpoints HTTP, ejemplos, webhook delivery