Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Carlos-Gnd/FERRED-Inventario-y-Ventas/llms.txt

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

The sales API processes point-of-sale transactions atomically — stock is decremented and the DTE is generated in a single operation. Sales can be registered by ADMIN and CAJERO roles, restricted to their assigned branch.
The DTE (electronic invoice) is sent to Hacienda asynchronously after the sale is created. If the submission fails, the sale is not rolled back — the estado field on the returned factura will be SIMULADO or ERROR_HACIENDA, and you can retry with POST /api/dte/:id/reenviar.

​
POST /api/ventas

Creates a sale, decrements stock for each item in the branch, and triggers DTE generation. Roles: ADMIN, CAJERO
Products whose tipoUnidad is UNIDAD or LOTE require an integer cantidad. Passing a fractional quantity (e.g., 2.5) returns a 409 error with details about which products failed the unit-type check.

​
Body

​
sucursalId
number
required
ID of the branch where the sale takes place. Non-admin users must belong to this branch.
​
items
object[]
required
Line items in the sale. Must contain at least one entry.
​
clienteNombre
string
default:"Consumidor Final"
Customer name for the invoice.
​
tipoPago
string
default:"efectivo"
Payment method. Free-form string (e.g., "efectivo", "tarjeta").

​
Response 201

​
ok
boolean
Always true on success.
​
factura
object
The created FacturaDte record, including line item details and branch information.
​
resumen
object
Calculated sale totals.

​
Errors

StatusCondition
400Request body fails Zod validation (missing fields, wrong types).
404One or more productoId values do not exist or are inactive.
409Insufficient stock in the branch, or cantidad is fractional for a UNIDAD/LOTE product.
500Unexpected server error.

​
Example

curl -X POST https://server-production-3252.up.railway.app/api/ventas \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "sucursalId": 1,
    "items": [
      { "productoId": 15, "cantidad": 2, "precioUnit": 12.50 },
      { "productoId": 23, "cantidad": 1, "precioUnit": 45.00 }
    ],
    "clienteNombre": "Juan Pérez",
    "tipoPago": "efectivo"
  }'

​
GET /api/ventas/:id/ticket

Retrieves the full ticket data for an existing invoice, suitable for reprinting at the POS. Roles: ADMIN, CAJERO

​
Path parameters

​
id
number
required
ID of the invoice (FacturaDte) to retrieve.

​
Response 200

​
facturaId
number
Invoice ID.
​
codigoGeneracion
string
UUID assigned during DTE generation.
​
numeroControl
string
Hacienda control number.
​
fecha
string
ISO 8601 timestamp of when the sale was created.
​
sucursal
object
Branch information.
​
cajero
string
Name of the user who processed the sale, or "Sistema" if not available.
​
clienteNombre
string
Customer name on the invoice.
​
tipoDte
string
DTE type code (e.g., "01").
​
estado
string
Current DTE state.
​
items
object[]
Line items on the ticket.
​
resumen
object
​
dteJson
object
The full DTE JSON payload submitted to Hacienda, or null if not yet generated.

​
GET /api/ventas/estadisticas/semanales

Returns aggregated daily sales totals for a rolling window of up to 14 days. ADMIN users see totals across all branches; other roles see only their assigned branch. Roles: ADMIN, CAJERO, BODEGA

​
Query parameters

​
days
number
default:"7"
Number of days to include in the window. Must be between 1 and 14.

​
Response

​
dias
object[]
One entry per day in the requested window, ordered chronologically.
​
totalPeriodo
number
Sum of all total values across the entire window.
​
totalVentas
number
Total number of individual sales across the window.

Build docs developers (and LLMs) love

Get started for freeTalk to us