Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/elzackarias/Hackaton3B-Reto1/llms.txt

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

Analytics endpoints aggregate the live InventoryEngine state into actionable KPIs and restock guidance. All values are computed on-demand from the in-memory event log and current stock levels — there is no caching layer, so every response reflects the exact state at request time.

​
GET /api/analytics

Returns a live KPI snapshot of the entire shelf: capacity utilization, event throughput, active alerts, and per-product fill rates. 
curl http://localhost:8000/api/analytics

​
Top-level Response Fields

​
timestamp
string
ISO 8601 datetime when this analytics snapshot was generated.
​
total_capacity
integer
Sum of all stock_initial values across the 7 products (stock_initial × 7, typically 56).
​
total_current
integer
Sum of stock_current across all 7 products.
​
fill_rate_global
float
Global shelf fill rate: total_current / total_capacity, rounded to 2 decimal places. Range 0.0–1.0.
​
total_events
integer
Total number of events (retiros + devoluciones) recorded since the last reset.
​
velocity_per_min
float
Rolling event throughput in events per minute, computed from the span between the first and last recorded events. Returns 0.0 if fewer than 2 events exist.
​
alerts_active
integer
Number of products currently in alert state (is_alert = true).
​
most_sold_sku
string | null
sku_id of the product with the highest number of retiro events. null if no events yet.
​
least_sold_sku
string | null
sku_id of the product with the fewest retiro events. null if no events yet.
​
products
array
Per-product breakdown. See sub-fields below.

​
Product Analytics Object (within products array)

​
sku_id
string
Unique SKU identifier.
​
sku_name
string
Human-readable product name.
​
stock_current
integer
Current units on the shelf.
​
stock_initial
integer
Initial stock level (always 8).
​
fill_rate
float
Per-product fill rate: stock_current / stock_initial, rounded to 2 decimal places.
​
retiros
integer
Total number of retiro events recorded for this SKU since the last reset.
​
iventa
float
Internal sales velocity index from the product catalog. Higher values indicate faster-selling products (e.g., nachos_naturasol = 22, agua_burst = 6).
Example response: 
{
  "timestamp": "2024-11-15T10:45:00.321000",
  "total_capacity": 56,
  "total_current": 48,
  "fill_rate_global": 0.86,
  "total_events": 12,
  "velocity_per_min": 2.4,
  "alerts_active": 0,
  "most_sold_sku": "nachos_naturasol",
  "least_sold_sku": "burst_energetica_roja",
  "products": [
    {
      "sku_id": "nachos_naturasol",
      "sku_name": "Nachos Con Sal Naturasol 200gr",
      "stock_current": 4,
      "stock_initial": 8,
      "fill_rate": 0.5,
      "retiros": 4,
      "iventa": 22
    },
    {
      "sku_id": "agua_burst",
      "sku_name": "Agua Natural Burst 1500ml",
      "stock_current": 8,
      "stock_initial": 8,
      "fill_rate": 1.0,
      "retiros": 0,
      "iventa": 6
    }
  ]
}

​
GET /api/restock

Returns a restock priority list for all products that are not at full stock, sorted by priority_score in descending order (most urgent first). If all products are fully stocked, the response is an empty array. 
curl http://localhost:8000/api/restock

​
Priority Score Formula

priority_score = units_missing × iventa × (1 - fill_rate)
Products with high iventa (fast sellers) and low fill_rate (nearly empty) rank highest.

​
Response Fields (per item)

​
sku_id
string
Unique SKU identifier.
​
sku_name
string
Human-readable product name.
​
slot_id
integer
Physical shelf slot number (1–7).
​
stock_current
integer
Current units remaining on the shelf.
​
stock_initial
integer
Target stock level (always 8).
​
units_missing
integer
Units needed to reach full stock: stock_initial - stock_current.
​
fill_rate
float
Current fill rate: stock_current / stock_initial, rounded to 2 decimal places.
​
iventa
float
Internal sales velocity index from the product catalog.
​
priority_score
float
Computed restock urgency score. Higher = more urgent.
​
is_alert
boolean
true when the product has crossed the alert threshold.
​
urgency
string
Human-readable urgency tier:
  • "CRITICA" — product is in alert state (is_alert = true)
  • "MEDIA" — fill rate is 50% or below (fill_rate ≤ 0.5)
  • "BAJA" — fill rate is above 50%
Example response: 
[
  {
    "sku_id": "nachos_naturasol",
    "sku_name": "Nachos Con Sal Naturasol 200gr",
    "slot_id": 4,
    "stock_current": 2,
    "stock_initial": 8,
    "units_missing": 6,
    "fill_rate": 0.25,
    "iventa": 22,
    "priority_score": 99.0,
    "is_alert": true,
    "urgency": "CRITICA"
  },
  {
    "sku_id": "sun_paradise_naranja",
    "sku_name": "Bebida Naranja Sun Paradise 900ml",
    "slot_id": 7,
    "stock_current": 5,
    "stock_initial": 8,
    "units_missing": 3,
    "fill_rate": 0.62,
    "iventa": 18,
    "priority_score": 20.2,
    "is_alert": false,
    "urgency": "BAJA"
  }
]
Products at full stock (units_missing = 0) are excluded from the response entirely. An empty array [] means all 7 products are fully stocked.

Build docs developers (and LLMs) love

Get started for freeTalk to us