REST API Reference: Transaction History Endpoints

The Transactions API records every financial event that occurs at the gym — membership payments and point-of-sale product sales alike. All three endpoints require a valid Bearer token; no admin privilege is needed, allowing reception staff to create and query records during their shift. Date-range filters are applied against the createdAt UTC timestamp adjusted to the America/Mexico_City (UTC−6) timezone so that a filter for 2024-06-15 captures the full local business day, not a UTC-offset slice.

Transaction Object

Every endpoint that returns transaction data uses this shape.

integer

required

Auto-incremented primary key.

fecha

string

required

Display date stored as a formatted string, e.g. "15/jun/2024". Set automatically at creation time in the Mexico City timezone. Not an ISO timestamp.

hora

string

required

Display time stored as a formatted 12-hour string, e.g. "03:45 PM". Set automatically at creation time in the Mexico City timezone.

nombre

string

required

First name of the payer. For membership transactions this is pulled from the linked client record. For product sales it defaults to "Venta".

apellidos

string

required

Last name of the payer. Defaults to "Mostrador" for walk-in product sales.

clienteId

string | null

UUID of the linked Client record. Present for membership transactions; null for product sales.

concepto

string

required

Human-readable description. For product sales this is auto-built from product names, e.g. "Proteína Whey (x2), Agua 500ml".

monto

number

required

Transaction amount in MXN, returned as a JavaScript number (the underlying Decimal is coerced).

metodo

"Efectivo" | "Tarjeta" | "Transferencia"

required

Payment method used.

tipo

"MEMBRESIA" | "PRODUCTO"

required

Transaction category.

createdAt

ISO 8601 datetime

required

Actual UTC timestamp written by the database. This is the field used for all date-range filtering.

user

object

Present only on GET /api/transactions (not /history). Contains the staff account that created the record.

Show user fields

integer

Staff user ID.

string

Staff user email.

role

"admin" | "recepcionista"

Staff user role.

fecha and hora are stored as pre-formatted display strings, not ISO timestamps. Use createdAt for any programmatic date arithmetic or filtering.

GET /api/transactions

Retrieve all transactions with optional filters. Results are ordered by createdAt descending and include the user relation. Auth: Authorization: Bearer <token> — any authenticated role

Query Parameters

tipo

"MEMBRESIA" | "PRODUCTO"

Filter by transaction category.

metodo

"Efectivo" | "Tarjeta" | "Transferencia"

Filter by payment method.

fechaInicio

string (YYYY-MM-DD)

Start of the date range (inclusive). Interpreted as midnight Mexico City time (UTC−6), so 2024-06-15 maps to 2024-06-15T06:00:00Z through 2024-06-16T05:59:59.999Z.

fechaFin

string (YYYY-MM-DD)

End of the date range (inclusive). Adjusts the upper bound of createdAt to end-of-day Mexico City time for the given date. Ignored if equal to fechaInicio.

Success Response — 200

{
  "success": true,
  "data": [
    {
      "id": 42,
      "fecha": "15/jun/2024",
      "hora": "10:30 AM",
      "nombre": "Carlos",
      "apellidos": "Mendoza",
      "clienteId": "a1b2c3d4-...",
      "concepto": "Membresía Mensual",
      "monto": 500,
      "metodo": "Tarjeta",
      "tipo": "MEMBRESIA",
      "createdAt": "2024-06-15T16:30:00.000Z",
      "user": {
        "id": 3,
        "email": "recepcion@spartansgym.com",
        "role": "recepcionista"
      }
    }
  ]
}

Error Responses

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

Example — filtered request

curl -X GET \
  "https://api.spartansgym.com/api/transactions?tipo=MEMBRESIA&fechaInicio=2024-06-01&fechaFin=2024-06-30" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

GET /api/transactions/history

Returns the last 100 transactions ordered by createdAt descending. No query parameters are accepted. The user relation is not included in this response — use GET /api/transactions when you need staff attribution. Auth: Authorization: Bearer <token> — any authenticated role

Success Response — 200

{
  "success": true,
  "data": [
    {
      "id": 99,
      "fecha": "15/jun/2024",
      "hora": "02:15 PM",
      "nombre": "Venta",
      "apellidos": "Mostrador",
      "clienteId": null,
      "concepto": "Proteína Whey (x1), Agua 500ml (x2)",
      "monto": 320,
      "metodo": "Efectivo",
      "tipo": "PRODUCTO",
      "createdAt": "2024-06-15T20:15:00.000Z"
    }
  ]
}

Error Responses

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

POST /api/transactions

Create a new transaction. The fecha and hora fields are set automatically using the current Mexico City time — do not pass them in the request body. Auth: Authorization: Bearer <token> — any authenticated role

Request Body

tipo

"MEMBRESIA" | "PRODUCTO"

required

Determines the transaction category and influences how nombre, apellidos, and concepto are resolved.

metodo

"Efectivo" | "Tarjeta" | "Transferencia"

required

Payment method used.

monto

number

required

Total transaction amount in MXN.

clienteId

string (UUID)

Required for tipo: "MEMBRESIA". The client’s id is used to look up their nombre and apellidos for storage on the transaction.

concepto

string

Optional free-text description. For tipo: "PRODUCTO" this field is overwritten by the auto-generated product name list derived from the productos array.

productos

array

Required for tipo: "PRODUCTO". Each item describes a product being sold.

Show productos item fields

integer

required

Product ID from the products table.

quantity

integer

required

Units sold. The product’s stock is decremented by this amount.

For product sales, pass concepto only as a fallback. The server overwrites it with the concatenated product names (e.g. "Proteína Whey (x2), Agua 500ml"), including a (xN) quantity suffix whenever quantity > 1.

Server-side behaviour by type

PRODUCTO — iterates productos, fetches each product by id, appends its name (with quantity suffix) to build concepto, and decrements stock via Product.update. nombre defaults to "Venta", apellidos to "Mostrador". MEMBRESIA — fetches the Client by clienteId and copies nombre / apellidos from the client record. concepto is taken from the request body as-is.

Success Response — 201

{
  "success": true,
  "data": {
    "id": 101,
    "fecha": "15/jun/2024",
    "hora": "11:00 AM",
    "nombre": "Ana",
    "apellidos": "Torres",
    "clienteId": "f9e8d7c6-...",
    "concepto": "Membresía Mensual",
    "monto": 500,
    "metodo": "Transferencia",
    "tipo": "MEMBRESIA",
    "createdAt": "2024-06-15T17:00:00.000Z"
  }
}

Error Responses

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

Example — membership payment

curl -X POST https://api.spartansgym.com/api/transactions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": "MEMBRESIA",
    "metodo": "Tarjeta",
    "monto": 500,
    "clienteId": "f9e8d7c6-b5a4-4321-abcd-ef1234567890",
    "concepto": "Membresía Mensual"
  }'

Product stock is decremented immediately and non-atomically per item. If the server encounters an error mid-loop, previously decremented stock is not rolled back. Validate stock availability on the client before calling this endpoint.

Overview

Endpoints

REST API Reference: Transaction History Endpoints

Transaction Object

GET /api/transactions

Query Parameters

Success Response — 200

Error Responses

Example — filtered request

GET /api/transactions/history

Success Response — 200

Error Responses

POST /api/transactions

Request Body

Server-side behaviour by type

Success Response — 201

Error Responses

Example — membership payment

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Transaction Object

​GET /api/transactions

​Query Parameters

​Success Response — 200

​Error Responses

​Example — filtered request

​GET /api/transactions/history

​Success Response — 200

​Error Responses

​POST /api/transactions

​Request Body

​Server-side behaviour by type

​Success Response — 201

​Error Responses

​Example — membership payment

Build docs developers (and LLMs) love

Transaction Object

GET /api/transactions

Query Parameters

Success Response — 200

Error Responses

Example — filtered request

GET /api/transactions/history

Success Response — 200

Error Responses

POST /api/transactions

Request Body

Server-side behaviour by type

Success Response — 201

Error Responses

Example — membership payment