API de Notificaciones In-App — Comfaca Créditos

El sistema de notificaciones in-app de Comfaca Créditos en Línea permite mantener a los usuarios informados sobre eventos relevantes de sus solicitudes — cambios de estado, vencimientos de plazo, firmas digitales pendientes y más. Cada notificación pertenece exclusivamente al usuario autenticado (owner_username), y el servidor lleva registro del momento exacto en que fue leída (read_at). Todos los endpoints de esta sección requieren una sesión activa.

Todos los endpoints de /api/notifications requieren autenticación mediante cookie de sesión. Las peticiones sin sesión válida reciben una respuesta 401 No hay sesión activa.

GET /api/notifications

Retorna la lista de notificaciones del usuario autenticado, ordenadas de más reciente a más antigua. Incluye el conteo de no leídas y el total de notificaciones del usuario.

Query Parameters

boolean

default:"false"

Si se envía true, filtra y retorna únicamente las notificaciones no leídas (aquellas cuyo read_at es null).

number

default:"50"

Cantidad máxima de notificaciones a retornar. Por defecto 50.

Respuesta exitosa `200`

{
  "success": true,
  "message": "Notificaciones obtenidas exitosamente",
  "data": {
    "notifications": [
      {
        "id": "b3f1c2d4-89ab-4cde-bf01-23456789abcd",
        "type": "estado_solicitud",
        "data": {
          "solicitud_id": "42",
          "estado": "aprobada",
          "mensaje": "Su solicitud de crédito ha sido aprobada."
        },
        "read_at": null,
        "created_at": "2026-03-15T14:30:00.000Z",
        "owner_username": "jdoe",
        "notifiable_type": "User",
        "notifiable_id": "1",
        "updated_at": "2026-03-15T14:30:00.000Z"
      }
    ],
    "unread_count": 3,
    "total": 12
  }
}

Show Campos del objeto notification

string

Identificador único UUID de la notificación.

string

Tipo de notificación. Ejemplos: estado_solicitud, firma_digital, plazo_vencimiento, sistema.

object

Payload JSON con información específica del evento que generó la notificación (campos variables según el type).

string | null

Timestamp ISO 8601 del momento en que el usuario leyó la notificación. null si aún no ha sido leída.

string

Timestamp ISO 8601 de creación de la notificación.

string

Nombre de usuario propietario de la notificación.

string

Tipo de entidad notificable (siempre "User" en la implementación actual).

string

ID de la entidad notificable asociada.

string

Timestamp ISO 8601 de la última actualización del registro.

number

(Raíz del data) Total de notificaciones no leídas del usuario.

number

(Raíz del data) Total de notificaciones del usuario (leídas y no leídas).

Ejemplo curl

# Listar todas las notificaciones (máx. 50)
curl -X GET "https://app.comfaca.com/api/notifications" \
  -H "Cookie: nuxt-session=<token>"

# Solo notificaciones no leídas
curl -X GET "https://app.comfaca.com/api/notifications?unread=true" \
  -H "Cookie: nuxt-session=<token>"

# Con límite personalizado
curl -X GET "https://app.comfaca.com/api/notifications?limit=10" \
  -H "Cookie: nuxt-session=<token>"

GET /api/notifications/unread-count

Retorna únicamente el conteo de notificaciones no leídas del usuario autenticado. Ideal para actualizar badges en la UI sin cargar el listado completo.

Respuesta exitosa `200`

{
  "success": true,
  "data": {
    "unread_count": "5"
  }
}

string

Número de notificaciones no leídas del usuario, retornado como cadena de texto.

Ejemplo curl

curl -X GET "https://app.comfaca.com/api/notifications/unread-count" \
  -H "Cookie: nuxt-session=<token>"

PUT /api/notifications/:id/read

Marca una notificación específica como leída, estableciendo su campo read_at con la fecha y hora actuales. Solo el propietario de la notificación puede marcarla como leída.

Path Parameters

string

required

UUID de la notificación a marcar como leída.

Respuesta exitosa `200`

{
  "success": true,
  "message": "Notificación marcada como leída",
  "data": null
}

Códigos de error

Código	Causa
`400`	No se proporcionó el `id` de la notificación
`401`	No hay sesión activa
`403`	La notificación pertenece a otro usuario
`404`	La notificación no existe

Ejemplo curl

curl -X PUT "https://app.comfaca.com/api/notifications/b3f1c2d4-89ab-4cde-bf01-23456789abcd/read" \
  -H "Cookie: nuxt-session=<token>"

PUT /api/notifications/mark-all-read

Marca todas las notificaciones no leídas del usuario autenticado como leídas en una sola operación. Retorna el número de notificaciones afectadas.

Respuesta exitosa `200`

{
  "success": true,
  "message": "Notificaciones marcadas como leídas",
  "data": {
    "marked_count": 7
  }
}

number

Cantidad de notificaciones que fueron marcadas como leídas en la operación.

Ejemplo curl

curl -X PUT "https://app.comfaca.com/api/notifications/mark-all-read" \
  -H "Cookie: nuxt-session=<token>"

DELETE /api/notifications/:id

Elimina permanentemente una notificación. Solo el propietario de la notificación puede eliminarla.

Esta operación es irreversible. La notificación se elimina definitivamente de la base de datos.

Path Parameters

string

required

UUID de la notificación a eliminar.

Respuesta exitosa `200`

{
  "success": true,
  "message": "Notificación eliminada exitosamente",
  "data": null
}

Códigos de error

Código	Causa
`400`	No se proporcionó el `id` de la notificación
`401`	No hay sesión activa
`403`	La notificación pertenece a otro usuario
`404`	La notificación no existe

Ejemplo curl

curl -X DELETE "https://app.comfaca.com/api/notifications/b3f1c2d4-89ab-4cde-bf01-23456789abcd" \
  -H "Cookie: nuxt-session=<token>"

Uso con el Composable `useNotifications`

El frontend consume estos endpoints a través del composable useNotifications, que gestiona el estado reactivo de las notificaciones en la aplicación Nuxt 4:

// Uso básico del composable
const {
  notifications,
  unreadCount,
  markAllRead
} = useNotifications()

// Marcar todas las notificaciones como leídas
await markAllRead()

// El conteo se actualiza reactivamente
console.log(`Notificaciones no leídas: ${unreadCount.value}`)

// Ejemplo más completo con manejo de estado
const {
  notifications,
  unreadCount,
  markAllRead
} = useNotifications()

// Escuchar cambios en tiempo real
watch(unreadCount, (newCount) => {
  if (Number(newCount) > 0) {
    // Mostrar badge en el icono de la campana
    updateBadge(Number(newCount))
  }
})

// En un componente de lista de notificaciones
async function handleMarkAllRead() {
  await markAllRead()
  // unreadCount se actualiza automáticamente a 0
}

Resumen de Endpoints

GET /api/notifications

Lista notificaciones del usuario con soporte para filtros unread y limit.

GET /api/notifications/unread-count

Conteo rápido de notificaciones no leídas para badges en la UI.

PUT /api/notifications/:id/read

Marca una notificación individual como leída por su UUID.

PUT /api/notifications/mark-all-read

Marca todas las notificaciones pendientes como leídas en lote.

Autenticación

Solicitudes de Crédito

Panel Administrativo

Utilidades

API de Notificaciones In-App — Comfaca Créditos

GET /api/notifications

Query Parameters

Respuesta exitosa `200`

Ejemplo curl

GET /api/notifications/unread-count

Respuesta exitosa `200`

Ejemplo curl

PUT /api/notifications/:id/read

Path Parameters

Respuesta exitosa `200`

Códigos de error

Ejemplo curl

PUT /api/notifications/mark-all-read

Respuesta exitosa `200`

Ejemplo curl

DELETE /api/notifications/:id

Path Parameters

Respuesta exitosa `200`

Códigos de error

Ejemplo curl

Uso con el Composable `useNotifications`

Resumen de Endpoints

GET /api/notifications

GET /api/notifications/unread-count

PUT /api/notifications/:id/read

PUT /api/notifications/mark-all-read

​GET /api/notifications

​Query Parameters

​Respuesta exitosa 200

​Ejemplo curl

​GET /api/notifications/unread-count

​Respuesta exitosa 200

​Ejemplo curl

​PUT /api/notifications/:id/read

​Path Parameters

​Respuesta exitosa 200

​Códigos de error

​Ejemplo curl

​PUT /api/notifications/mark-all-read

​Respuesta exitosa 200

​Ejemplo curl

​DELETE /api/notifications/:id

​Path Parameters

​Respuesta exitosa 200

​Códigos de error

​Ejemplo curl

​Uso con el Composable useNotifications

​Resumen de Endpoints

GET /api/notifications

GET /api/notifications/unread-count

PUT /api/notifications/:id/read

PUT /api/notifications/mark-all-read

GET /api/notifications

Query Parameters

Respuesta exitosa `200`

Ejemplo curl

GET /api/notifications/unread-count

Respuesta exitosa `200`

Ejemplo curl

PUT /api/notifications/:id/read

Path Parameters

Respuesta exitosa `200`

Códigos de error

Ejemplo curl

PUT /api/notifications/mark-all-read

Respuesta exitosa `200`

Ejemplo curl

DELETE /api/notifications/:id

Path Parameters

Respuesta exitosa `200`

Códigos de error

Ejemplo curl

Uso con el Composable `useNotifications`

Resumen de Endpoints