REST API Reference: Client Management Endpoints

The Clients API is the core of Spartans Gym’s member management. It covers the full member lifecycle: enrolling new clients with a plan and payment, querying and filtering the member roster, editing member details, recording daily gym check-ins, renewing expiring memberships, and removing former members. All endpoints require a valid Bearer token. Write operations are split by role — front-desk staff (recepcionista) can read and enroll; only admin users may edit or delete records.

The Client Object

Every successful response wraps a Client object (or an array of them) inside a data field alongside "success": true.

string

required

UUID. Unique identifier for the client record.

nombre

string

required

First name of the client.

apellidos

string

required

Last name(s) of the client.

genero

string

required

Biological gender. One of Masculino, Femenino, or Otro.

telefono

string

required

Phone number used as the primary contact identifier and search key.

plan

string

required

Name of the active membership plan the client is enrolled in.

monto

number

required

Amount paid (MXN) for the current membership period.

metodoPago

string

required

Payment method used. One of Efectivo, Tarjeta, or Transferencia.

status

string

required

Membership status. One of ACTIVO, VENCIDO, or PENDIENTE.

ultimaVisita

string

Time of the client’s last gym check-in, formatted as HH:MM AM/PM in the America/Mexico_City timezone. Defaults to --:-- until the first attendance is recorded.

vencimiento

string

required

ISO 8601 datetime string representing when the current membership expires.

fotoUrl

string | null

URL of the client’s profile photo, or null if none has been set.

attendanceDate

string | null

ISO 8601 datetime of the most recent attendance record, or null if the client has never checked in.

createdAt

string

required

ISO 8601 datetime when the client record was created.

updatedAt

string

required

ISO 8601 datetime when the client record was last modified.

Endpoints

List Clients

Requires role admin or recepcionista.

Returns all clients ordered by creation date descending. All query parameters are optional and can be combined.

GET /api/clients

Query Parameters

string

Case-insensitive substring search across nombre, apellidos, and telefono.

status

string

Filter by membership status. Accepted values: ACTIVO, VENCIDO, PENDIENTE.

plan

string

Filter by exact plan name (e.g. "Mensual", "Trimestral").

Success Response — 200 OK

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-...",
      "nombre": "Carlos",
      "apellidos": "Ramírez López",
      "genero": "Masculino",
      "telefono": "5512345678",
      "plan": "Mensual",
      "monto": 499,
      "metodoPago": "Efectivo",
      "status": "ACTIVO",
      "ultimaVisita": "09:32 AM",
      "vencimiento": "2025-08-15T06:00:00.000Z",
      "fotoUrl": null,
      "attendanceDate": "2025-07-15T15:32:00.000Z",
      "createdAt": "2025-07-01T14:00:00.000Z",
      "updatedAt": "2025-07-15T15:32:00.000Z"
    }
  ]
}

Error Responses

Status	Description
`401`	Missing or invalid Bearer token.
`403`	Authenticated user does not have the required role.
`500`	Internal server error.

Get Client by ID

Requires role admin or recepcionista.

Retrieves a single client record by its UUID.

GET /api/clients/:id

Path Parameters

string

required

The client’s UUID.

Success Response — 200 OK Returns a single Client object wrapped in data. Error Responses

Status	Description
`401`	Missing or invalid Bearer token.
`403`	Insufficient role.
`404`	No client found with the given ID.
`500`	Internal server error.

Create Client

Requires role admin or recepcionista.

Enrolls a new gym member. The plan value must match the name of an existing active plan. The system automatically calculates the vencimiento date from the plan’s period field (defaulting to 1 month if the period cannot be parsed). The new client’s status is set to ACTIVO immediately.

POST /api/clients

Request Body

nombre

string

required

Client’s first name.

apellidos

string

required

Client’s last name(s).

genero

string

required

Gender identity. Must be one of Masculino, Femenino, or Otro.

telefono

string

required

Phone number. Used as the primary search key; does not need to be unique.

plan

string

required

Exact name of an active membership plan. Returns 400 if the plan does not exist or is inactive.

monto

number

required

Amount paid for this enrollment (MXN).

metodoPago

string

required

Payment method. One of Efectivo, Tarjeta, or Transferencia.

fotoUrl

string

Optional URL to a profile photo.

Success Response — 201 Created

{
  "success": true,
  "data": {
    "id": "f7e6d5c4-...",
    "nombre": "Ana",
    "apellidos": "García Torres",
    "genero": "Femenino",
    "telefono": "5598765432",
    "plan": "Mensual",
    "monto": 499,
    "metodoPago": "Tarjeta",
    "status": "ACTIVO",
    "ultimaVisita": "--:--",
    "vencimiento": "2025-08-16T14:00:00.000Z",
    "fotoUrl": null,
    "attendanceDate": null,
    "createdAt": "2025-07-16T14:00:00.000Z",
    "updatedAt": "2025-07-16T14:00:00.000Z"
  }
}

Error Responses

Status	Description
`400`	Missing required fields, invalid `genero` value, or plan not found / inactive.
`401`	Missing or invalid Bearer token.
`403`	Insufficient role.
`500`	Internal server error.

curl -X POST https://api.example.com/api/clients \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Ana",
    "apellidos": "García Torres",
    "genero": "Femenino",
    "telefono": "5598765432",
    "plan": "Mensual",
    "monto": 499,
    "metodoPago": "Tarjeta"
  }'

Update Client

Requires role admin only. Receptionists cannot update client records.

Partially updates an existing client. Supply only the fields you wish to change; omitted fields retain their current values.

PUT /api/clients/:id

Path Parameters

string

required

UUID of the client to update.

Request Body (all fields optional)

nombre

string

Updated first name.

apellidos

string

Updated last name(s).

genero

string

Updated gender. One of Masculino, Femenino, Otro.

telefono

string

Updated phone number.

plan

string

Updated plan name. Does not recalculate vencimiento; use the /renew endpoint for a full renewal.

monto

number

Updated amount.

metodoPago

string

Updated payment method. One of Efectivo, Tarjeta, Transferencia.

fotoUrl

string | null

Pass a URL to set a new photo, or explicitly pass null to clear it.

Success Response — 200 OK Returns the full updated Client object inside data. Error Responses

Status	Description
`401`	Missing or invalid Bearer token.
`403`	User is not an admin.
`404`	No client found with the given ID.
`500`	Internal server error.

Delete Client

Requires role admin only. This is a hard delete — the client record and all associated attendance records (via onDelete: Cascade) are permanently removed.

Permanently deletes a client and all of their attendance history.

DELETE /api/clients/:id

Path Parameters

string

required

UUID of the client to delete.

Success Response — 200 OK

{
  "success": true,
  "message": "Cliente eliminado correctamente"
}

Error Responses

Status	Description
`401`	Missing or invalid Bearer token.
`403`	User is not an admin.
`404`	No client found with the given ID.
`500`	Internal server error.

Register Attendance

Requires role admin or recepcionista. No request body is needed.

Records a gym check-in for the specified client. Two guards run before the attendance is saved:

Membership expiry check — compares client.vencimiento against today’s date (time components are zeroed). Returns 403 if the membership has expired.
Duplicate attendance check — queries for an existing Attendance record whose fecha falls within [startOfToday, startOfTomorrow). Returns 400 if one already exists.

On success, both the ultimaVisita (formatted as HH:MM AM/PM, America/Mexico_City) and attendanceDate fields on the Client are updated in the same database transaction as the new Attendance record.

POST /api/clients/:id/attendance

Path Parameters

string

required

UUID of the client checking in.

Success Response — 200 OK

{
  "success": true,
  "data": {
    "ultimaVisita": "10:05 AM",
    "attendanceDate": "2025-07-16T16:05:00.000Z",
    "attendanceId": 482
  }
}

Error Responses

Status	Description
`400`	Client has already checked in today.
`401`	Missing or invalid Bearer token.
`403`	Client’s membership has expired.
`404`	No client found with the given ID.
`500`	Internal server error.

curl -X POST https://api.example.com/api/clients/a1b2c3d4-.../attendance \
  -H "Authorization: Bearer <token>"

Renew Membership

Requires role admin or recepcionista.

Renews a client’s membership to a new (or the same) plan. The new expiry date is calculated from whichever is later: the client’s current vencimiento (if it is still in the future) or today. This means a renewal applied before expiry stacks on top of the remaining time. The client’s status is set back to ACTIVO upon renewal.

POST /api/clients/:id/renew

Path Parameters

string

required

UUID of the client to renew.

Request Body

newPlan

string

required

Exact name of an active plan to assign. Returns 400 if the plan does not exist or is inactive.

amount

number

required

Amount paid for the renewal (MXN).

paymentMethod

string

required

Payment method. One of Efectivo, Tarjeta, or Transferencia.

Success Response — 200 OK

{
  "success": true,
  "data": {
    "plan": "Trimestral",
    "monto": 1200,
    "vencimiento": "2025-11-15T06:00:00.000Z",
    "status": "ACTIVO"
  }
}

Error Responses

Status	Description
`400`	Plan not found or inactive.
`401`	Missing or invalid Bearer token.
`403`	Insufficient role.
`404`	No client found with the given ID.
`500`	Internal server error.

Overview

Endpoints

REST API Reference: Client Management Endpoints

The Client Object

Endpoints

List Clients

Get Client by ID

Create Client

Update Client

Delete Client

Register Attendance

Renew Membership

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​The Client Object

​Endpoints

​List Clients

​Get Client by ID

​Create Client

​Update Client

​Delete Client

​Register Attendance

​Renew Membership

Build docs developers (and LLMs) love

The Client Object

Endpoints

List Clients

Get Client by ID

Create Client

Update Client

Delete Client

Register Attendance

Renew Membership