Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/15aozzz/Lab-Nova-Salud/llms.txt

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

The sales endpoints cover the two core operations of the register: recording a completed sale with one or more line items, and fetching a previously recorded sale by its internal ID. Both endpoints delegate to stored procedures; the backend executes no raw SQL.
All routes except POST /api/auth/login require a valid JWT in the Authorization: Bearer <token> header.

​
POST /api/ventas/registrar

Registers a complete sale — header and line items — in a single database transaction. Internally calls sp_registrar_venta, which generates the document number, decrements stock via triggers, and rolls back automatically if any item is out of stock.

​
Request body

​
id_tipo_comprobante
number
required
Document type ID (e.g., 1 for Boleta, 2 for Factura). Obtain valid IDs from GET /api/comprobantes/tipos.
​
id_usuario
number
required
ID of the cashier registering the sale.
​
total
number
required
Grand total of the sale. Must be greater than 0.
​
detalle
object[]
required
Line items array. Must contain at least one item.
​
numero_documento_cliente
string
Customer DNI or RUC. Optional for anonymous sales.
​
nombres_razon_social
string
Customer full name or business name. Optional for anonymous sales.

​
Response

200 OK — success
​
exito
boolean
required
true when the sale was committed successfully.
​
id_venta
number
required
Internal ID of the new sale record.
​
serie
string
required
Document series assigned to this sale (e.g., "B001").
​
numero_documento
string
required
Zero-padded correlative number (e.g., "00000001").
​
total
number
required
Total amount echoed back from the request body.
400 Bad Request — business rule failure
​
exito
boolean
required
Always false.
​
mensaje
string
required
Human-readable reason for the failure (e.g., insufficient stock detected by the trigger).

​
Errors

StatusConditionBody
400id_tipo_comprobante missing or not a number{ "error": "id_tipo_comprobante es requerido y debe ser un número" }
400id_usuario missing or not a number{ "error": "id_usuario es requerido y debe ser un número" }
400total missing or <= 0{ "error": "total es requerido y debe ser mayor a 0" }
400detalle empty or not an array{ "error": "detalle debe ser un array con al menos 1 elemento" }
400Stock trigger rejects the transaction{ "exito": false, "mensaje": "<trigger message>" }
500Unexpected server or database error{ "error": "<message>" }
The MySQL trigger trg_validar_stock_antes_venta fires on each Detalle_Ventas insert. If any item has insufficient stock the entire transaction is rolled back — no partial sale is committed.

​
Example

curl --request POST \
  --url http://localhost:3000/api/ventas/registrar \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id_tipo_comprobante": 1,
    "numero_documento_cliente": "12345678",
    "nombres_razon_social": "Juan Pérez",
    "id_usuario": 2,
    "total": 5.00,
    "detalle": [
      {
        "id_producto": 1,
        "id_producto_precio": 1,
        "cantidad": 10,
        "precio_unitario": 0.50,
        "subtotal": 5.00
      }
    ]
  }'
Response
{
  "exito": true,
  "id_venta": 1,
  "serie": "B001",
  "numero_documento": "00000001",
  "total": 5.00
}

​
GET /api/ventas/:id

Returns the full detail of a sale: the document header and all associated line items. Calls sp_get_venta_detalle, which returns two result sets; the backend maps them to cabecera and detalle.

​
Path parameters

​
id
number
required
Internal sale ID returned by POST /api/ventas/registrar.

​
Response

200 OK
​
cabecera
object
required
Sale header record from the first SP result set.
​
detalle
object[]
required
Line items from the second SP result set.

​
Errors

StatusConditionBody
404No sale exists for the given ID{ "error": "Venta no encontrada" }
500Database or server error{ "error": "<message>" }

​
Example

curl --request GET \
  --url http://localhost:3000/api/ventas/1 \
  --header 'Authorization: Bearer <token>'
Response
{
  "cabecera": {
    "id_venta": 1,
    "serie": "B001",
    "numero_documento": "00000001",
    "tipo_comprobante": "BOLETA",
    "fecha_venta": "2024-01-15T10:30:00.000Z",
    "total": 5.00,
    "nombres_razon_social": "Juan Pérez",
    "numero_documento_cliente": "12345678"
  },
  "detalle": [
    {
      "nombre_comercial": "Paracetamol 500mg",
      "nombre_unidad": "UNIDAD",
      "cantidad": 10,
      "precio_unitario": 0.50,
      "subtotal": 5.00
    }
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us