Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Eleazarguitar18/kantuta_pos_front/llms.txt

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

The Sales module is the primary transactional engine of Kantuta POS. When a sale is created, the backend automatically calculates line-item subtotals, sums the total, and decrements stock_actual for every product in the detalles array — all in a single atomic operation. Sales can be in one of three states: COMPLETADA, ANULADA, or EDITADA, which you can update via the PATCH endpoint. All routes require a valid Bearer Token JWT in the Authorization header.

​
Interface Reference

export interface BaseEntityAudit {
  estado: boolean;
  id_user_create: number | null;
  id_user_update?: number | null;
  created_at: string; // ISO Date String
  updated_at: string; // ISO Date String
}

export interface DetalleVenta extends BaseEntityAudit {
  id: number;
  cantidad: number;
  precio_unitario: number;
  subtotal: number;   // Calculated: cantidad * precio_unitario
  id_venta: number;
  id_producto: number;
  producto?: Producto; // Included in GET responses
}

export interface Venta extends BaseEntityAudit {
  id: number;
  total: number;
  metodo_pago: "EFECTIVO" | "QR" | "TRANSFERENCIA";
  fecha: string;               // ISO Date String
  id_sesion_caja: number;
  estado_venta: "COMPLETADA" | "ANULADA" | "EDITADA";
  motivo_edicion: string | null;
  fecha_modificacion: string;  // ISO Date String
  detalles: DetalleVenta[];
}

​
POST /ventas

Creates a new sale, computes subtotals and the grand total, and decrements stock_actual for each product listed in detalles. Returns the complete Venta object with its computed total and saved line items. Authentication: Required — Authorization: Bearer <access_token>

​
Request Body

​
metodo_pago
string
required
Payment method for this sale. One of: "EFECTIVO", "QR", "TRANSFERENCIA".
​
id_sesion_caja
number
required
ID of the active cash register session where this payment is received. The session must be in ABIERTA state.
​
detalles
DetalleVentaInput[]
required
Array of line items for the sale. Must contain at least one entry.
​
id_user_create
number
required
ID of the authenticated user (cashier) creating this sale. Used for audit tracking.

​
Response Fields

​
id
number
required
Auto-generated unique identifier for the sale.
​
total
number
required
Grand total calculated by the backend as the sum of all (cantidad * precio_unitario) subtotals.
​
metodo_pago
string
required
Payment method used. One of: EFECTIVO, QR, TRANSFERENCIA.
​
fecha
string
required
ISO 8601 timestamp of when the sale was recorded.
​
id_sesion_caja
number
required
Cash session that received the payment.
​
estado_venta
string
required
Initial state of the sale. Defaults to "COMPLETADA" upon creation.
​
motivo_edicion
string | null
Reason for any modification. null on initial creation.
​
fecha_modificacion
string
required
ISO 8601 timestamp of the last status change.
​
detalles
DetalleVenta[]
required
Saved line items, each with a computed subtotal.
​
estado
boolean
required
Active flag, defaults to true.
​
created_at
string
required
ISO 8601 creation timestamp.
curl --request POST \
  --url http://localhost:3000/ventas \
  --header "Authorization: Bearer <access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "metodo_pago": "EFECTIVO",
    "id_sesion_caja": 5,
    "detalles": [
      {
        "id_producto": 7,
        "cantidad": 2,
        "precio_unitario": 5.50
      },
      {
        "id_producto": 12,
        "cantidad": 1,
        "precio_unitario": 15.00
      }
    ],
    "id_user_create": 1
  }'

​
GET /ventas

Returns the full sales history. Every Venta record includes the detalles array with line-item details. Authentication: Required — Authorization: Bearer <access_token>

​
Response Fields

​
id
number
required
Unique identifier of the sale.
​
total
number
required
Grand total of the sale.
​
metodo_pago
string
required
Payment method: EFECTIVO, QR, or TRANSFERENCIA.
​
fecha
string
required
ISO 8601 date the sale was made.
​
id_sesion_caja
number
required
Cash session associated with this sale.
​
estado_venta
string
required
Current state: COMPLETADA, ANULADA, or EDITADA.
​
motivo_edicion
string | null
Reason provided when the sale was edited or cancelled.
​
detalles
DetalleVenta[]
required
Line items included in this sale.
curl --request GET \
  --url http://localhost:3000/ventas \
  --header "Authorization: Bearer <access_token>"

​
GET /ventas/:id

Fetches a single sale by its numeric ID, including the full detalles array. Authentication: Required — Authorization: Bearer <access_token>

​
Path Parameters

​
id
number
required
The unique identifier of the sale to retrieve.

​
Response Fields

​
id
number
required
Unique identifier of the sale.
​
total
number
required
Grand total of the sale.
​
metodo_pago
string
required
Payment method used.
​
fecha
string
required
ISO 8601 timestamp of the sale.
​
estado_venta
string
required
Current state: COMPLETADA, ANULADA, or EDITADA.
​
motivo_edicion
string | null
Edit or cancellation reason, or null.
​
fecha_modificacion
string
required
ISO 8601 timestamp of the most recent state change.
​
detalles
DetalleVenta[]
required
Line items for this sale, each with cantidad, precio_unitario, subtotal, and an optional nested producto object.
curl --request GET \
  --url http://localhost:3000/ventas/42 \
  --header "Authorization: Bearer <access_token>"

​
PATCH /ventas/:id

Updates or cancels an existing sale. Use this endpoint to change the payment method, mark a sale as ANULADA or EDITADA, or record an edit reason. All fields are optional. Authentication: Required — Authorization: Bearer <access_token>

​
Path Parameters

​
id
number
required
The unique identifier of the sale to update.

​
Request Body

​
metodo_pago
string
Updated payment method. One of: "EFECTIVO", "QR", "TRANSFERENCIA".
​
id_sesion_caja
number
Updated cash session reference.
​
estado_venta
string
New state for the sale. One of: "COMPLETADA", "ANULADA", "EDITADA". Use "ANULADA" to cancel a sale.
​
motivo_edicion
string
A free-text explanation for the change. Required by convention when setting estado_venta to "ANULADA" or "EDITADA".
​
id_user_update
number
ID of the authenticated user performing this update. Used for audit tracking.

​
Response Fields

​
id
number
required
Unique identifier of the updated sale.
​
total
number
required
Grand total of the sale (unchanged by a status update).
​
metodo_pago
string
required
Current payment method after the update.
​
estado_venta
string
required
Updated state: COMPLETADA, ANULADA, or EDITADA.
​
motivo_edicion
string | null
The recorded reason for this modification.
​
fecha_modificacion
string
required
ISO 8601 timestamp updated to reflect the time of this change.
​
id_user_update
number | null
ID of the user who performed this update.
​
detalles
DetalleVenta[]
required
Unchanged line items of the sale.
curl --request PATCH \
  --url http://localhost:3000/ventas/42 \
  --header "Authorization: Bearer <access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "estado_venta": "ANULADA",
    "motivo_edicion": "Cliente solicitó devolución del producto",
    "id_user_update": 1
  }'

Build docs developers (and LLMs) love

Get started for freeTalk to us