Cajas API: Cash Register and Session Management

The Cajas API is the backbone of Kantuta POS’s financial accountability system. It governs the entire lifecycle of a physical cash register — from initial creation and configuration, through the opening and closing of operator shifts (sessions), to the recording of ad-hoc cash movements such as petty cash disbursements. Every sale and agent transaction is tied to an active session, making session management a prerequisite for most POS operations.

All endpoints in this module require a valid Authorization: Bearer <access_token> header. Most endpoints are accessible to both Administrador and Operador roles unless otherwise noted.

Physical Cajas

List All Cajas

Authorization

string

required

Bearer token obtained from the auth endpoint.

GET /cajas

Returns an array of all registered physical cash registers, including their current configuration and specialty.

Response

number

Unique identifier of the caja.

nombre

string

Human-readable name for the cash register (e.g., "Caja 01 - Ventas").

especialidad

string

Operational mode: SOLO_VENTAS, SOLO_AGENTES, or MIXTA.

saldo

number

Base balance assigned at creation (immutable reference amount).

sesiones

SesionCaja[]

Historical list of sessions associated with this caja.

Create a Caja

This endpoint is restricted to the Administrador role only.

POST /cajas

Creates a new physical cash register. Each caja can be configured to accept only sales, only agent transactions, or both.

Request Body

nombre

string

required

Display name for the caja. Minimum 3 characters (e.g., "Caja 02 - Agentes").

especialidad

string

required

Operational mode for the caja. One of: SOLO_VENTAS, SOLO_AGENTES, MIXTA.

saldo

number

required

Base balance assigned to this register (minimum 0). Used as the starting reference amount for reconciliation.

id_user_create

number

ID of the administrator creating this record (for audit trail).

curl -X POST https://api.example.com/cajas \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Caja 03 - Mixta",
    "especialidad": "MIXTA",
    "saldo": 500.00,
    "id_user_create": 1
  }'

Get a Single Caja

GET /cajas/:id

Returns a specific caja by its ID, including its complete session history.

Path Parameters

number

required

The numeric ID of the caja.

Update a Caja

PATCH /cajas/:id

Partially updates a caja’s properties (e.g., rename it or change its specialty).

Path Parameters

number

required

The numeric ID of the caja to update.

Request Body

All fields are optional. Provide only the fields you want to change.

nombre

string

New display name for the caja.

especialidad

string

New operational mode: SOLO_VENTAS, SOLO_AGENTES, or MIXTA.

id_user_update

number

ID of the user performing the update (audit trail).

Delete a Caja (Soft Delete)

DELETE /cajas/:id?id_user_update=N

Soft-deletes a caja, marking it as inactive without removing it from the database. The id_user_update query parameter is required to record who performed the deletion.

Path Parameters

number

required

The numeric ID of the caja to delete.

Query Parameters

id_user_update

number

required

ID of the administrator performing the soft delete.

curl -X DELETE "https://api.example.com/cajas/3?id_user_update=1" \
  -H "Authorization: Bearer <access_token>"

Sessions

Open a Session (Abrir Caja)

POST /cajas/abrir

Opens a new shift session on a physical caja, assigning it to a specific user/operator. An active session is required before any sales or agent transactions can be processed.

Accessible by both Administrador and Operador roles. For Operador users, monto_inicial is optional — it may be set by management policy.

Request Body

id_caja

number

required

ID of the physical cash register to open.

monto_inicial

number

Starting cash amount placed in the register for making change. Minimum 0. Optional for Operadores.

id_usuario

number

required

ID of the user (cashier) who will operate this session.

id_user_create

number

required

ID of the user creating this record (for audit trail — often the same as id_usuario).

curl -X POST https://api.example.com/cajas/abrir \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id_caja": 1,
    "monto_inicial": 200.00,
    "id_usuario": 2,
    "id_user_create": 2
  }'

Response

Returns a SesionCaja object with estado_sesion: "ABIERTA".

number

Unique session identifier.

monto_inicial

number

Opening cash amount.

estado_sesion

string

Session status. Will be "ABIERTA" on successful open.

fecha_apertura

string

ISO 8601 timestamp of when the session was opened.

id_caja

number

ID of the associated physical caja.

id_usuario

number

ID of the operator assigned to this session.

Close a Session (Cerrar Caja)

PATCH /cajas/sesion/:id/cerrar

Closes an active session. The operator provides the physically counted cash (monto_final_real). The backend automatically calculates the theoretical closing balance (monto_final_teorico) from all recorded transactions and computes the diferencia (overage or shortage).

Path Parameters

number

required

The numeric ID of the session to close.

Request Body

monto_final_real

number

required

The physical cash amount counted by the operator at closing. Minimum 0.

id_user_update

number

required

ID of the user closing the session (audit trail).

curl -X PATCH https://api.example.com/cajas/sesion/101/cerrar \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "monto_final_real": 1450.80,
    "id_user_update": 1
  }'

Response

Returns the updated SesionCaja with estado_sesion: "CERRADA".

estado_sesion

string

"CERRADA" after successful close.

monto_final_teorico

number

Backend-calculated expected closing balance (monto_inicial + all ingresos − all egresos + ventas + agentes).

monto_final_real

number

Physical cash counted by the operator.

diferencia

number

monto_final_real − monto_final_teorico. Positive = surplus, negative = shortage.

fecha_cierre

string

ISO 8601 timestamp of session closure.

Get Active Session for a User

GET /cajas/sesion-activa/:id_usuario

Retrieves the currently open session assigned to a specific user. Useful for determining whether an operator already has an active shift before starting a new one.

Path Parameters

id_usuario

number

required

The user ID to query.

Get Session Balance

GET /cajas/sesion/:id/balance

Returns the current running balance of an active session, reflecting all transactions recorded so far during the shift.

Path Parameters

number

required

The numeric ID of the session.

Cash Movements

Record a Movement

POST /cajas/movimiento

Records a manual cash movement (ingress or egress) on an active session. Use this for petty cash disbursements, cash additions between sessions, or any non-sale/non-agent cash flow that needs to be tracked.

Request Body

tipo

string

required

Direction of the cash flow: INGRESO (cash in) or EGRESO (cash out).

monto

number

required

Amount of the movement. Minimum 0.10.

motivo

string

required

Reason or description for the movement (e.g., "Compra de bolsas para empaque").

id_sesion_caja

number

required

ID of the active session where this movement is recorded.

id_user_create

number

required

ID of the user recording the movement (audit trail).

curl -X POST https://api.example.com/cajas/movimiento \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": "EGRESO",
    "monto": 25.00,
    "motivo": "Compra de bolsas para empaque",
    "id_sesion_caja": 101,
    "id_user_create": 2
  }'

Response — `MovimientoCaja`

number

Unique movement identifier.

tipo

string

"INGRESO" or "EGRESO".

monto

number

Amount of the movement.

motivo

string

Reason recorded for the movement.

fecha

string

ISO 8601 timestamp of when the movement was registered.

id_sesion_caja

number

ID of the session this movement belongs to.

TypeScript Interfaces

interface SesionCaja {
  id: number;
  monto_inicial: number;
  monto_final_teorico: number | null;  // null while session is ABIERTA
  monto_final_real: number | null;     // null while session is ABIERTA
  diferencia: number | null;           // null while session is ABIERTA
  estado_sesion: 'ABIERTA' | 'CERRADA';
  fecha_apertura: string;              // ISO 8601 timestamp
  fecha_cierre: string | null;         // null while session is ABIERTA
  id_caja: number;
  id_usuario: number;
}

interface MovimientoCaja {
  id: number;
  tipo: 'INGRESO' | 'EGRESO';
  monto: number;
  motivo: string;
  fecha: string;                       // ISO 8601 timestamp
  id_sesion_caja: number;
}

interface Caja {
  id: number;
  nombre: string;
  especialidad: 'SOLO_VENTAS' | 'SOLO_AGENTES' | 'MIXTA';
  saldo: number;
  sesiones: SesionCaja[];
}

Role Restrictions Summary

Endpoint	Administrador	Operador
`GET /cajas`	✅	✅
`POST /cajas`	✅	❌
`GET /cajas/:id`	✅	✅
`PATCH /cajas/:id`	✅	✅
`DELETE /cajas/:id`	✅	✅
`POST /cajas/abrir`	✅	✅
`PATCH /cajas/sesion/:id/cerrar`	✅	✅
`GET /cajas/sesion-activa/:id`	✅	✅
`GET /cajas/sesion/:id/balance`	✅	✅
`POST /cajas/movimiento`	✅	✅

Authentication

Users & People

Inventory

Operations

Integrations

Cajas API: Cash Register and Session Management

Physical Cajas

List All Cajas

Response

Create a Caja

Request Body

Get a Single Caja

Path Parameters

Update a Caja

Path Parameters

Request Body

Delete a Caja (Soft Delete)

Path Parameters

Query Parameters

Sessions

Open a Session (Abrir Caja)

Request Body

Response

Close a Session (Cerrar Caja)

Path Parameters

Request Body

Response

Get Active Session for a User

Path Parameters

Get Session Balance

Path Parameters

Cash Movements

Record a Movement

Request Body

Response — `MovimientoCaja`

TypeScript Interfaces

Role Restrictions Summary

Build docs developers (and LLMs) love

Authentication

Users & People

Inventory

Operations

Integrations

Documentation Index

​Physical Cajas

​List All Cajas

​Response

​Create a Caja

​Request Body

​Get a Single Caja

​Path Parameters

​Update a Caja

​Path Parameters

​Request Body

​Delete a Caja (Soft Delete)

​Path Parameters

​Query Parameters

​Sessions

​Open a Session (Abrir Caja)

​Request Body

​Response

​Close a Session (Cerrar Caja)

​Path Parameters

​Request Body

​Response

​Get Active Session for a User

​Path Parameters

​Get Session Balance

​Path Parameters

​Cash Movements

​Record a Movement

​Request Body

​Response — MovimientoCaja

​TypeScript Interfaces

​Role Restrictions Summary

Build docs developers (and LLMs) love

Physical Cajas

List All Cajas

Response

Create a Caja

Request Body

Get a Single Caja

Path Parameters

Update a Caja

Path Parameters

Request Body

Delete a Caja (Soft Delete)

Path Parameters

Query Parameters

Sessions

Open a Session (Abrir Caja)

Request Body

Response

Close a Session (Cerrar Caja)

Path Parameters

Request Body

Response

Get Active Session for a User

Path Parameters

Get Session Balance

Path Parameters

Cash Movements

Record a Movement

Request Body

Response — `MovimientoCaja`

TypeScript Interfaces

Role Restrictions Summary