Metrics and Analytics API — KPIs, Trends, and Reports

The Metrics API exposes three endpoints that together cover every analytics need in StockManager: a lightweight dashboard summary for at-a-glance KPIs, a comprehensive business analytics object that covers revenue trends, product performance, inventory health, and vendor stats for any custom date range, and a never-sold products report for identifying dead stock. Every endpoint requires an active session; no elevated role is needed.

Dashboard Summary

GET /api/stats

Returns a compact set of current-state indicators intended for the main dashboard widgets. All values reflect the live database at the moment of the request — no date range parameter is accepted. Auth: any authenticated session. Response

products

integer

Total number of product records in the items table, regardless of status.

low_stock

integer

Count of active items where quantity <= min_quantity and quantity > 0.

sales_today

integer

Number of sale transactions (sells rows) recorded today (server local date).

low_stock_list

array

Top 10 items closest to or below their minimum quantity threshold, sorted ascending by current stock.

Show Low-stock item fields

integer

Product ID.

name

string

Product name.

sku

string

Barcode / SKU (barrs_code column).

stock

integer

Current quantity on hand.

expire_soon

integer

Count of items with an expiration_date within the next 7 days.

total_inventory_value

float

Sum of quantity × price for all active (status = 1) items, rounded to two decimal places.

curl -b cookies.txt http://localhost:5000/api/stats

{
  "products": 142,
  "low_stock": 8,
  "sales_today": 23,
  "low_stock_list": [
    {"id": 17, "name": "Aceite Motor 5W-30", "sku": "7501031311309", "stock": 1},
    {"id": 55, "name": "Filtro Aire K&N", "sku": "024844021824", "stock": 2}
  ],
  "expire_soon": 3,
  "total_inventory_value": 128450.75
}

Analytics

GET /api/metrics

Returns a rich analytics object covering KPIs, time-series data, product rankings, heatmaps, inventory forecasting, and vendor performance for a specified period. When from and to are both provided they take precedence over period. Auth: any authenticated session.

period

integer

Number of trailing days to analyze. Accepted values: 7, 30, 90, 365. Defaults to 7. Ignored when from and to are both supplied.

from

string

Period start date in YYYY-MM-DD format. Must be paired with to.

string

Period end date in YYYY-MM-DD format. Must be paired with from. When both from and to are set they override period.

Response

kpis

object

Core revenue and sales KPIs for the requested period, each accompanied by a percentage change relative to the equivalent preceding period.

Show KPI fields

revenue

float

Total revenue (sum of sale totals).

totalSales

integer

Number of completed sale transactions.

avgTicket

float

Average revenue per sale transaction.

unitsSold

integer

Total individual units sold across all transactions.

revenueChange

float

% change in revenue vs. the previous equivalent period.

salesChange

float

% change in transaction count vs. previous period.

ticketChange

float

% change in average ticket vs. previous period.

unitsChange

float

% change in units sold vs. previous period.

salesOverTime

object

Day-by-day breakdown of revenue and sale counts across the requested range.

Show salesOverTime fields

labels

array

String labels for each day. Short weekday names (Lun–Dom) when period ≤ 7; DD/MM otherwise.

revenue

array

Revenue value for each corresponding label date.

sales

array

Transaction count for each corresponding label date.

topProducts

array

Best-selling products ranked by units sold during the period.

Show Product entry fields

integer

Product ID.

name

string

Product name.

sku

string

Barcode / SKU, or "Sin SKU" when absent.

units

integer

Units sold during the period.

revenue

float

Revenue generated by this product.

salesByWeekday

array

7-element array (index 0 = Monday … index 6 = Sunday) containing the total sale count for each weekday during the period.

salesByHour

array

24-element array (index 0 = 00:00 … index 23 = 23:00) with the total sale count for each hour of day.

heatmap

object

Sales intensity matrix combining weekday and hourly distributions.

Show Heatmap fields

data

array

7 × 24 integer matrix. data[day][hour] is the estimated sale count for that day-of-week / hour combination.

days

array

7 Spanish weekday abbreviations: ['Lun', 'Mar', 'Mié', 'Jue', 'Vie', 'Sáb', 'Dom'].

hours

array

Integer list [0, 1, …, 23].

inventoryForecast

array

Up to 20 active products sorted by daysRemaining ascending — the items most at risk of running out. Only products with at least one unit sold during the period appear here.

Show Forecast item fields

integer

Product ID.

name

string

Product name.

sku

string

Barcode / SKU.

currentStock

integer

Units currently on hand.

minStock

integer

Configured minimum quantity threshold.

unitsSold

integer

Units sold during the analysis period.

dailyAverage

float

Average units sold per day over the period.

daysRemaining

integer

Estimated days until stock reaches zero at current velocity. null if no sales were recorded.

rotation

float

Units sold ÷ current stock; higher means faster turnover.

status

string

"danger" (≤ 3 days), "warning" (≤ 7 days), or "normal".

criticalStocks

array

Subset of inventoryForecast containing only items with status == "danger" (3 days or fewer of stock remaining).

insights

object

Human-readable summary derived from the period’s data.

Show Insight fields

bestDay

object

{name: string, revenue: float} — the weekday with the highest revenue, or null if no data exists.

peakHour

integer

Hour of day (0–23) with the highest sale count, or null.

topProduct

object

{name: string, units: integer} — best-selling product by units, or null.

trend

string

Narrative sentence describing revenue direction, e.g. "Las ventas aumentaron 12.4% respecto al período anterior.".

comparison

object

Side-by-side revenue figures for current and previous periods.

Show Comparison fields

current

float

Revenue for the requested period.

float

Revenue for the preceding equivalent period.

alerts

object

Real-time inventory alert counts.

Show Alert fields

outOfStock

integer

Products with quantity = 0.

lowStock

integer

Products at or below min_quantity.

noMovement

integer

Active products with zero sales in the period.

trendLine

object

Moving-average smoothing of the daily revenue series.

Show Trend line fields

labels

array

Same label strings as salesOverTime.labels.

values

array

Floating-point moving-average values. Leading positions that do not yet have enough history are null.

vendors

array

Per-vendor performance data for the period (structure mirrors internal get_vendors_metrics output).

inventory

object

Aggregate inventory snapshot at the time of the request.

Show Inventory summary fields

totalValue

float

Sum of quantity × price for all active items.

totalUnits

integer

Total units on hand across all active items in the forecast list.

period

object

Echo of the resolved date range used for the query.

Show Period fields

start

string

YYYY-MM-DD start date.

end

string

YYYY-MM-DD end date.

days

integer

Number of days covered.

Use from + to for fixed fiscal periods (e.g. a completed month), and period for rolling windows. The previous-period comparison always covers the same number of days immediately preceding the start date.

# Last 30 days
curl -b cookies.txt "http://localhost:5000/api/metrics?period=30"

# Custom date range
curl -b cookies.txt "http://localhost:5000/api/metrics?from=2024-01-01&to=2024-01-31"

{
  "kpis": {
    "revenue": 54320.50,
    "totalSales": 312,
    "avgTicket": 174.10,
    "unitsSold": 891,
    "revenueChange": 8.3,
    "salesChange": 5.1,
    "ticketChange": 3.0,
    "unitsChange": 6.7
  },
  "salesOverTime": {
    "labels": ["01/01", "02/01", "03/01"],
    "revenue": [1820.00, 2105.50, 1990.00],
    "sales": [11, 13, 12]
  },
  "topProducts": [
    {"id": 5, "name": "Aceite 5W-30", "sku": "7501031311309", "units": 48, "revenue": 4320.00}
  ],
  "salesByWeekday": [45, 62, 58, 71, 80, 95, 30],
  "salesByHour": [0,0,0,0,0,0,1,4,12,18,22,20,19,21,17,15,11,8,5,3,2,1,0,0],
  "heatmap": {
    "data": [[0,0,1],[0,0,2]],
    "days": ["Lun","Mar","Mié","Jue","Vie","Sáb","Dom"],
    "hours": [0,1,2]
  },
  "alerts": {"outOfStock": 2, "lowStock": 7, "noMovement": 14},
  "insights": {
    "bestDay": {"name": "Sábado", "revenue": 9800.00},
    "peakHour": 11,
    "topProduct": {"name": "Aceite 5W-30", "units": 48},
    "trend": "Las ventas aumentaron 8.3% respecto al período anterior. ¡Excelente trabajo!"
  },
  "comparison": {"current": 54320.50, "previous": 50155.20},
  "period": {"start": "2024-01-01", "end": "2024-01-31", "days": 31}
}

Dead Stock Report

GET /api/never-sold

Returns every active product (status = 1) that has never appeared in any sale detail record — i.e., has zero historical sales of any kind, not just within a date range. Useful for identifying obsolete or unattractive stock. Auth: any authenticated session. Response

products

array

Active products with no sales history, sorted by quantity descending (highest stock first).

Show Never-sold product fields

integer

Product ID.

name

string

Product name.

sku

string

Barcode / SKU (barrs_code), or null if not set.

stock

integer

Current quantity on hand.

price

float

Unit sale price.

curl -b cookies.txt http://localhost:5000/api/never-sold

{
  "products": [
    {"id": 88, "name": "Tapa Válvula Universal", "sku": "TAP-001", "stock": 40, "price": 85.00},
    {"id": 102, "name": "Empaque Silicón", "sku": null, "stock": 15, "price": 12.50}
  ]
}

This endpoint scans the entire details table for any historical appearance of each product. A product that was sold once and then returned still appears as “sold” and will not appear in this list.

Overview

Endpoints

Metrics and Analytics API — KPIs, Trends, and Reports

Dashboard Summary

GET /api/stats

Analytics

GET /api/metrics

Dead Stock Report

GET /api/never-sold

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Dashboard Summary

​GET /api/stats

​Analytics

​GET /api/metrics

​Dead Stock Report

​GET /api/never-sold

Build docs developers (and LLMs) love

Dashboard Summary

GET /api/stats

Analytics

GET /api/metrics

Dead Stock Report

GET /api/never-sold