Notificaciones

Sistema de notificaciones in-app

Keirost incluye un sistema de notificaciones en tiempo real para mantener informados a los usuarios sin necesidad de consultar manualmente.

Tipos de notificación

Tipo	Descripción	Cuándo se genera
email_status	Estado de envío de email	Al completarse o fallar un email encolado
document_sent	Documento enviado	Al enviar un documento por email
payment_received	Cobro recibido	Al registrar un pago de cliente
payment_made	Pago realizado	Al registrar un pago a proveedor
document_locked	Documento bloqueado	Al asentar una factura
automation_triggered	Automatización ejecutada	Al cumplirse una regla de automatización
plugin_error	Error en plugin	Cuando un plugin lanza una excepción
system_alert	Alerta del sistema	Espacio en disco bajo, backup fallido, etc.
mention	Mención	Cuando otro usuario te menciona en un comentario

Modelo de notificación

interface Notification {
  id: string;
  type: NotificationType;
  title: string;
  body: string;
  read: boolean;
  user_id: string;
  tenant_id: string;
  metadata?: Record<string, unknown>;
  action_url?: string;
  action_label?: string;
  created_at: string;
  read_at?: string;
}

---

Endpoint de notificaciones

Listar notificaciones del usuario

GET /api/notifications
GET /api/notifications?read=false
GET /api/notifications?type=email_status
GET /api/notifications?limit=10&offset=0
Authorization: Bearer <token>

Respuesta:

{
  "data": [
    {
      "id": "notif_001",
      "type": "email_status",
      "title": "Email enviado correctamente",
      "body": "Factura F-2026-0012 enviada a cliente@acme.com",
      "read": false,
      "action_url": "/sales-invoices/inv_2026_0012",
      "action_label": "Ver factura",
      "created_at": "2026-05-08T10:05:00Z"
    },
    {
      "id": "notif_002",
      "type": "payment_received",
      "title": "Cobro registrado",
      "body": "Recibido pago de 1.210,00 EUR de Acme S.L.",
      "read": true,
      "read_at": "2026-05-08T11:00:00Z",
      "created_at": "2026-05-08T09:30:00Z"
    }
  ],
  "pagination": {
    "total": 42,
    "page": 1,
    "per_page": 20,
    "has_more": true
  },
  "unread_count": 3
}

Marcar como leida

POST /api/notifications/:id/read

Marcar todas como leidas

POST /api/notifications/read-all

Eliminar notificación

DELETE /api/notifications/:id

Marcar como no leida

POST /api/notifications/:id/unread

---

Campana de notificaciones (UI)

El icono de campana en la barra superior:

• Muestra un indicador pulsante cuando hay notificaciones no leidas
• Al hacer click abre el dropdown de notificaciones con las 10 mas recientes
• Muestra el contador total de no leidas en un badge
• El dropdown tiene enlace “Ver todas” que lleva a la página de notificaciones completa

Componente bell

// El componente NotificationBell esta en @openfactu/ui
import { NotificationBell } from '@openfactu/ui';

<NotificationBell
  unreadCount={3}
  notifications={recentNotifications}
  onMarkRead={(id) => markAsRead(id)}
  onMarkAllRead={() => markAllAsRead()}
/>

Polling en tiempo real

La interfaz comprueba nuevas notificaciones cada 30 segundos via:

GET /api/notifications/unread-count

{
  "unread_count": 3
}

También se reciben en tiempo real via WebSocket (/ws/notifications) para usuarios activos.

---

Feed de tareas en segundo plano

El feed de tareas muestra el progreso de operaciones que se ejecutan en segundo plano (exportación de datos, generación de informes PDF, sincronización masiva).

Modelo de tarea en background

interface BackgroundTask {
  id: string;
  type: 'export' | 'report' | 'sync' | 'backup';
  status: 'running' | 'completed' | 'failed';
  progress: number;         // 0-100
  message: string;           // "Exportando 156 facturas..."
  result_url?: string;      // URL del archivo generado
  error?: string;
  created_at: string;
  completed_at?: string;
}

Endpoints

GET  /api/tasks
GET  /api/tasks/:id
GET  /api/tasks/:id/progress
DELETE /api/tasks/:id

Notificaciones de tarea

Cuando una tarea en segundo plano termina (completada o fallida), se genera una notificación:

{
  "type": "task_completed",
  "title": "Exportacion completada",
  "body": "El archivo facturas_2026.xlsx esta listo para descargar.",
  "action_url": "/api/exports/facturas_2026.xlsx",
  "action_label": "Descargar"
}

---

Configuración de notificaciones

Cada usuario puede configurar que notificaciones quiere recibir.

GET /api/notifications/settings
PATCH /api/notifications/settings

{
  "email_status": true,
  "document_sent": true,
  "payment_received": true,
  "payment_made": false,
  "document_locked": true,
  "automation_triggered": true,
  "plugin_error": true,
  "system_alert": true,
  "mention": true,
  "push_enabled": true,
  "email_enabled": false
}

Campo	Descripción
push_enabled	Recibir notificaciones push en el navegador
email_enabled	Recibir resumen diario por email

Notificaciones push via navegador

Keirost soporta Web Push API para notificaciones nativas del navegador (incluso con la pestana cerrada).

El servicio worker se registra automáticamente si el navegador lo soporta. El icono de campana solicita permiso la primera vez.

---

Webhooks de notificación

También puedes registrar webhooks para recibir notificaciones en sistemas externos:

{
  "event": "notification.created",
  "url": "https://tu-sistema.com/webhook/notifications",
  "method": "POST",
  "active": true,
  "filter_types": ["payment_received", "document_locked"]
}

Payload del webhook:

{
  "event": "notification.created",
  "timestamp": "2026-05-08T10:05:00Z",
  "data": {
    "notification_id": "notif_001",
    "type": "payment_received",
    "title": "Cobro registrado",
    "body": "Recibido pago de 1.210,00 EUR de Acme S.L.",
    "user_id": "user_admin",
    "tenant_id": "tenant_demo"
  }
}

---

Resumen de endpoints

Método	Ruta	Descripción
GET	/api/notifications	Listar notificaciones
GET	/api/notifications/unread-count	Contador de no leidas
POST	/api/notifications/:id/read	Marcar como leida
POST	/api/notifications/read-all	Marcar todas como leidas
POST	/api/notifications/:id/unread	Marcar como no leida
DELETE	/api/notifications/:id	Eliminar notificación
GET	/api/notifications/settings	Obtener preferencias
PATCH	/api/notifications/settings	Guardar preferencias
GET	/api/tasks	Listar tareas en segundo plano
GET	/api/tasks/:id	Detalle de tarea
GET	/api/tasks/:id/progress	Progreso de tarea