Skip to content

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 ​

CanalCómo llega al usuario
In-appAparece en el panel de la aplicación
EmailSe envía al correo del usuario de forma asíncrona
WebhookSe hace un POST a una URL configurada por el tenant
Web pushNotification API del navegador (suscripción Web Push registrada)
Push nativoiOS / Android vía token de dispositivo (FCM)

Cada canal puede activarse o desactivarse por usuario y tipo de notificación.

Tipos de notificación ​

TipoCuándo se dispara
USER_CREATEDAl crear una cuenta nueva
USER_INVITEDAl recibir una invitación a una empresa
USER_INVITATION_ACCEPTEDAl aceptar una invitación
ROLE_CHANGEDAl cambiar el rol de un usuario
EXPORT_READYAl completar una exportación
PAYMENT_FAILEDAl fallar un cobro de la suscripción
SUBSCRIPTION_CHANGEDAl cancelarse o modificarse una suscripción
INVOICE_AVAILABLEAl generarse una nueva factura
TRIAL_ENDINGCuando el período de prueba está por vencer
FEEDBACK_RECEIVEDAl recibirse feedback nuevo desde el widget de beta testers — se notifica in-app a todos los super administradores de la plataforma
CUSTOMContenido 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.

http
POST /notifications/send
Authorization: Bearer <token>   # o X-API-Key: sk_…
X-Company-Id: <companyId>
Content-Type: application/json

Modos de destinatarios

modeComportamiento
broadcastTodos los miembros actuales de la empresa
usersLista 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. Omitir destination es válido; si se incluye, debe ser una ruta interna no vacía que empiece por /. null, vacío, esquemas javascript:/http(s):// y URLs protocol-relative // → 400.
  • Plantilla: { "type", "payload" } — tipos del catálogo (no CUSTOM). El API exige que payload incluya todos los requiredFields de la plantilla; claves ausentes o en blanco → 400

Canales (opcional):

  • channels: lista de in_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 → omissions con no_recipient_devices

Respuesta: 202 Accepted con:

json
{
  "accepted": true,
  "channels": ["in_app"],
  "omissions": []
}

Sin estado de entrega por destinatario (send-and-forget). MEMBER → 403.

Ejemplo broadcast libre:

json
{
  "mode": "broadcast",
  "title": "Aviso de la empresa",
  "body": "Mañana hay all-hands",
  "destination": "/announcements"
}

Ejemplo multi-canal:

json
{
  "mode": "users",
  "userIds": ["uuid-miembro"],
  "title": "Ping",
  "body": "Hola",
  "channels": ["in_app", "email", "native_push"]
}

Ejemplo lista + plantilla:

json
{
  "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).

http
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": "…" }
}
platformBody
webendpoint (URL de suscripción) + keys.p256dh + keys.auth
ios / androidendpoint = 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 ​

http
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 ​

http
GET /notifications/scheduled?page=1&limit=20
POST /notifications/scheduled/:id/cancel

Por 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 ​

EndpointQué listaQuién
GET /notifications/sendsOutbox de envíos originados por el actor (inmediato + programado): id, mode, contenido/plantilla, canales solicitados, status, timestamps; los fallidos incluyen failedAt y lastErrorOWNER/ADMIN/sk_
GET /notifications/tenantTodas 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 ​

http
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:

json
{
  "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.

  1. Obtener ticket (JWT de sesión + empresa activa):
http
POST /notifications/realtime/ticket
Authorization: Bearer <token>
X-Company-Id: <companyId>

Respuesta: { "ticket": "...", "expiresIn": 45 } (~45s, un solo uso).

  1. Abrir el stream (EventSource no puede enviar Bearer):
http
GET /notifications/stream?ticket=<ticket>
Accept: text/event-stream

Eventos 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 ​

http
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 ​

http
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:

http
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étodoRutaDescripción
GET/notifications/templatesListar el catálogo de plantillas de sistema (companyId nulo)
GET/notifications/templates/:idObtener una plantilla de sistema por id — 404 si el id es de una plantilla propia de empresa
POST/notifications/templatesCrear una plantilla de sistema
PATCH/notifications/templates/:idEditar una plantilla de sistema — no afecta notificaciones ya enviadas; 404 si el id es de empresa
DELETE/notifications/templates/:idEliminar 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:

http
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étodoRutaDescripción
GET/notifications/templates/availableListado unificado: catálogo de sistema + plantillas propias de la empresa activa (OWNER/ADMIN)
http
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étodoRutaDescripción
GET/notifications/company-templatesListar las plantillas propias de la empresa activa
GET/notifications/company-templates/:idObtener una plantilla propia por id (404 si es de otra empresa)
POST/notifications/company-templatesCrear una plantilla propia para la empresa activa
PATCH/notifications/company-templates/:idEditar una plantilla propia — no afecta notificaciones ya enviadas con la versión anterior
DELETE/notifications/company-templates/:idEliminar una plantilla propia — no afecta notificaciones ya enviadas

Ejemplo de creación:

http
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étodoRutaDescripción
GET/notifications/preferencesLista las preferencias explícitas del usuario autenticado en la empresa activa
PUT/notifications/preferencesActiva/desactiva un par tipo+canal ({ type, channel, enabled }). Tipo o canal inválido → 400. El userId sale de la sesión, nunca del body
http
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 correo

No 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):

  1. Implementar la interfaz NotificationChannelService
  2. Añadirlo como provider en NotificationsModule
  3. Registrar el canal en NotificationsService.getChannelService()

Para añadir un nuevo tipo de notificación:

  1. Añadir el valor al enum NotificationType
  2. Añadir el renderer de canales en template.registry.ts (matriz de canales + fallback)
  3. Añadir la entrada en system-catalog.seed.ts (content con — fuente de render en runtime)
  4. Si se dispara por un evento, añadir el listener en NotificationEventListener