GET /api/admin/dashboard/estadisticas

El endpoint de estadísticas del dashboard es el punto de entrada principal para el panel de control administrativo de Comfaca Créditos en Línea. En una sola petición agrega cuatro dimensiones analíticas del sistema: el estado del portafolio de solicitudes de crédito (incluyendo tasas de aprobación, montos acumulados y distribución por estado), el rendimiento del programa de convenios empresariales, la composición del directorio de usuarios por rol y la actividad más reciente del sistema. Esta consolidación evita múltiples llamadas paralelas desde el cliente y permite renderizar el dashboard completo con un único fetch.

Este endpoint requiere una sesión activa con rol administrador. Las peticiones sin autenticación o con rol insuficiente recibirán 401 Unauthorized o 403 Forbidden.

Autenticación

Requiere rol administrador. Se autentica mediante la cookie de sesión de Nuxt (nuxt-session).

Query Parameters

Este endpoint no acepta parámetros de consulta. Siempre devuelve las estadísticas del estado actual del sistema completo.

Response

success

boolean

true cuando la consulta se ejecuta sin errores.

message

string

"Consulta completada exitosamente".

data

object

Show Estructura completa de data

solicitudes

object

Estadísticas del portafolio de solicitudes de crédito.

Show Campos de solicitudes

total

number

Total de solicitudes registradas en el sistema (todos los estados).

aprobadas

number

Número de solicitudes con estado APROBADA.

activas

number

Solicitudes que aún están en el flujo de validación (excluye RECHAZADA, DESESTIMADA, CANCELADA y DESISTE).

pendientesFirma

number

Solicitudes con estado PENDIENTE_FIRMADO esperando la firma digital de los involucrados.

montoTotalAprobado

number | null

Suma total del campo valor_solicitud de todas las solicitudes aprobadas, en pesos colombianos (COP).

tasaAprobacion

number

Porcentaje de aprobación calculado como (aprobadas / total) * 100. Retorna 0 si no hay solicitudes.

porEstado

array

Distribución de solicitudes por cada estado activo en la tabla estados_solicitud, ordenada por el campo orden.

Show Estructura de cada elemento

estado

string

ID del estado (ej. POSTULADO, APROBADA).

nombre

string

Nombre legible del estado (ej. "Postulado", "Aprobada").

count

string

Cantidad de solicitudes en este estado (serializado como string).

color

string

Color HEX o nombre CSS asignado al estado para la visualización en gráficas.

porMes

array

Tendencia de nuevas solicitudes en los últimos 6 meses.

Show Estructura de cada elemento

mes

string

Mes en formato YYYY-MM.

nombre

string

Nombre legible del mes en español (ej. "noviembre de 2024").

count

number

Número de solicitudes creadas en ese mes.

convenios

object

Estadísticas del programa de convenios empresariales.

Show Campos de convenios

activos

string

Número de convenios con estado Activo (serializado como string).

totalEmpresas

string

Total de empresas únicas registradas por NIT (serializado como string).

topEmpresas

array

Las 5 empresas con mayor número de empleados registrados.

Show Estructura de cada empresa

Nombre de la empresa.

nit

string

NIT de la empresa.

numero_empleados

string

Número de empleados registrados.

tipo_empresa

string | null

Tipo de sociedad (S.A.S., E.S.P., etc.).

porTipo

array

Distribución de convenios por tipo de empresa.

Show Estructura de cada elemento

tipo_empresa

string | null

Tipo de empresa.

count

string

Cantidad de empresas de ese tipo.

usuarios

object

Estadísticas del directorio de usuarios del sistema.

Show Campos de usuarios

total

number

Total de usuarios registrados.

activos

number

Usuarios con disabled: false.

recientes

number

Usuarios creados en los últimos 30 días.

trabajadores

string | undefined

Cantidad de usuarios con rol user_trabajador.

porRol

array

Distribución de usuarios por rol.

Show Estructura de cada elemento

role

string

Nombre del rol (ej. admin, user_trabajador, asesor).

count

string

Número de usuarios con ese rol.

actividadReciente

object

Snapshot de la actividad más reciente del sistema.

Show Campos de actividadReciente

solicitudesRecientes

array

Las últimas 5 solicitudes de crédito creadas, ordenadas por created_at descendente.

Show Campos de cada solicitud reciente

numero_solicitud

string

Número de la solicitud.

estado

string

Estado actual de la solicitud.

created_at

string

Fecha de creación.

owner_username

string

Username del solicitante.

usuariosRecientes

array

Los últimos 5 usuarios creados, ordenados por created_at descendente.

Show Campos de cada usuario reciente

username

string

Username del nuevo usuario.

full_name

string | null

Nombre completo.

numero_documento

string | null

Documento de identidad.

roles

array

Roles asignados al usuario.

created_at

string

Fecha de registro.

ultimaActualizacion

string

Timestamp ISO 8601 del momento en que se generaron las estadísticas. Útil para mostrar en el dashboard cuándo se actualizaron los datos por última vez.

Ejemplo de petición

curl -X GET "https://app.comfaca.com/api/admin/dashboard/estadisticas" \
  -H "Cookie: nuxt-session=<token>"

Ejemplo de respuesta completa

{
  "success": true,
  "message": "Consulta completada exitosamente",
  "data": {
    "solicitudes": {
      "total": 102,
      "aprobadas": 34,
      "activas": 61,
      "pendientesFirma": 3,
      "montoTotalAprobado": 850000000,
      "tasaAprobacion": 33.33,
      "porEstado": [
        { "estado": "POSTULADO",           "nombre": "Postulado",             "count": "12", "color": "#6B7280" },
        { "estado": "DOCUMENTOS_CARGADOS", "nombre": "Documentos cargados",   "count": "8",  "color": "#F59E0B" },
        { "estado": "ENVIADO_VALIDACION",  "nombre": "Enviado a validación",  "count": "5",  "color": "#3B82F6" },
        { "estado": "PENDIENTE_FIRMADO",   "nombre": "Pendiente de firmado",  "count": "3",  "color": "#8B5CF6" },
        { "estado": "FIRMADO",             "nombre": "Firmado",               "count": "27", "color": "#10B981" },
        { "estado": "APROBADA",            "nombre": "Aprobada",              "count": "34", "color": "#22C55E" },
        { "estado": "RECHAZADA",           "nombre": "Rechazada",             "count": "6",  "color": "#EF4444" },
        { "estado": "DESESTIMADA",         "nombre": "Desestimada",           "count": "2",  "color": "#F97316" },
        { "estado": "CANCELADA",           "nombre": "Cancelada",             "count": "1",  "color": "#9CA3AF" },
        { "estado": "DESISTE",             "nombre": "Desistida",             "count": "4",  "color": "#D1D5DB" }
      ],
      "porMes": [
        { "mes": "2024-06", "nombre": "junio de 2024",      "count": 9  },
        { "mes": "2024-07", "nombre": "julio de 2024",      "count": 14 },
        { "mes": "2024-08", "nombre": "agosto de 2024",     "count": 18 },
        { "mes": "2024-09", "nombre": "septiembre de 2024", "count": 21 },
        { "mes": "2024-10", "nombre": "octubre de 2024",    "count": 22 },
        { "mes": "2024-11", "nombre": "noviembre de 2024",  "count": 18 }
      ]
    },
    "convenios": {
      "activos": "45",
      "totalEmpresas": "52",
      "topEmpresas": [
        { "razon_social": "Hospital Regional del Norte E.S.P.", "nit": "900456789", "numero_empleados": "850", "tipo_empresa": "E.S.P." },
        { "razon_social": "Constructora Andina S.A.S.",         "nit": "900123456", "numero_empleados": "250", "tipo_empresa": "S.A.S." }
      ],
      "porTipo": [
        { "tipo_empresa": "S.A.S.",  "count": "28" },
        { "tipo_empresa": "E.S.P.",  "count": "10" },
        { "tipo_empresa": "S.A.",    "count": "7"  },
        { "tipo_empresa": "Ltda.",   "count": "5"  },
        { "tipo_empresa": null,      "count": "2"  }
      ]
    },
    "usuarios": {
      "total": 187,
      "activos": 180,
      "recientes": 14,
      "trabajadores": "162",
      "porRol": [
        { "role": "user_trabajador", "count": "162" },
        { "role": "asesor",          "count": "18"  },
        { "role": "admin",           "count": "7"   }
      ]
    },
    "actividadReciente": {
      "solicitudesRecientes": [
        {
          "numero_solicitud": "SOL-2024-000102",
          "estado": "DOCUMENTOS_CARGADOS",
          "created_at": "2024-11-15T14:22:00.000Z",
          "owner_username": "pedro.ramirez"
        },
        {
          "numero_solicitud": "SOL-2024-000101",
          "estado": "APROBADA",
          "created_at": "2024-11-15T11:05:00.000Z",
          "owner_username": "lucia.vargas"
        }
      ],
      "usuariosRecientes": [
        {
          "username": "ana.moreno",
          "full_name": "Ana Moreno Castillo",
          "numero_documento": "63456789",
          "roles": ["user_trabajador"],
          "created_at": "2024-11-15T09:00:00.000Z"
        }
      ]
    },
    "ultimaActualizacion": "2024-11-15T17:30:00.000Z"
  }
}

Tipo `DashboardStats`

Estructura TypeScript del objeto de estadísticas que devuelve el endpoint (campo data):

interface DashboardStats {
  solicitudes: {
    total: number
    aprobadas: number
    activas: number
    pendientesFirma: number
    montoTotalAprobado: Decimal | null
    tasaAprobacion: number
    porEstado: Array<{
      estado: string
      nombre: string
      count: string      // serializado como string
      color: string
    }>
    porMes: Array<{
      mes: string        // formato "YYYY-MM"
      nombre: string     // ej. "noviembre de 2024"
      count: number
    }>
  }
  convenios: {
    activos: string      // serializado como string
    totalEmpresas: string
    topEmpresas: Array<{
      razon_social: string
      nit: string
      numero_empleados: string
      tipo_empresa: string | null
    }>
    porTipo: Array<{
      tipo_empresa: string | null
      count: string
    }>
  }
  usuarios: {
    total: number
    activos: number
    recientes: number
    trabajadores: string | undefined
    porRol: Array<{
      role: string
      count: string
    }>
  }
  actividadReciente: {
    solicitudesRecientes: Array<{
      numero_solicitud: string | null
      estado: string
      created_at: Date
      owner_username: string
    }>
    usuariosRecientes: Array<{
      username: string
      created_at: Date | null
      roles: unknown
      numero_documento: string | null
      full_name: string | null
    }>
  }
  ultimaActualizacion: string  // ISO 8601
}

Para refrescar únicamente los contadores por estado sin recargar todas las estadísticas del dashboard, usa el endpoint más liviano GET /api/admin/solicitudes/estados-count. Este solo ejecuta un groupBy en la tabla de solicitudes y es significativamente más rápido que el endpoint de estadísticas completas.

Autenticación

Solicitudes de Crédito

Panel Administrativo

Utilidades

GET /api/admin/dashboard/estadisticas — Métricas del Dashboard