Documentation Index
Fetch the complete documentation index at: https://mintlify.com/Eleazarguitar18/kantuta_pos_back/llms.txt
Use this file to discover all available pages before exploring further.
The reportes module in Kantuta POS acts as a dedicated data-serving layer for your frontend’s reporting and analytics needs. Rather than generating PDFs on the server, every endpoint returns structured JSON — pre-aggregated, pre-labeled, and ready to be consumed by client-side PDF libraries (jsPDF, Puppeteer, React-PDF) or charting components. This separation of concerns keeps the backend focused on data integrity while giving your frontend full control over layout, branding, and formatting.
All report endpoints return structured JSON objects. Feed them directly into a PDF generation library on the frontend — jsPDF for client-side rendering, Puppeteer for server-side HTML-to-PDF, or React-PDF for component-based layouts.
Dashboard Statistics
The dashboard stats endpoint is the single call that powers your home-screen KPIs. It returns consolidated metrics across sales, agent recharges, inventory health, and monthly sales trends — all in one response.
GET /reportes/dashboard-stats?anio=2025
| Parameter | Required | Default | Description |
|---|
anio | Optional | Current year | The year used to group monthly sales data (e.g., 2025) |
curl -X GET "https://api.example.com/reportes/dashboard-stats?anio=2025" \
-H "Authorization: Bearer <token>"
- Total sales revenue and transaction count for the current period
- Agent recharge totals (
recargas) for the period
- Stock health KPIs — number of products below
stock_minimo
- Monthly sales array — 12 data points (one per month) for the requested year, suitable for bar or line charts
Report Data Endpoints
All endpoints below live under /reportes/data/ and return JSON payloads structured for specific report types.
Sales by Date Range
GET /reportes/data/ventas-rango?fechaInicio=2025-01-01&fechaFin=2025-01-31&auditor=Admin
auditor string in the report header object for accountability.
Query parameters:
| Parameter | Required | Description |
|---|
fechaInicio | ✅ | Start date in YYYY-MM-DD format |
fechaFin | ✅ | End date in YYYY-MM-DD format |
auditor | ✅ | Name or username of the person generating the report |
curl -X GET "https://api.example.com/reportes/data/ventas-rango?fechaInicio=2025-01-01&fechaFin=2025-01-31&auditor=Admin" \
-H "Authorization: Bearer <token>"
Purchases by Date Range
GET /reportes/data/compras-rango?fechaInicio=2025-01-01&fechaFin=2025-01-31&auditor=Admin
| Parameter | Required | Description |
|---|
fechaInicio | ✅ | Start date in YYYY-MM-DD format |
fechaFin | ✅ | End date in YYYY-MM-DD format |
auditor | ✅ | Name embedded in the report header |
Inventory Snapshot
GET /reportes/data/inventario?auditor=Admin
stock_minimo are flagged for easy highlighting in the PDF.
Query parameters:
| Parameter | Required | Description |
|---|
auditor | ✅ | Name embedded in the report header |
curl -X GET "https://api.example.com/reportes/data/inventario?auditor=Admin" \
-H "Authorization: Bearer <token>"
Operator Productivity
GET /reportes/data/productividad-operador?fechaInicio=2025-01-01&fechaFin=2025-01-31&operadorId=1
| Parameter | Required | Description |
|---|
fechaInicio | ✅ | Start date in YYYY-MM-DD format |
fechaFin | ✅ | End date in YYYY-MM-DD format |
operadorId | Optional | Filter to a specific operator by user ID. Omit to get data for all operators |
Cash Register Session Movements
GET /reportes/data/movimientos-caja/:idSesion
SesionCaja. This is the data source for the end-of-shift cash reconciliation PDF.
Path parameters:
| Parameter | Type | Description |
|---|
idSesion | integer | ID of the session (SesionCaja.id) |
curl -X GET https://api.example.com/reportes/data/movimientos-caja/12 \
-H "Authorization: Bearer <token>"
Single Sale Receipt
GET /reportes/data/venta/:id
curl -X GET https://api.example.com/reportes/data/venta/45 \
-H "Authorization: Bearer <token>"
Product Info Sheet
GET /reportes/data/producto/:id
curl -X GET https://api.example.com/reportes/data/producto/3 \
-H "Authorization: Bearer <token>"
Caja Session History
GET /reportes/data/caja-historial/:id
| Parameter | Type | Description |
|---|
id | integer | ID of the physical Caja (not the session) |
curl -X GET https://api.example.com/reportes/data/caja-historial/1 \
-H "Authorization: Bearer <token>"
Sales Summary (via Ventas Module)
For an aggregated financial summary of sales over a date range — with totals grouped by payment method, transaction count, and average ticket — use the sales module’s dedicated report endpoint:
POST /ventas/reporte-resumen
{
"fechaInicio": "2025-01-01",
"fechaFin": "2025-01-31"
}
curl -X POST https://api.example.com/ventas/reporte-resumen \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"fechaInicio": "2025-01-01",
"fechaFin": "2025-01-31"
}'
200 OK (not 201) and is documented in the Sales Workflow guide.
All Report Endpoints at a Glance
| Method | Endpoint | Description |
|---|
GET | /reportes/dashboard-stats?anio= | Dashboard KPIs and monthly trends |
GET | /reportes/data/ventas-rango | Sales list by date range |
GET | /reportes/data/compras-rango | Purchases list by date range |
GET | /reportes/data/inventario | Full inventory snapshot |
GET | /reportes/data/productividad-operador | Operator productivity metrics |
GET | /reportes/data/movimientos-caja/:idSesion | Session cash movements |
GET | /reportes/data/venta/:id | Single sale receipt data |
GET | /reportes/data/producto/:id | Product info sheet |
GET | /reportes/data/caja-historial/:id | Full caja session history |
POST | /ventas/reporte-resumen | Grouped sales summary for PDF |