Saltearse al contenido
Keirost Keirost · Docs

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 notificacion

TipoDescripcionCuándo se genera
email_statusEstado de envio de emailAl completarse o fallar un email encolado
document_sentDocumento enviadoAl enviar un documento por email
payment_receivedCobro recibidoAl registrar un pago de cliente
payment_madePago realizadoAl registrar un pago a proveedor
document_lockedDocumento bloqueadoAl asentar una factura
automation_triggeredAutomatizacion ejecutadaAl cumplirse una regla de automatizacion
plugin_errorError en pluginCuando un plugin lanza una excepcion
system_alertAlerta del sistemaEspacio en disco bajo, backup fallido, etc.
mentionMencionCuando otro usuario te menciona en un comentario

Modelo de notificacion

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 notificacion

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 pagina 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
}

Tambien 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 (exportacion de datos, generacion de informes PDF, sincronizacion 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 notificacion:

{
  "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"
}

Configuracion 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
}
CampoDescripcion
push_enabledRecibir notificaciones push en el navegador
email_enabledRecibir 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 automaticamente si el navegador lo soporta. El icono de campana solicita permiso la primera vez.

Webhooks de notificacion

Tambien 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

MetodoRutaDescripcion
GET/api/notificationsListar notificaciones
GET/api/notifications/unread-countContador de no leidas
POST/api/notifications/:id/readMarcar como leida
POST/api/notifications/read-allMarcar todas como leidas
POST/api/notifications/:id/unreadMarcar como no leida
DELETE/api/notifications/:idEliminar notificacion
GET/api/notifications/settingsObtener preferencias
PATCH/api/notifications/settingsGuardar preferencias
GET/api/tasksListar tareas en segundo plano
GET/api/tasks/:idDetalle de tarea
GET/api/tasks/:id/progressProgreso de tarea