Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/azahel79/Spartans-gym/llms.txt

Use this file to discover all available pages before exploring further.

The Attendances API provides a read-only view of every gym check-in event recorded in the system. It is designed for reporting and roster review — managers can filter by date range, client status, plan, or search term to produce attendance reports. The actual act of recording a new check-in is performed through the client-scoped endpoint POST /api/clients/:id/attendance, which is fully documented on the Clients page. All attendance endpoints require a valid Bearer token and are accessible to any authenticated role.

​
The Attendance Object

Each item in the response array is a flattened object that combines the core attendance record with a snapshot of the related client’s details at query time.
​
id
integer
required
Auto-incremented integer identifier for the attendance record.
​
clientId
string
required
UUID of the client who checked in.
​
userId
integer | null
ID of the staff User who registered the attendance, or null if the user account has since been deleted (onDelete: SetNull).
​
fecha
string
required
ISO 8601 datetime of the check-in event. Stored in UTC; use the companion hora field for a human-readable local time.
​
hora
string
required
Check-in time formatted as HH:MM AM/PM in the America/Mexico_City timezone (e.g. "09:45 AM").
​
createdAt
string
required
ISO 8601 datetime when the record was persisted.
​
nombre
string
required
Client’s first name at query time.
​
apellidos
string
required
Client’s last name(s) at query time.
​
telefono
string
required
Client’s phone number at query time.
​
plan
string
required
Name of the plan the client was enrolled in at query time.
​
metodoPago
string
required
Payment method on the client’s current membership.
​
status
string
required
Client’s membership status at query time (ACTIVO, VENCIDO, or PENDIENTE).
​
fotoUrl
string | null
Client’s profile photo URL, or null.
​
vencimiento
string
required
Client’s current membership expiry datetime (ISO 8601).
​
user
object | null
Snapshot of the staff user who registered the check-in, or null.

​
Endpoints

​
List Attendance Records

Requires a valid Bearer token. Accessible to all roles (admin and recepcionista).
Returns all attendance records in descending order by fecha. All query parameters are optional and combinable. 
GET /api/attendances
Query Parameters
​
fechaInicio
string
Start date for filtering records, formatted as YYYY-MM-DD. Interpreted as the start of that calendar day in the America/Mexico_City timezone (UTC-6 offset used for boundary calculation). Results include records from this date onward.
​
fechaFin
string
End date for filtering, formatted as YYYY-MM-DD. If provided alongside fechaInicio, results are bounded to the inclusive date range [fechaInicio, fechaFin]. If equal to fechaInicio, only records for that single day are returned.
​
status
string
Filter by client membership status. Accepted values: ACTIVO, VENCIDO, PENDIENTE. Pass Todos or omit to include all statuses.
​
plan
string
Filter by client plan name. Pass Todos los planes, Cualquiera, or omit to include all plans.
​
search
string
Case-insensitive substring search across the related client’s nombre, apellidos, and telefono fields.
Success Response — 200 OK 
{
  "success": true,
  "data": [
    {
      "id": 482,
      "clientId": "a1b2c3d4-...",
      "userId": 3,
      "fecha": "2025-07-16T16:05:00.000Z",
      "hora": "10:05 AM",
      "createdAt": "2025-07-16T16:05:01.000Z",
      "nombre": "Ana",
      "apellidos": "García Torres",
      "telefono": "5598765432",
      "plan": "Mensual",
      "metodoPago": "Tarjeta",
      "status": "ACTIVO",
      "fotoUrl": null,
      "vencimiento": "2025-08-16T06:00:00.000Z",
      "user": {
        "id": 3,
        "email": "recepcion@spartansgym.com",
        "role": "recepcionista"
      }
    }
  ]
}
Error Responses
StatusDescription
401Missing or invalid Bearer token.
403Authenticated user does not have the required role.
500Internal server error.
curl https://api.example.com/api/attendances \
  -H "Authorization: Bearer <token>"

​
Attendance Guards

When a check-in is submitted via POST /api/clients/:id/attendance, two server-side guards execute before the record is persisted. Understanding them helps you handle the relevant error codes correctly.

​
Membership Expiry Guard

Before writing any record, the controller compares client.vencimiento against the current date. Both values have their time components zeroed out (set to 00:00:00.000) before the comparison, so a membership that expires at any point during today is still considered valid for the whole calendar day. If expiryDate < today (date-only comparison), the endpoint returns: 
{
  "success": false,
  "error": "Membresía vencida"
}
with HTTP status 403 Forbidden.

​
Duplicate Attendance Guard

The system allows each client to check in at most once per calendar day. It queries for an existing Attendance record matching: 
clientId = :id
AND fecha >= startOfToday
AND fecha <  startOfTomorrow
If a matching record is found — or if the client’s attendanceDate already matches today’s date — the endpoint returns: 
{
  "success": false,
  "error": "El cliente ya registró asistencia hoy"
}
with HTTP status 400 Bad Request.
The ultimaVisita field on each Client record stores the check-in time as a human-readable string (e.g. "10:05 AM") formatted using the America/Mexico_City timezone via toLocaleTimeString('en-US', { hour12: true, timeZone: 'America/Mexico_City' }). The raw UTC timestamp is always available as attendanceDate on the Client or fecha on the Attendance record for precise time-zone-aware calculations on the client side.

Build docs developers (and LLMs) love

Get started for freeTalk to us