Notificaciones
El sistema de notificaciones envía alertas a los usuarios a través de múltiples canales cuando ocurren eventos relevantes en la plataforma.
Canales soportados
| Canal | Cómo llega al usuario |
|---|---|
| In-app | Aparece en el panel de la aplicación |
| Se envía al correo del usuario de forma asíncrona | |
| Webhook | Se hace un POST a una URL configurada por el tenant |
| Web push | Notification API del navegador (suscripción Web Push registrada) |
| Push nativo | iOS / Android vía token de dispositivo (FCM) |
Cada canal puede activarse o desactivarse por usuario y tipo de notificación.
Tipos de notificación
| Tipo | Cuándo se dispara |
|---|---|
USER_CREATED | Al crear una cuenta nueva |
USER_INVITED | Al recibir una invitación a una empresa |
USER_INVITATION_ACCEPTED | Al aceptar una invitación |
ROLE_CHANGED | Al cambiar el rol de un usuario |
EXPORT_READY | Al completar una exportación |
PAYMENT_FAILED | Al fallar un cobro de la suscripción |
SUBSCRIPTION_CHANGED | Al cancelarse o modificarse una suscripción |
INVOICE_AVAILABLE | Al generarse una nueva factura |
TRIAL_ENDING | Cuando el período de prueba está por vencer |
FEEDBACK_RECEIVED | Al recibirse feedback nuevo desde el widget de beta testers — se notifica in-app a todos los super administradores de la plataforma |
CUSTOM | Contenido libre compuesto vía POST /notifications/send. No es un tipo de catálogo tipado en la API. |
API — Envío compuesto
OWNER/ADMIN (JWT + empresa activa) o clave secreta del tenant (sk_ con rol OWNER/ADMIN) pueden enviar notificaciones inmediatas.
POST /notifications/send
Authorization: Bearer <token> # o X-API-Key: sk_…
X-Company-Id: <companyId>
Content-Type: application/jsonModos de destinatarios
mode | Comportamiento |
|---|---|
broadcast | Todos los miembros actuales de la empresa |
users | Lista cerrada en userIds (obligatoria, no vacía). Ids inválidos o de otro tenant se omiten sin informe de fallidos |
Contenido (excluyentes):
- Libre:
{ "title", "body", "destination?" }— límites: título 255, cuerpo 10000, destino 2048. Omitirdestinationes válido; si se incluye, debe ser una ruta interna no vacía que empiece por/.null, vacío, esquemasjavascript:/http(s)://y URLs protocol-relative//→ 400. - Plantilla:
{ "type", "payload" }— tipos del catálogo (noCUSTOM). El API exige quepayloadincluya todos losrequiredFieldsde la plantilla; claves ausentes o en blanco → 400
Canales (opcional):
channels: lista dein_app|email|webhook|web_push|native_push- Omitido o
[]→ default["in_app"] - Entrega = intersección con preferencias / dispositivos / webhook del destinatario
- Push nativo sin app client vinculada a la empresa → se omite e informa en
omissions(no_app_client_linked) - App vinculada pero ningún destinatario con dispositivo nativo →
omissionsconno_recipient_devices
Respuesta: 202 Accepted con:
{
"accepted": true,
"channels": ["in_app"],
"omissions": []
}Sin estado de entrega por destinatario (send-and-forget). MEMBER → 403.
Ejemplo broadcast libre:
{
"mode": "broadcast",
"title": "Aviso de la empresa",
"body": "Mañana hay all-hands",
"destination": "/announcements"
}Ejemplo multi-canal:
{
"mode": "users",
"userIds": ["uuid-miembro"],
"title": "Ping",
"body": "Hola",
"channels": ["in_app", "email", "native_push"]
}Ejemplo lista + plantilla:
{
"mode": "users",
"userIds": ["uuid-miembro"],
"type": "EXPORT_READY",
"payload": {}
}La entrega reutiliza NotificationsService.notify() restringido a los canales elegidos (preferencias + plantillas). IN_APP con canal en vivo aplica SSE. Sin dispositivo push registrado, ese canal se omite sin fallar el envío.
Cada envío inmediato también deja una fila en el outbox (notification_composed_sends, estado executed) con los canales solicitados.
API — Dispositivos push
Cualquier usuario autenticado puede registrar y dar de baja endpoints de push asociados a su cuenta (y empresa activa).
POST /notifications/devices
Authorization: Bearer <token>
X-Company-Id: <companyId>
Content-Type: application/json
{
"platform": "web",
"endpoint": "https://fcm.googleapis.com/fcm/send/…",
"keys": { "p256dh": "…", "auth": "…" }
}platform | Body |
|---|---|
web | endpoint (URL de suscripción) + keys.p256dh + keys.auth |
ios / android | endpoint = token FCM/dispositivo |
También: GET /notifications/devices (lista propia) y DELETE /notifications/devices/:deviceId (baja).
Configuración del host (VAPID / FCM): ver documentación de arquitectura de notificaciones.
API — Envíos programados e historial
Misma autorización que el envío inmediato (OWNER/ADMIN JWT o sk_ OWNER/ADMIN).
Programar
POST /notifications/schedule
Authorization: Bearer <token>
X-Company-Id: <companyId>
Content-Type: application/json
{
"mode": "broadcast",
"title": "Aviso",
"body": "Mañana",
"scheduledAt": "2030-01-15T10:00:00.000Z"
}scheduledAt debe ser un instante futuro (UTC); si no → 400. destination sigue las mismas reglas del envío inmediato: omitirlo es válido; null, vacío, esquemas inseguros y URLs protocol-relative → 400. Respuesta 201 con la fila outbox (status: scheduled). Si la entrega falla, se reintenta hasta 3 veces; después queda failed con failedAt y lastError, y se notifica al actor que la programó.
Cuando llega el instante, un poller in-process (~10s) reclama filas vencidas y las ejecuta con el mismo pipeline que el envío inmediato. No requiere Redis.
Listar / cancelar pendientes
GET /notifications/scheduled?page=1&limit=20
POST /notifications/scheduled/:id/cancelPor defecto OWNER/ADMIN/sk_ ven los pendientes del tenant; ?own=true limita al actor. Cancelar después de ejecutar → 409 y no revierte entregas.
Historial propio vs listado global del tenant
| Endpoint | Qué lista | Quién |
|---|---|---|
GET /notifications/sends | Outbox de envíos originados por el actor (inmediato + programado): id, mode, contenido/plantilla, canales solicitados, status, timestamps; los fallidos incluyen failedAt y lastError | OWNER/ADMIN/sk_ |
GET /notifications/tenant | Todas las notificaciones in-app del tenant (sistema + manuales) | OWNER/ADMIN/sk_; MEMBER → 403 |
El historial nunca cambia si se edita o borra una plantilla: tanto el outbox (/notifications/sends) como las notificaciones in-app (/notifications y /notifications/tenant) guardan lo que se envió/renderizó en el momento del envío — nunca una referencia viva a una fila de notification_templates. Editar o eliminar una plantilla de sistema o propia después de un envío no altera ni invalida ese historial.
API — Notificaciones in-app
Las notificaciones in-app se consultan y marcan como leídas a través de la API.
Listar notificaciones
GET /notifications?page=1&limit=20
Authorization: Bearer <token>
X-Company-Id: <companyId>Parámetro opcional ?unread=true para ver solo las no leídas.
Paginación — page (default 1) y limit (default 20, máximo 100) son opcionales. Una página fuera de rango no es un error: devuelve data: [] con total reflejando el conteo real.
Respuesta:
{
"data": [
{
"id": "uuid",
"notificationType": "USER_INVITED",
"title": "You've been invited",
"body": "You've been invited to join as member.",
"metadata": { "role": "member" },
"destination": null,
"readAt": null,
"createdAt": "2024-01-01T10:00:00Z"
}
],
"total": 1,
"page": 1,
"limit": 20
}destination es una ruta interna opcional de navegación para el host; en envío libre debe empezar por / y no admite esquemas ni URLs //. Viene de metadata.destination; las notificaciones legacy sin destino devuelven null.
Canal en vivo (SSE) —
Canal aditivo al listado REST: el SDK/host se suscribe para recibir notificaciones in-app en tiempo real.
- Obtener ticket (JWT de sesión + empresa activa):
POST /notifications/realtime/ticket
Authorization: Bearer <token>
X-Company-Id: <companyId>Respuesta: { "ticket": "...", "expiresIn": 45 } (~45s, un solo uso).
- Abrir el stream (EventSource no puede enviar Bearer):
GET /notifications/stream?ticket=<ticket>
Accept: text/event-streamEventos notification con: id, title, body, type, destination, read, createdAt, unreadCount.
Al cambiar de empresa hace falta un ticket nuevo. El fan-out es in-process (una sola instancia); multi-instancia requerirá pub/sub más adelante.
Marcar una notificación como leída
POST /notifications/:id/read
Authorization: Bearer <token>Devuelve la notificación actualizada con readAt establecido. Si la notificación no pertenece al usuario o al tenant activo, devuelve 403.
Marcar todas como leídas
POST /notifications/read-all
Authorization: Bearer <token>
X-Company-Id: <companyId>Devuelve 204 sin cuerpo.
Email y webhook
Las notificaciones por email y webhook se envían de forma asíncrona en background. El usuario no espera a que se envíen — la request HTTP no se bloquea.
El email usa el transportador configurado en MAILER_TRANSPORT. En modo log no se entrega el correo: primero se aplica la resolución SMTP de y luego solo se registran metadatos seguros, sin destinatario, asunto ni contenido. Si no hay un provider o fallback SMTP usable, la resolución falla.
El webhook hace un POST a la URL configurada en la setting webhook.url. Si no está configurada, el webhook se omite silenciosamente.
Para configurar el webhook:
PUT /settings/webhook.url
{ "value": "https://mi-servidor.com/webhook" }Plantillas de sistema gestionables
Además del catálogo fijo de tipos anterior, un SUPER_ADMIN de la plataforma puede administrar un catálogo de plantillas de notificación con nombre, campos de datos requeridos y contenido (título/cuerpo, con placeholders ). Los diez tipos del catálogo fijo se migran automáticamente a este catálogo (por code, ej. USER_CREATED), sin afectar el envío automático existente. Eliminar una plantilla es un borrado lógico (deleted_at): deja de aparecer en el listado/picker y el seed de arranque no la vuelve a crear.
Endpoints (solo SUPER_ADMIN de la plataforma)
| Método | Ruta | Descripción |
|---|---|---|
GET | /notifications/templates | Listar el catálogo de plantillas de sistema (companyId nulo) |
GET | /notifications/templates/:id | Obtener una plantilla de sistema por id — 404 si el id es de una plantilla propia de empresa |
POST | /notifications/templates | Crear una plantilla de sistema |
PATCH | /notifications/templates/:id | Editar una plantilla de sistema — no afecta notificaciones ya enviadas; 404 si el id es de empresa |
DELETE | /notifications/templates/:id | Eliminar una plantilla de sistema — no afecta notificaciones ya enviadas; 404 si el id es de empresa |
Intentar leer, editar o borrar por id una plantilla propia de empresa a través de estas rutas de sistema responde 404 (no 403): el CRUD de SUPER_ADMIN solo alcanza filas con companyId nulo.
En el SDK TypeScript, el CRUD global está separado en client.systemNotificationTemplates y solo se expone en Browser con JWT Super Admin. El claim se comprueba localmente para mejorar el feedback; el servidor vuelve a autorizar cada operación. El CRUD tenant sigue en client.notifications (listTemplates, getTemplate, createTemplate, updateTemplate, deleteTemplate) y requiere OWNER/ADMIN de la empresa activa en Browser.
Ejemplo de creación:
POST /notifications/templates
Authorization: Bearer <token super admin>
{
"name": "Bienvenida personalizada",
"description": "Plantilla de bienvenida con tono corporativo",
"requiredFields": ["name"],
"content": {
"title": "¡Bienvenido!",
"body": "Hola {{name}}, tu cuenta ya está lista.",
"subject": "Bienvenido a bordo"
}
}Esta gestión es independiente de la elección de plantilla en el compositor de envío manual. Enviar directamente desde una fila de este catálogo queda como una iteración aparte; hoy type solo acepta el catálogo fijo de NotificationType.
Listado unificado para el compositor de envío
Un OWNER o ADMIN de la empresa activa puede listar en una sola llamada el catálogo de sistema junto con las plantillas propias de su empresa — pensado para poblar el selector de plantilla del compositor de envío manual.
| Método | Ruta | Descripción |
|---|---|---|
GET | /notifications/templates/available | Listado unificado: catálogo de sistema + plantillas propias de la empresa activa (OWNER/ADMIN) |
GET /notifications/templates/available
Authorization: Bearer <token owner/admin>
X-Company-Id: <company-uuid>Nunca incluye las plantillas propias de otra empresa (aislamiento por tenant). Si no hay empresa activa seleccionada responde 400.
Plantillas propias por empresa
Además del catálogo de sistema, cualquier OWNER o ADMIN de una empresa puede crear sus propias plantillas — con el mismo formato (nombre, campos requeridos, contenido con placeholders) — para uso exclusivo de esa empresa. Están completamente aisladas por tenant: una empresa nunca ve, edita ni borra las plantillas propias de otra.
Endpoints (OWNER/ADMIN de la empresa activa)
| Método | Ruta | Descripción |
|---|---|---|
GET | /notifications/company-templates | Listar las plantillas propias de la empresa activa |
GET | /notifications/company-templates/:id | Obtener una plantilla propia por id (404 si es de otra empresa) |
POST | /notifications/company-templates | Crear una plantilla propia para la empresa activa |
PATCH | /notifications/company-templates/:id | Editar una plantilla propia — no afecta notificaciones ya enviadas con la versión anterior |
DELETE | /notifications/company-templates/:id | Eliminar una plantilla propia — no afecta notificaciones ya enviadas |
Ejemplo de creación:
POST /notifications/company-templates
Authorization: Bearer <token owner/admin>
{
"name": "Confirmación de pedido",
"requiredFields": ["orderId"],
"content": {
"title": "Pedido confirmado",
"body": "Tu pedido {{orderId}} fue confirmado."
}
}Intentar leer, editar o borrar una plantilla propia de otra empresa responde 404 (no 403), para no confirmar ni negar la existencia de ese id a un tenant ajeno. Un OWNER y un ADMIN de la misma empresa tienen exactamente los mismos permisos sobre sus plantillas propias — no hay jerarquía entre ambos roles en esta iteración.
El CRUD tenant también está disponible en los SDK de servidor y navegador, separado del catálogo global de sistema.
Preferencias
Por defecto todas las notificaciones están activadas. Un usuario puede desactivar un tipo o canal específico — esto se almacena en notification_preferences.
| Método | Ruta | Descripción |
|---|---|---|
GET | /notifications/preferences | Lista las preferencias explícitas del usuario autenticado en la empresa activa |
PUT | /notifications/preferences | Activa/desactiva un par tipo+canal ({ type, channel, enabled }). Tipo o canal inválido → 400. El userId sale de la sesión, nunca del body |
PUT /notifications/preferences
Authorization: Bearer <token>
X-Company-Id: <companyId>
Content-Type: application/json
{
"type": "USER_INVITED",
"channel": "email",
"enabled": false
}Si no hay fila para un tipo/canal, el sistema asume enabled: true.
Multi-tenancy
Cada notificación está aislada por tenantId. Un usuario autenticado con la empresa A nunca ve notificaciones de la empresa B. La query siempre combina userId + tenantId.
Cómo se generan las notificaciones
Las notificaciones se crean automáticamente a partir de eventos del dominio:
UserInvitedEvent
↓ escucha NotificationEventListener
↓ NotificationsService.notify()
↓ para cada canal habilitado:
in-app → guarda en BD
email → job asíncrono → envío por correoNo necesitas llamar al servicio de notificaciones directamente. Los eventos del sistema lo hacen automáticamente.
El feedback de beta testers (widget flotante) es un caso especial: no pertenece a un tenant, así que en vez de notificar a los miembros de una empresa, se notifica a todos los super administradores de la plataforma cuando llega feedback nuevo:
FeedbackCreatedEvent ('feedback.created')
↓ escucha NotificationEventListener
↓ busca todos los usuarios con isSuperAdmin === true
↓ NotificationsService.notify() por cada super administrador
in-app → guarda en BD (tipo FEEDBACK_RECEIVED)Extensibilidad
Para añadir un nuevo canal (ej. push móvil, SMS):
- Implementar la interfaz
NotificationChannelService - Añadirlo como provider en
NotificationsModule - Registrar el canal en
NotificationsService.getChannelService()
Para añadir un nuevo tipo de notificación:
- Añadir el valor al enum
NotificationType - Añadir el renderer de canales en
template.registry.ts(matriz de canales + fallback) - Añadir la entrada en
system-catalog.seed.ts(contentcon— fuente de render en runtime) - Si se dispara por un evento, añadir el listener en
NotificationEventListener