Reportes API: Dashboard Statistics and Report Data

The Reportes module provides structured JSON payloads purpose-built for two use cases: real-time dashboard charts and PDF-ready report data. Every response is pre-aggregated on the server — totals, breakdowns, and rankings are computed by the API so the frontend can pass the data straight to a charting library or a PDF renderer without additional transformation. All endpoints in this module require a valid Authorization: Bearer <access_token> header.

Dashboard statistics

GET /reportes/dashboard-stats

Returns a consolidated KPI snapshot for the main dashboard: today’s sales and recharge totals, a low-stock product count, a 12-month bar chart series, a top-5 best-seller ranking, and a monthly recharge distribution breakdown by carrier.

Query parameters

anio

number

Four-digit year used to group the monthly sales series (e.g. 2025). Defaults to the current calendar year when omitted. Non-numeric values are silently coerced to the current year.

Response

kpis

object

Real-time KPI counters for today.

Show KPI fields

ventas_hoy

number

Total revenue from completed sales (estado_venta = 'COMPLETADA') created today (local midnight to 23:59:59).

recargas_hoy

number

Total amount of mobile top-up transactions (RecargaCliente) processed today.

ganancia_comisiones_hoy

number

Commission earnings today. Returns 0 (feature reserved for a future release).

productos_stock_bajo

number

Count of active products where stock_actual <= stock_minimo.

ventas_mensuales

array

12-element array — one entry per calendar month — for the requested anio. Months with no completed sales have total: 0.

Show Monthly entry

mes

string

Three-letter Spanish month abbreviation: "Ene", "Feb", … "Dic".

total

number

Sum of completed sale totals for that month.

top_productos

array

Top 5 products ranked by total units sold across all time (completed sales only).

Show Product entry

nombre

string

Product name.

cantidad

number

Total units sold.

ganancia

number

Gross profit: SUM(subtotal) - SUM(cantidad × costo_compra).

recargas_distribucion

array

Monthly recharge revenue split by carrier — always returns exactly three entries: Entel, Viva, and Tigo. Carriers with no transactions in the current month have total: 0.

Show Carrier entry

proveedor

string

Carrier name ("Entel", "Viva", or "Tigo").

total

number

Sum of recharge amounts for the current calendar month.

Example

curl https://api.kantutapos.com/api/reportes/dashboard-stats?anio=2025 \
  -H "Authorization: Bearer <access_token>"

{
  "kpis": {
    "ventas_hoy": 1540.50,
    "recargas_hoy": 320.00,
    "ganancia_comisiones_hoy": 0,
    "productos_stock_bajo": 3
  },
  "ventas_mensuales": [
    { "mes": "Ene", "total": 12300.00 },
    { "mes": "Feb", "total": 9800.50 },
    { "mes": "Mar", "total": 15200.75 },
    { "mes": "Abr", "total": 11050.00 },
    { "mes": "May", "total": 18400.00 },
    { "mes": "Jun", "total": 0 },
    { "mes": "Jul", "total": 0 },
    { "mes": "Ago", "total": 0 },
    { "mes": "Sep", "total": 0 },
    { "mes": "Oct", "total": 0 },
    { "mes": "Nov", "total": 0 },
    { "mes": "Dic", "total": 0 }
  ],
  "top_productos": [
    { "nombre": "Coca Cola 2L", "cantidad": 340, "ganancia": 510.00 },
    { "nombre": "Aceite Fino 1L", "cantidad": 210, "ganancia": 315.00 }
  ],
  "recargas_distribucion": [
    { "proveedor": "Entel", "total": 1200.00 },
    { "proveedor": "Viva",  "total": 750.00 },
    { "proveedor": "Tigo",  "total": 430.00 }
  ]
}

Sales range report

GET /reportes/data/ventas-rango

Returns a financial summary and itemized list of sales for a date range. Designed to feed PDF report generators — the response includes pre-computed payment-method breakdowns so no further aggregation is needed client-side.

Query parameters

fechaInicio

string

required

Range start date in ISO 8601 format (YYYY-MM-DD). Internally set to 00:00:00 local time.

fechaFin

string

required

Range end date in ISO 8601 format (YYYY-MM-DD). Internally set to 23:59:59.999 local time.

auditor

string

required

Name of the person requesting the report — embedded in the PDF header by the frontend renderer.

Response

totales

object

Aggregated totals for the requested range (only COMPLETADA and EDITADA sales are counted).

Show Totals fields

totalVendido

number

Sum of all completed/edited sale totals.

totalTransacciones

number

Total count of sale records in the date range (all statuses).

desglose.efectivo

number

Revenue from cash (EFECTIVO) payments.

desglose.qr

number

Revenue from QR code payments.

desglose.transferencia

number

Revenue from bank transfer payments.

desglose.digitalTotal

number

Combined QR + transfer revenue.

ventas

array

Ordered list of individual sales (most recent first).

Show Sale entry

number

Sale ID.

fecha

string

ISO 8601 timestamp of the sale.

total

number

Sale total amount.

metodo_pago

string

"EFECTIVO", "QR", or "TRANSFERENCIA".

estado_venta

string

"COMPLETADA", "EDITADA", or "ANULADA".

Example

curl "https://api.kantutapos.com/api/reportes/data/ventas-rango?fechaInicio=2025-05-01&fechaFin=2025-05-31&auditor=Gerente+General" \
  -H "Authorization: Bearer <access_token>"

Purchases range report

GET /reportes/data/compras-rango

Returns all purchase records within a date range along with the total capital invested. Mirrors the sales range endpoint but queries the Compra entity.

Query parameters

fechaInicio

string

required

Range start date (YYYY-MM-DD).

fechaFin

string

required

Range end date (YYYY-MM-DD).

auditor

string

required

Auditor name embedded in the report metadata.

Response

fechaInicio

string

Start date echoed back.

fechaFin

string

End date echoed back.

auditor

string

Auditor name echoed back.

fechaEmision

string

ISO 8601 timestamp of when the report was generated.

compras

array

List of purchase records (most recent first).

Show Purchase entry

number

Purchase ID.

fecha

string

Purchase date.

proveedor

string

Supplier name, or "Sin Proveedor" if not recorded.

pagado_con_caja

boolean

Whether the purchase was paid from the cash register.

total

number

Total purchase amount.

totalInvertido

number

Sum of all purchase totals in the range.

Inventory snapshot

GET /reportes/data/inventario

Returns the current state of all active products — cost basis, sale price, current stock, and a low-stock flag — plus a financial summary of the inventory’s total value.

Query parameters

auditor

string

required

Auditor name included in the report metadata for traceability.

Response

fechaCorte

string

ISO 8601 timestamp of when the snapshot was taken.

auditor

string

Auditor name echoed back.

productos

array

All active products, ordered by stock_actual ascending (lowest stock first).

Show Product entry

codigo_barras

string

Barcode, or "-" if not assigned.

nombre

string

Product name.

categoria

string

Category name, or "-" if uncategorized.

stock_actual

number

Current units on hand.

bajoStock

boolean

true if stock_actual <= stock_minimo.

costo

number

Unit purchase cost.

precio

number

Unit sale price.

resumen

object

Inventory financial summary.

Show Summary fields

itemsBajoStock

number

Count of products at or below their minimum stock level.

totalCosto

number

Total inventory value at cost (SUM(costo × stock_actual)).

totalPrecio

number

Total inventory value at sale price (SUM(precio × stock_actual)).

gananciaProyectada

number

Projected gross profit if all current stock were sold (totalPrecio - totalCosto).

Operator productivity report

GET /reportes/data/productividad-operador

Aggregates completed sales by operator (the user who created each sale) for a given date range. Returns a ranked list of operators sorted by total amount billed, descending. Useful for performance reviews and commission calculations.

Query parameters

fechaInicio

string

required

Range start date (YYYY-MM-DD).

fechaFin

string

required

Range end date (YYYY-MM-DD).

operadorId

number

Optional. Filter results to a single operator by their user ID. Omit to return all operators.

Response

fechaInicio

string

Start date echoed back.

fechaFin

string

End date echoed back.

fechaEmision

string

ISO 8601 timestamp of report generation.

operadores

array

Ranked list of operators (highest billed first).

Show Operator entry

operador

string

Operator’s full name from the Usuario entity.

cantidad_ventas

number

Number of completed sales attributed to this operator.

total_facturado

number

Total revenue from the operator’s completed sales.

Cash session movements

GET /reportes/data/movimientos-caja/:idSesion

Returns the complete movement log for a specific cash register session, including INGRESO/EGRESO entries and pre-computed net totals. Throws 404 if the session ID does not exist.

Path parameters

idSesion

number

required

Numeric ID of the SesionCaja record (e.g. 42).

Response

sesion

object

Session metadata.

Show Session fields

number

Session ID.

cajaNombre

string

Name of the cash register.

fechaApertura

string

Session open timestamp.

fechaCierre

string

Session close timestamp, or null if still open.

montoInicial

number

Opening float amount.

saldoActualTeorico

number

Current theoretical balance from the Caja entity.

movimientos

array

All active movements for this session, ordered chronologically.

Show Movement entry

number

Movement ID.

fecha

string

Movement timestamp.

tipo

string

"INGRESO" or "EGRESO".

motivo

string

Description of the movement (e.g. "Pago a proveedor").

monto

number

Amount of the movement.

totales

object

Show Totals fields

ingresos

number

Sum of all INGRESO movements.

egresos

number

Sum of all EGRESO movements.

neto

number

Net cash flow: ingresos - egresos.

Single sale receipt

GET /reportes/data/venta/:id

Returns all data required to render a receipt PDF for one completed sale: line items, unit prices, subtotals, payment method, and the operator who processed it. Throws 404 if the sale ID does not exist.

Path parameters

number

required

Numeric ID of the Venta record (e.g. 1042).

Response

number

Sale ID.

fecha

string

ISO 8601 sale timestamp.

cajero

string

Name of the operator who processed the sale, or "Sistema" if the user record is unavailable.

metodo_pago

string

"EFECTIVO", "QR", or "TRANSFERENCIA".

estado_venta

string

Final status: "COMPLETADA", "EDITADA", or "ANULADA".

detalles

array

Line items of the sale.

Show Line item

nombre

string

Product name.

cantidad

number

Units sold.

precio_unitario

number

Unit price at time of sale.

subtotal

number

Line total (precio_unitario × cantidad).

total

number

Sale grand total.

Product data sheet

GET /reportes/data/producto/:id

Returns a product information sheet suitable for a PDF catalog or inventory printout. Throws 404 if the product ID does not exist.

Path parameters

number

required

Numeric ID of the Producto record.

Response

number

Product ID.

nombre

string

Product name.

codigo_barras

string

Barcode string, or null if not assigned.

categoria

string

Category name, or "Sin categoría".

stock_actual

number

Current units on hand.

stock_minimo

number

Reorder threshold.

precio_venta

number

Current sale price.

costo_compra

number

Current purchase cost.

fecha_ingreso

string

ISO 8601 timestamp of when the product was first created.

Cash register history extract

GET /reportes/data/caja-historial/:id

Returns a full chronological movement history across all sessions for a given cash register. Unlike /movimientos-caja/:idSesion (which scopes to one session), this endpoint aggregates every movement ever recorded for the register. Throws 404 if no movements exist for the given caja ID.

Path parameters

number

required

Numeric ID of the Caja entity (the physical register), not a session ID.

Response

caja

object

Show Caja fields

number

Caja ID.

nombre

string

movimientos

array

All movements across all sessions for this register, ordered by date ascending.

Show Movement entry

number

Movement ID.

fecha

string

Movement timestamp.

id_sesion

number

ID of the session this movement belongs to.

tipo

string

"INGRESO" or "EGRESO".

motivo

string

Description of the movement.

monto

number

Movement amount.

totales

object

Show Totals fields

ingresos

number

Lifetime sum of all INGRESO movements.

egresos

number

Lifetime sum of all EGRESO movements.

neto

number

ingresos - egresos.

PDF generation tips

All /reportes/data/* endpoints return self-contained JSON objects — no secondary requests needed. Pass the response directly to your PDF library:

jsPDF + AutoTable — map ventas or movimientos arrays to table rows
Puppeteer — render an HTML template server-side, inject JSON data, then print to PDF
react-pdf / @react-pdf/renderer — use the response as props to a <Document> component on the frontend

The auditor and fechaEmision fields are intentionally included in each response so they can be stamped on the report header without any additional API calls.

POST /ventas/reporte-resumen (in the Ventas module) provides an alternative grouped financial summary for a date range with subtotals by payment method. Use it when you need a high-level executive summary rather than the full transaction list returned by /reportes/data/ventas-rango.

Authentication

Users & People

Inventory

Operations

Integrations

Reportes API: Dashboard Statistics and Report Data

Dashboard statistics

Query parameters

Response

Example

Sales range report

Query parameters

Response

Example

Purchases range report

Query parameters

Response

Inventory snapshot

Query parameters

Response

Operator productivity report

Query parameters

Response

Cash session movements

Path parameters

Response

Single sale receipt

Path parameters

Response

Product data sheet

Path parameters

Response

Cash register history extract

Path parameters

Response

PDF generation tips

Build docs developers (and LLMs) love

Authentication

Users & People

Inventory

Operations

Integrations

Documentation Index

​Dashboard statistics

​Query parameters

​Response

​Example

​Sales range report

​Query parameters

​Response

​Example

​Purchases range report

​Query parameters

​Response

​Inventory snapshot

​Query parameters

​Response

​Operator productivity report

​Query parameters

​Response

​Cash session movements

​Path parameters

​Response

​Single sale receipt

​Path parameters

​Response

​Product data sheet

​Path parameters

​Response

​Cash register history extract

​Path parameters

​Response

​PDF generation tips

Build docs developers (and LLMs) love

Dashboard statistics

Query parameters

Response

Example

Sales range report

Query parameters

Response

Example

Purchases range report

Query parameters

Response

Inventory snapshot

Query parameters

Response

Operator productivity report

Query parameters

Response

Cash session movements

Path parameters

Response

Single sale receipt

Path parameters

Response

Product data sheet

Path parameters

Response

Cash register history extract

Path parameters

Response

PDF generation tips