REST API Reference: Dashboard Statistics Endpoint

The Dashboard API exposes a single aggregated statistics endpoint that powers the main management screen. It queries attendance records, client memberships, and transaction history in one call, then shapes the response based on the authenticated user’s role. Admins receive full financial data; recepcionistas receive the same operational data but without revenue figures, keeping sensitive business metrics appropriately restricted.

GET /api/dashboard/stats

Returns aggregated gym statistics. The response shape varies by role — see the field reference and examples below. Auth: Authorization: Bearer <token> — any authenticated role

Success Response — 200

All roles receive the base fields. Admin accounts additionally receive the three financial fields marked admin only below.

totalMovimientos

number

required

Total count of all transactions ever recorded in the system (not filtered by date).

ocupacionActual

number (0–100)

required

Today’s occupancy percentage: (today's attendance count / active client count) × 100, rounded to the nearest integer and capped at 100. Returns 0 when there are no active clients.

proximosVencimientos

array (max 5)

required

Clients whose membership expires within the next 7 days, ordered by vencimiento ascending.

Show proximosVencimientos item

string (UUID)

Client ID.

nombre

string

Client first name.

apellidos

string

Client last name.

dias

integer

Days remaining until expiration (ceiling-rounded).

diasFaltantes

integer

Alias for dias — same value, included for frontend compatibility.

plan

string

Membership plan name, e.g. "Mensual".

fotoUrl

string | null

Cloudinary URL of the client’s profile photo, or null.

status

"ACTIVO" | "VENCIDO" | "PENDIENTE"

Client membership status.

actividadReciente

array (max 5)

required

The five most recent events across both transactions and attendance check-ins, merged and sorted by createdAt descending.

Show actividadReciente item

string

Prefixed ID — "trx-{id}" for transactions or "att-{id}" for attendances.

usuario

string

Full name of the client or payer (nombre + apellidos).

accion

string

Description — concepto for transactions; "Registro de asistencia" for check-ins.

area

string

Payment method for transactions (e.g. "Tarjeta"); "Recepcion" for check-ins.

hora

string

Stored hora string, e.g. "10:30 AM".

tipo

"check" | "pago"

"check" for attendance records and membership transactions; "pago" for product sales.

monto

number

Transaction amount in MXN; 0 for attendance check-ins.

createdAt

ISO 8601 datetime

UTC timestamp used for sorting.

afluenciaPorHora

array (7 items)

required

Today’s attendance counts bucketed into fixed two-hour slots. Always returns exactly 7 entries regardless of whether any attendance was recorded for a given hour.

Show afluenciaPorHora item

hora

"08:00" | "10:00" | "12:00" | "14:00" | "16:00" | "18:00" | "20:00"

Hour bucket label.

valor

integer

Number of attendances recorded in this hour slot today.

afluenciaPorDia

array (7 items)

required

Current ISO week (Monday → Sunday) with attendance and transaction counts per day. Days in the future still appear with real: 0 and proyectado: 0.

Show afluenciaPorDia item

dia

"Lun" | "Mar" | "Mie" | "Jue" | "Vie" | "Sab" | "Dom"

Abbreviated day label.

real

integer

Attendance check-ins recorded on this day.

proyectado

integer

Transactions recorded on this day (used as a projected-revenue proxy).

ingresosTotalesMes

number

Admin only. Sum of all transaction monto values in the current calendar month (UTC boundaries).

metaMensual

number

Admin only. Hardcoded monthly revenue target: 60000 MXN.

porcentajeMeta

number (0–100)

Admin only. (ingresosTotalesMes / metaMensual) × 100, capped at 100.

Error Responses

Status	Meaning
`401`	Missing or invalid Bearer token
`500`	Internal server error

Example — Admin response

curl -X GET https://api.spartansgym.com/api/dashboard/stats \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Example — Recepcionista response

Recepcionista (200 OK)

{
  "success": true,
  "data": {
    "totalMovimientos": 1340,
    "ocupacionActual": 42,
    "proximosVencimientos": [
      {
        "id": "a1b2c3d4-1234-5678-abcd-ef0123456789",
        "nombre": "Luis",
        "apellidos": "Ramírez",
        "dias": 2,
        "diasFaltantes": 2,
        "plan": "Mensual",
        "fotoUrl": "https://res.cloudinary.com/spartans/image/upload/v1/clients/luis.jpg",
        "status": "ACTIVO"
      }
    ],
    "actividadReciente": [
      {
        "id": "trx-101",
        "usuario": "Ana Torres",
        "accion": "Membresía Mensual",
        "area": "Tarjeta",
        "hora": "11:00 AM",
        "tipo": "check",
        "monto": 500,
        "createdAt": "2024-06-15T17:00:00.000Z"
      }
    ],
    "afluenciaPorHora": [
      { "hora": "08:00", "valor": 5 },
      { "hora": "10:00", "valor": 12 },
      { "hora": "12:00", "valor": 8 },
      { "hora": "14:00", "valor": 3 },
      { "hora": "16:00", "valor": 7 },
      { "hora": "18:00", "valor": 14 },
      { "hora": "20:00", "valor": 4 }
    ],
    "afluenciaPorDia": [
      { "dia": "Lun", "real": 22, "proyectado": 18 },
      { "dia": "Mar", "real": 19, "proyectado": 15 },
      { "dia": "Mie", "real": 25, "proyectado": 21 },
      { "dia": "Jue", "real": 17, "proyectado": 14 },
      { "dia": "Vie", "real": 30, "proyectado": 26 },
      { "dia": "Sab", "real": 28, "proyectado": 20 },
      { "dia": "Dom", "real": 10, "proyectado": 8 }
    ]
  }
}

The ingresosTotalesMes, metaMensual, and porcentajeMeta fields are silently omitted from the recepcionista response — they are not set to null or 0. Client code should treat their absence as an access-controlled omission and guard accordingly (e.g. data.ingresosTotalesMes ?? null).

Overview

Endpoints

REST API Reference: Dashboard Statistics Endpoint

GET /api/dashboard/stats

Success Response — 200

Error Responses

Example — Admin response

Example — Recepcionista response

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /api/dashboard/stats

​Success Response — 200

​Error Responses

​Example — Admin response

​Example — Recepcionista response

Build docs developers (and LLMs) love

GET /api/dashboard/stats

Success Response — 200

Error Responses

Example — Admin response

Example — Recepcionista response