Sales API: Register and Manage Transactions

The /ventas endpoints handle all sales transactions — both in-store POS sales and online Tienda orders. The sale origin (POS vs WEB) is set automatically based on the caller’s role: a CLIENTE token produces a WEB origin, while ADMIN or EMPLEADO tokens produce a POS origin. The cajeroId is always extracted from the JWT; callers never supply it directly.

POST /api/ventas

Registers a new sale and decrements stock for each item in the transaction. Auth: ADMIN, EMPLEADO, or CLIENTE

Request Body (`VentaRequest`)

medioPago

string

required

Payment method. Must be one of the MedioPagoEnum values listed below.

items

array

required

List of line items. Must contain at least one entry.

Show ItemVentaRequest fields

productoId

Long

required

ID of the product to sell.

cantidad

Integer

required

Quantity to sell. Minimum 1.

clienteId

Long

Optional ID of the customer. Required for WEB sales when linking to a customer account; omit for anonymous POS transactions.

Response `201 Created`

Returns a VentaDetalleResponse.

Long

Internal sale identifier.

fecha

OffsetDateTime

Timestamp of the transaction in ISO-8601 format with timezone offset (Argentina/Buenos Aires, UTC-3).

subtotal

BigDecimal

Sum of all line item subtotals before discounts.

descuento

BigDecimal

Total discount applied to the sale.

total

BigDecimal

Final amount charged after discounts.

estado

string

Current sale state. One of COMPLETADA, ANULADA, PENDIENTE.

medioPago

string

Payment method used.

nombreCajero

string

Full name of the employee or admin who processed the sale.

origen

string

Sale channel: POS (in-store) or WEB (online Tienda).

comprobanteId

Long

ID of the associated fiscal receipt record. May be null if receipt generation is pending.

items

array

Line items included in the sale.

Show ItemVentaResponse fields

productoId

Long

ID of the sold product.

sku

string

SKU of the sold product.

nombreProducto

string

Product display name at time of sale.

cantidad

Integer

Units sold.

precioUnitario

BigDecimal

Unit price at time of sale.

subtotal

BigDecimal

Line subtotal (precioUnitario × cantidad).

curl -X POST http://localhost:8081/api/ventas \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "medioPago": "EFECTIVO",
    "items": [
      { "productoId": 12, "cantidad": 2 },
      { "productoId": 47, "cantidad": 1 }
    ]
  }'

GET /api/ventas

Lists all sales within a date range. Defaults to the last 30 days when no parameters are supplied. Dates are interpreted in the America/Argentina/Buenos_Aires timezone. Auth: ADMIN

Query Parameters

desde

date

Start date in ISO-8601 format (YYYY-MM-DD). Inclusive. Defaults to 30 days before today.

hasta

date

End date in ISO-8601 format (YYYY-MM-DD). Inclusive. Defaults to today.

Response `200 OK`

Returns an array of VentaResponse.

Long

Internal sale identifier.

fecha

OffsetDateTime

Transaction timestamp (ISO-8601 with timezone offset).

total

BigDecimal

Final charged amount.

estado

string

Sale state: COMPLETADA, ANULADA, or PENDIENTE.

medioPago

string

Payment method used.

nombreCajero

string

Name of the employee who processed the sale.

cantidadItems

Integer

Total number of line items in the sale.

origen

string

Sale channel: POS or WEB.

curl 'http://localhost:8081/api/ventas?desde=2025-01-01&hasta=2025-01-31' \
  -H 'Authorization: Bearer <token>'

GET /api/ventas/mis-compras

Returns the authenticated customer’s complete online order history. Only sales with origen = WEB linked to the caller’s user ID are returned. Auth: CLIENTE

Response `200 OK`

Returns an array of VentaResponse filtered to the caller’s userId. See GET /api/ventas for field descriptions.

GET /api/ventas/mis-ventas-hoy

Returns all sales processed by the authenticated employee during the current calendar day (Argentina timezone). Auth: EMPLEADO

Response `200 OK`

Returns an array of VentaResponse filtered to today’s sales for the calling employee.

GET /api/ventas/{id}

Returns summary information for a single sale. Auth: ADMIN or EMPLEADO

Path Parameters

Long

required

Internal sale identifier.

Response `200 OK`

Returns a VentaResponse.

GET /api/ventas/{id}/detalle

Returns the full details of a single sale, including the complete line-item list with product names, quantities, and per-unit prices. Auth: ADMIN or EMPLEADO

Path Parameters

Long

required

Internal sale identifier.

Response `200 OK`

Returns a VentaDetalleResponse. See POST /api/ventas for full field descriptions.

PUT /api/ventas/{id}/anular

Voids a sale by changing its estado to ANULADA. The sale record is retained for audit purposes. Auth: ADMIN

Path Parameters

Long

required

Internal sale identifier.

Response `200 OK`

Returns the updated VentaResponse with estado: "ANULADA".

Voiding a sale does not automatically reverse the stock change. If stock needs to be restored, perform a manual stock adjustment via POST /api/ajustes-stock after voiding.

Reference: Enumerations

`MedioPagoEnum` — Payment Methods

Value	Description
`EFECTIVO`	Cash payment
`DEBITO`	Debit card
`CREDITO`	Credit card
`MERCADOPAGO`	MercadoPago digital wallet

`EstadoVentaEnum` — Sale States

Value	Description
`PENDIENTE`	Sale created but not yet fully processed (e.g. awaiting payment confirmation)
`COMPLETADA`	Sale successfully finalised and stock decremented
`ANULADA`	Sale voided by an admin; stock is not automatically restored

`OrigenVentaEnum` — Sale Channel

Value	Description
`POS`	In-store sale processed by an `ADMIN` or `EMPLEADO`
`WEB`	Online order placed by a `CLIENTE` through the Tienda storefront

Overview

Endpoints

Sales API: Register and Manage Transactions

POST /api/ventas

Request Body (`VentaRequest`)

Response `201 Created`

GET /api/ventas

Query Parameters

Response `200 OK`

GET /api/ventas/mis-compras

Response `200 OK`

GET /api/ventas/mis-ventas-hoy

Response `200 OK`

GET /api/ventas/{id}

Path Parameters

Response `200 OK`

GET /api/ventas/{id}/detalle

Path Parameters

Response `200 OK`

PUT /api/ventas/{id}/anular

Path Parameters

Response `200 OK`

Reference: Enumerations

`MedioPagoEnum` — Payment Methods

`EstadoVentaEnum` — Sale States

`OrigenVentaEnum` — Sale Channel

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​POST /api/ventas

​Request Body (VentaRequest)

​Response 201 Created

​GET /api/ventas

​Query Parameters

​Response 200 OK

​GET /api/ventas/mis-compras

​Response 200 OK

​GET /api/ventas/mis-ventas-hoy

​Response 200 OK

​GET /api/ventas/{id}

​Path Parameters

​Response 200 OK

​GET /api/ventas/{id}/detalle

​Path Parameters

​Response 200 OK

​PUT /api/ventas/{id}/anular

​Path Parameters

​Response 200 OK

​Reference: Enumerations

​MedioPagoEnum — Payment Methods

​EstadoVentaEnum — Sale States

​OrigenVentaEnum — Sale Channel

Build docs developers (and LLMs) love

POST /api/ventas

Request Body (`VentaRequest`)

Response `201 Created`

GET /api/ventas

Query Parameters

Response `200 OK`

GET /api/ventas/mis-compras

Response `200 OK`

GET /api/ventas/mis-ventas-hoy

Response `200 OK`

GET /api/ventas/{id}

Path Parameters

Response `200 OK`

GET /api/ventas/{id}/detalle

Path Parameters

Response `200 OK`

PUT /api/ventas/{id}/anular

Path Parameters

Response `200 OK`

Reference: Enumerations

`MedioPagoEnum` — Payment Methods

`EstadoVentaEnum` — Sale States

`OrigenVentaEnum` — Sale Channel