Cash Registers API: Sessions, Movements, and Reconciliation

The Cash Registers module is the backbone of every cashier shift in Kantuta POS. A Caja (physical register) holds configuration like its name and operational specialty. A SesionCaja represents a single cashier turn — it opens with a declared starting balance and closes with a physical count. When the session closes, the backend automatically computes monto_final_teorico from all tracked movements and derives the diferencia for reconciliation. MovimientoCaja records any ad-hoc cash in-flows or out-flows during the session.

TypeScript Interfaces

export interface Caja extends BaseEntityAudit {
  id: number;
  nombre: string;
  especialidad: "SOLO_VENTAS" | "SOLO_AGENTES" | "MIXTA";
  sesiones?: SesionCaja[];
  saldo: number;
}

export interface SesionCaja extends BaseEntityAudit {
  id: number;
  monto_inicial: number;
  monto_final_teorico: number | null; // Computed by backend on close
  monto_final_real: number | null;    // Submitted by cashier on close
  diferencia: number | null;          // monto_final_real - monto_final_teorico
  estado_sesion: "ABIERTA" | "CERRADA";
  fecha_apertura: string;             // ISO Date String
  fecha_cierre: string | null;        // ISO Date String
  id_caja: number;
  caja?: Caja;
  id_usuario: number;
}

export interface MovimientoCaja extends BaseEntityAudit {
  id: number;
  tipo: "INGRESO" | "EGRESO";
  monto: number;
  motivo: string;
  fecha: string; // ISO Date String
  id_sesion_caja: number;
}

Endpoints

List All Cajas

curl -X GET http://localhost:3000/cajas \
  -H "Authorization: Bearer <access_token>"

GET /cajas — Returns all active cash register records. Inactive registers (soft-deleted) are filtered automatically. Response: Caja[]

Create a Caja

POST /cajas — Creates a new physical cash register.

nombre

string

required

Display name for the register. Minimum 3 characters.

especialidad

string

required

Determines which operations the register accepts. One of: SOLO_VENTAS, SOLO_AGENTES, or MIXTA.

saldo

number

Optional opening balance to set on the register record. Separate from the session’s monto_inicial.

id_user_create

number

ID of the user creating the record. Injected automatically by the frontend service from the logged-in user’s session.

curl -X POST http://localhost:3000/cajas \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Caja Principal",
    "especialidad": "MIXTA",
    "id_user_create": 1
  }'

Response: Caja

Get Caja by ID

GET /cajas/:id — Returns a single register with its full session history.

curl -X GET http://localhost:3000/cajas/1 \
  -H "Authorization: Bearer <access_token>"

Response: Caja — includes the sesiones array with all historical sessions.

Update a Caja

PATCH /cajas/:id — Partially updates a cash register. Accepts any subset of CrearCajaRequest fields.

nombre

string

New display name for the register.

especialidad

string

Updated specialty: SOLO_VENTAS, SOLO_AGENTES, or MIXTA.

curl -X PATCH http://localhost:3000/cajas/1 \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "nombre": "Caja Ventas Norte" }'

Response: Caja (updated object)

Delete a Caja (Soft Delete)

DELETE /cajas/:id?id_user_update=N — Marks the register as inactive. The record is not removed from the database.

id_user_update

number

required

ID of the user performing the deletion. Required for audit trail.

curl -X DELETE "http://localhost:3000/cajas/1?id_user_update=2" \
  -H "Authorization: Bearer <access_token>"

Response: void

Get Active Session for a User

GET /cajas/sesion-activa/:userId — Returns the currently open session assigned to a given cashier user.

curl -X GET http://localhost:3000/cajas/sesion-activa/5 \
  -H "Authorization: Bearer <access_token>"

Response: SesionCaja with estado_sesion: "ABIERTA", or null if no active session exists.

Open a Session

POST /cajas/abrir — Opens a new cashier session (starts a shift). Only one session per user can be open at a time.

id_caja

number

required

ID of the physical register to open.

monto_inicial

number

required

The starting cash balance declared by the cashier (used as the base for theoretical reconciliation).

id_usuario

number

required

ID of the cashier opening the session.

id_user_create

number

required

Audit user ID (usually the same as id_usuario). Auto-injected by the frontend service.

curl -X POST http://localhost:3000/cajas/abrir \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id_caja": 1,
    "monto_inicial": 500.00,
    "id_usuario": 5,
    "id_user_create": 5
  }'

Response: SesionCaja with estado_sesion: "ABIERTA" and a populated fecha_apertura.

Close a Session (Reconciliation)

PATCH /cajas/sesion/:id/cerrar — Closes an open session and triggers the backend reconciliation calculation.

monto_final_real

number

required

The physical cash count performed by the cashier at end-of-shift.

id_user_update

number

required

ID of the user closing the session. Auto-injected by the frontend service.

curl -X PATCH http://localhost:3000/cajas/sesion/12/cerrar \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "monto_final_real": 1240.50,
    "id_user_update": 5
  }'

Response: SesionCaja — The returned object includes the backend-computed fields:

monto_final_teorico

number

Calculated by the backend as: monto_inicial + sum of all INGRESO movements − sum of all EGRESO movements recorded during the session.

diferencia

number

Computed as monto_final_real − monto_final_teorico. A positive value indicates a surplus; a negative value indicates a shortage.

estado_sesion

string

Set to "CERRADA" upon successful close.

fecha_cierre

string

ISO 8601 timestamp of when the session was closed.

The reconciliation formula is: Teorico = monto_inicial + Σ INGRESOS − Σ EGRESOS. The diferencia is the discrepancy between what should be in the register and what was physically counted. A value of 0.00 indicates a perfect balance.

Get Session Balance

GET /cajas/sesion/:id/balance — Retrieves a real-time balance summary for an open session, including all movements registered so far.

curl -X GET http://localhost:3000/cajas/sesion/12/balance \
  -H "Authorization: Bearer <access_token>"

Register an Internal Movement

POST /cajas/movimiento — Records an ad-hoc cash in-flow (INGRESO) or out-flow (EGRESO) within an active session. These movements are factored into the theoretical balance at close.

tipo

string

required

Movement direction: INGRESO (cash in) or EGRESO (cash out).

monto

number

required

Amount of the movement. Minimum value: 0.10.

motivo

string

required

Free-text justification for the movement (e.g., “Pago de servicios”, “Fondo de cambio adicional”).

id_sesion_caja

number

required

ID of the active session to which this movement belongs.

id_user_create

number

required

Audit user ID. Auto-injected by the frontend service.

curl -X POST http://localhost:3000/cajas/movimiento \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": "EGRESO",
    "monto": 50.00,
    "motivo": "Pago de servicio de limpieza",
    "id_sesion_caja": 12,
    "id_user_create": 5
  }'

Response: MovimientoCaja

Reconciliation Logic

When PATCH /cajas/sesion/:id/cerrar is called, the backend executes the following reconciliation steps:

Fetch all movements — Retrieves every MovimientoCaja linked to the session’s id.
Sum inflows — Adds all movements with tipo: "INGRESO".
Sum outflows — Adds all movements with tipo: "EGRESO".
Compute theoretical balance — monto_final_teorico = monto_inicial + Σ INGRESOS − Σ EGRESOS.
Compute difference — diferencia = monto_final_real − monto_final_teorico.
Set session state — estado_sesion is set to "CERRADA" and fecha_cierre is stamped.

A diferencia of 0.00 means the physical count matches the system exactly. Positive values indicate a surplus (more cash than expected); negative values indicate a shortage.

Overview

Endpoints

Data Models

Cash Registers API: Sessions, Movements, and Reconciliation

TypeScript Interfaces

Endpoints

List All Cajas

Create a Caja

Get Caja by ID

Update a Caja

Delete a Caja (Soft Delete)

Get Active Session for a User

Open a Session

Close a Session (Reconciliation)

Get Session Balance

Register an Internal Movement

Reconciliation Logic

Build docs developers (and LLMs) love

Overview

Endpoints

Data Models

Documentation Index

​TypeScript Interfaces

​Endpoints

​List All Cajas

​Create a Caja

​Get Caja by ID

​Update a Caja

​Delete a Caja (Soft Delete)

​Get Active Session for a User

​Open a Session

​Close a Session (Reconciliation)

​Get Session Balance

​Register an Internal Movement

​Reconciliation Logic

Build docs developers (and LLMs) love

TypeScript Interfaces

Endpoints

List All Cajas

Create a Caja

Get Caja by ID

Update a Caja

Delete a Caja (Soft Delete)

Get Active Session for a User

Open a Session

Close a Session (Reconciliation)

Get Session Balance

Register an Internal Movement

Reconciliation Logic