La API de StockAI

Explains a specific SKU's inventory signal and recommendation in plain language.

Generates a concise insight about the current inventory state.

Generates an executive morning briefing narrative from the inventory briefing data. Adapts language and focus to the business profile.

Returns context-aware suggested questions for the AI Analyst.

The tenant's most recent alerts, newest first, plus this user's unread count. A read — every role may see the history of what was sent to them.

Everything the system did for this tenant, newest first.

The filter vocabulary, from the same registry the writers use, so the screen's filter cannot drift from what can actually be recorded.

Verbalize arbitrary JSON data with business context. The session only provides auth/tenant isolation — it does not need to be COMPLETED.

Answers a natural-language question about a completed session's results, grounded in its data and the tenant's documents.

Whether the session's results and documents are indexed for the analyst, and how many chunks.

Files produced by the session's training run (models, metrics, exports).

Streams one artifact file listed by the artifacts endpoint.

WAPE and bias of each SKU's champion model.

Customer orders placed ahead of time, with their delivery date, probability, status and risk.

The champion forecast per SKU per period, with its band.

One row per SKU and warehouse: signal, stock, incoming, coverage, reorder point, recommended quantity, forecast source and money at risk.

Every purchase order line with order, supplier, state, dates, quantity, cost and received quantity.

Purchase order lines with units received, and when.

Every dataset's columns, types, sort and parameters: the contract a report binds to.

Rich dataset analysis for the pre-column wizard step.

Alias of GET /sessions/{session_id}/configure/columns.

Alias of POST /sessions/{session_id}/configure/columns.

Every configuration block of the session in one response, as the training run will read it.

Service level, lead time and cost parameters used to turn the forecast into stock signals.

Sets service level, default lead time, holding cost and stockout cost for the session.

Alias of POST /sessions/{session_id}/configure/features.

Horizon and quantiles the session forecasts.

Sets the forecast horizon, its mode and the quantiles to produce.

Alias of POST /sessions/{session_id}/configure/models.

Alias of POST /sessions/{session_id}/configure/validation.

Which dataset columns are the SKU, date, demand and optional fields.

Maps the dataset's columns to the canonical fields (sku, date, demand, …).

Lags, rolling windows, calendar and Fourier features the session generates.

Sets the lags, rolling windows, calendar, Fourier and holiday features to generate.

Apply the guide's fixes as a recorded, deterministic transformation.

Which forecasting models the session trains and how the best one is chosen.

Selects the models to train, their hyperparameters and the selection metric. Routing only ever narrows this list.

Data-quality fixes chosen for the session's dataset.

Record how the user chose to handle each blocking-but-fixable finding.

Train/test split, walk-forward validation and minimum history.

Sets the train/test split, walk-forward folds, minimum history and seasonal period.

What is wrong with this file, and what the user may do about it.

Attaches an uploaded dataset to the session.

What the guide makes of the ORIGINAL file, given the answers so far.

Pre-training data health check.

Columns, types and sample rows of the session's dataset, with detected candidates for each canonical field.

Return hyperparameter schemas for all available models.

Alias of GET /sessions/{session_id}/inspect.

Uploads a file (multipart) and attaches it to the session in one call.

Readable by every role: it is needed to render any figure on any screen.

The tenant's file and SQL data sources. Paginated with skip and limit.

Uploads a CSV/Excel file (multipart) as a new data source.

Registers a database connection as a data source. Fields may come from a pasted `connection_string` (URL, JDBC, ADO.NET or libpq form); typed fields win. `ssl_mode` is disable, prefer, require, verify-ca or verify-full; `ssl_ca` is the server's CA certificate (PEM), stored encrypted like the password. Private and link-local hosts are refused unless the installation allows them (`data_source_host_not_allowed`).

Reads a connection string into engine, host, port, database, user and TLS mode. The password is never returned, only `has_password`.

Removes the data source.

One data source's metadata.

Changes the data source's name and description.

Demand statistics over the source: totals, seasonality and per-SKU summaries, optionally within a date range.

The same analysis for a single SKU, with its time series.

Columns and rows of the source, for editing and saving as a new source.

Executes ONE read statement (SELECT or WITH ... SELECT) on the customer's database, inside a read-only transaction that is always rolled back, and returns up to `limit` rows starting at `offset`, with `has_more`. Needs a `write`-scope key: it runs caller-written SQL on the customer's database. Anything else is refused with `sql_multiple_statements`, `sql_not_a_select`, `sql_forbidden_keyword`, `sql_forbidden_function` or `sql_unsupported_syntax`.

Runs the query (same read-only rules as execute-query) and returns the FULL result as an .xlsx (default) or .csv file, refusing rather than truncating past the row ceiling. Needs a `write`-scope key.

Uploads a new file (multipart) IN PLACE: the source keeps its id and column mapping, so the next training run needs no reconfiguration. The nightly-export endpoint.

Runs the query and stores the result as a dataset that sessions can train on.

The first rows of the source (and of a given sheet, for Excel).

Stores the query the SQL source materializes.

Creates a new data source from edited columns and rows.

Tables and views the connection can read, with row estimates and a safely quoted preview statement for each. Cached for a few minutes; `refresh=true` re-reads.

Column names, types and nullability of one table of a SQL source.

Changes any connection field of a SQL source. Omitted fields keep their stored value, the password included, except when the engine, host or port changes: then the password must be sent again (`data_source_password_required`).

Runs a staged test (dns, tcp, tls, auth, privileges, select, tables) and reports each stage as ok, warning, failed or skipped with a code. Warns when the login can write, with the least-privilege GRANT statements.

Uploaded datasets. Paginated with skip and limit.

Uploads a sales-history file (multipart) and profiles it.

One dataset's metadata and profile.

Documents uploaded for the analyst to read.

Upload a document (PDF, DOCX, TXT up to 50 MB). File is saved to storage and indexed asynchronously. Returns doc metadata with status=PENDING immediately.

Removes the document and its index.

One document's metadata.

Serve the raw file for in-browser viewing or download.

Whether the document has been processed and indexed.

This tenant's tier, its ceilings, and how close it is to them.

The JSON schema of every configuration block, independent of a session.

The forecasting models this deployment can train.

Accuracy of the session's forecasts against baselines, per SKU and overall.

The latest automatic reading of how this forecast is doing against the sales uploaded after it was made, next to its accuracy at training time.

The models that can be trained on this session's data.

Train a back-test of a completed session: the same configuration on a copy of its dataset with the last `holdout_periods` periods held out. Its forecast then covers those periods and can be graded against the full dataset with `forecast-vs-actual`. The source session and dataset are not modified; the run counts against the plan's saved-forecast ceiling and is refused (nothing deleted) when that is full.

The configuration schema with this session's current values.

STL trend / seasonal / residual split of one SKU's history.

Compares a new file (multipart) with the data the session was trained on and reports distribution drift.

The session's full configuration as one exportable document.

History and forecast (with quantiles) for one SKU, optionally for a given model.

The whole catalogue as one series: every SKU's champion forecast and history summed per date. Feeds the session-comparison chart's "all SKUs" option, where two sessions are only comparable as totals.

What this session predicted vs. what the tenant's LATER sales uploads say actually happened: per-SKU and pooled WAPE / MAPE / bias, the predicted-vs- actual series, and a verdict code the frontend renders in words.

Per-SKU inventory recommendations computed from this session's forecast.

Validation metrics per model and SKU.

Manual adjustments made to the session's forecast.

Upserts manual forecast values per SKU and date, with a reason. The body is a list.

Runs the trained model for one SKU with the given inputs and horizon.

Data-quality findings for the session's dataset.

Upload a CSV of actual values to compare against the stored forecast.

The session's results summarized as one report document.

Forecasts and per-model results of a completed session, at SKU or aggregate level.

Which model was routed to each SKU and why.

The routing decisions as a plan, per SKU segment.

Return SHAP feature importances for the best model for the given SKU.

Everything known about one SKU in the session: series, model, drivers and recommendation.

Data problems the validation layers found while training this session.

Age of the sales history and of the stock table, plus whether the semáforo may still claim a colour.

Fire the daily inventory alert immediately for this tenant — email to the admins, WhatsApp to the ones who opted in. Lets the user verify their channels without waiting for the 8:00 UTC scheduler run.

Returns all finished goods that use this component.

Returns BOM (Bill of Materials) for a finished good.

Removes a component from a parent SKU's bill of materials.

Creates or updates how much of a component one unit of the parent SKU uses.

Import stock from a CSV or Excel file.

Dry run of POST /bulk: what we detected in the file and what we would write, without touching a single row. This is what makes the mapping wizard possible — the user corrects our column guesses BEFORE importing, the same way the sales upload works.

Invoices falling due from POs already sent, dated by each supplier's credit terms. Read-only, so viewers may call it.

"Does the recommended purchase fit in the cash I have?"

Lightweight endpoint for the dashboard widget. Returns only the summary counts without the full item list.

Every SKU on hand whose stock level has not fallen in at least `window_days`, ranked worst first by money, with the tenant's total at the top. Needs no session — it reads real stock-level history, not a forecast.

Promotions and seasonal events that multiply expected demand.

Adds an event with a date range and a demand multiplier.

Which commercial events StockAI knows for a country, and whether this tenant has them seeded / switched on. Read-only.

Preload the LatAm commercial calendar into this tenant's events.

Switch every occurrence of one catalog entry on/off in a single call (e.g. all 24 seeded `co_quincena_15` rows).

What-if simulator — project a promo/season's impact per SKU: extra demand, stock survival, quantity to order and the latest order date. Read-only.

Events starting within the next `days` days.

Removes the event.

Changes an event's name, dates, multiplier, notes or active flag.

Per-SKU, per-family or per-category multiplier overrides for this event.

Pin the multiplier for a product or a category on this event. On Black Friday electronics do not behave like milk.

Drop the override: the product falls back to the event multiplier.

Projected revenue, cost and gross margin over the active session's forecast horizon, per SKU and in total, ranked so the top contributors are visible — "your next N days: X in sales, Y in margin, and these products carry it."

Records that an order was placed, with its lines. Reception tracking and supplier lead-time learning read it. A body without `items` records every actionable SKU of the session.

SKUs whose margin eroded because their cost rose while the product's sale_price is the only price StockAI has ever stored. `price_history_available: false` in the response is load-bearing: the "before" margin is today's price against a past cost, not a historical fact — see `cost_alerts.get_margin_erosion`'s docstring.

Daily operations briefing: risks, recommendations, demand changes, KPIs. Designed to be the first thing a manager opens every morning. Reflects the tenant's ACTIVE planning period — coverage and the signal in that unit — so /hoy agrees with /inventory (a weekly session must be read as weekly).

Runs the MILP purchasing/transfers optimizer for this session and returns suggested purchase quantities per SKU x warehouse, plus recommended inter-warehouse transfers, collapsed to one total per line over the full horizon.

A purchase order the buyer writes from scratch — supplier chosen explicitly, lines typed in, no forecast session behind it. Persisted with source='manual' so adoption metrics stay clean. `Idempotency-Key`: same contract as /log-po.

Returns recent PO generation events for the history panel.

The PO history, filtered and paged on the server. `total` counts the filtered set; `awaiting_reception` counts every open order of the tenant.

Create purchase orders from a CSV / Excel file, one order per (order reference, supplier, destination warehouse).

Dry run of POST /po/import: the orders the file would create, and every row whose supplier / product / warehouse did not resolve. Writes nothing.

Purchase-order import template: header row plus example lines (two orders, the first with two lines).

POs still pending/partial whose expected arrival — order date plus the supplier's already-learned lead time — has passed with no reception recorded. Powers the /hoy 'did it arrive?' nudge.

Lines of a PO with ordered vs received quantities (reception form).

Record that a PO arrived (fully, partially, or not at all). Side effects: current_stock increases by the received units, and StockAI logs the supplier's REAL lead time (order date → reception date).

Sends a PO's PDF to each of its suppliers by email and WhatsApp, grouping the PO's lines by supplier name (a PO can span more than one supplier). Lines with no supplier name, or whose supplier has no saved contact info, are skipped and reported back — never a 500.

Supplier quantity scales, optionally filtered by supplier and/or SKU.

Given the cart the buyer currently has on screen, which lines are one step away from a better unit price AND would still be a good idea to step up to.

Removes a supplier's quantity price break.

The valid product types, as the English keys the frontend translates.

MRP Level 1 explosion: given forecast demand + BOM, returns required quantities of each component and raw material, flagging shortages and purchase requirements.

Generates and streams a one-page executive PDF inventory summary.

Returns accumulated ROI metrics across all time.

Recap of a single calendar month (feature 3.2). Defaults to the month that just closed — the same period the monthly recap email covers.

Last N months: orders, stockout risks handled, adoption, capital freed from overstock.

Unconfigured SKUs ordered by the money they move, with the running cumulative share of projected spend.

Recent history of recorded shrinkage (input to the future monthly summary).

Record a stock-out that is NOT a sale — breakage, expiry, self-consumption or a gift/sample. Decrements the SKU's theoretical stock through the same path PO reception uses (so the signal stays accurate) and accumulates the cost (quantity x unit cost) for a future monthly shrinkage summary.

Returns the valid shrinkage reason codes (labels are handled client-side via i18n).

Returns per-SKU inventory status in the tenant's ACTIVE planning period: - coverage (in the active period's units — see `coverage_unit`) - traffic-light signal (PEDIR_YA / PEDIR_PRONTO / OK / SOBRESTOCK / SIN_DATOS) - recommended order quantity - inventory value

Export purchase order as CSV, filtered to actionable SKUs.

Every SKU's stock record: on hand, minimum, lead time, cost, supplier and catalogue fields.

List stock counts, newest first, with how many products each holds.

Open a count session for one warehouse, optionally scoped to a category or supplier.

One count with every line (counted quantity next to the system quantity at the first scan).

Write the differences into stock, exactly once, and record each adjustment with reason 'physical_count'. Omit skus to apply every line; a list applies only those. All or nothing.

Discard an open or closed count. Stock is not changed.

Finish counting. A closed count accepts no more lines and can be reviewed and applied.

Record units of a SKU in an open count. mode 'add' (default) accumulates, 'set' replaces the counted total; a repeated client_ref is ignored.

Remove one SKU from an open count.

Differences between counted and system quantity, largest value impact first. A SKU with no unit cost has a null value impact.

Resolve a scanned code to a SKU (barcode first, then SKU). Declared before `/stock/{sku}`, which would otherwise take 'lookup' for a SKU.

Stock rows searched, filtered by warehouse and paged on the server. The plain `/stock` list stays whole for the screens that need every row.

Removes the SKU's stock record.

One SKU's stock record.

Partial update of ONE existing stock row. It never creates one.

Upserts a SKU's stock: on hand, minimum, lead time, cost, MOQ, supplier, price and catalogue fields.

Point-in-time stock levels for trend visualisation.

finished_good, semi_finished, component, raw_material, packaging or service.

Suppliers that sell this SKU, with cost, MOQ and lead time per supplier.

Removes the supplier from the SKU's supplier list.

Sets the supplier's cost, MOQ, lead time and primary flag for the SKU.

Suppliers who raised a SKU's cost at least once in the window, worst first, with the products each one hit hardest. Built only from POs that were actually received — a quoted or rejected order proves nothing was paid.

The tenant's suppliers with contact details, lead times and payment terms.

Adds a supplier with contact details, lead time and payment terms.

Suppliers that POST /po/{id}/send would silently skip — no email and no WhatsApp on file, or a supplier name on PO lines with no record at all (feature 2.5).

Create suppliers from a CSV / Excel file.

Dry run of POST /suppliers/import: what was detected and what would be written. Touches no row.

Suppliers import template: the header row plus two example rows.

Suppliers whose recent lead time is significantly slower than their own history — "Acme is taking 12 days, not 7" (feature 3.3).

Active suppliers, searched and paged on the server (the plain list stays whole for the dropdowns that need every supplier).

Per-supplier performance: real lead time range, on-time rate, fill rate.

Deactivates the supplier (see the reactivate endpoint).

Changes a supplier's contact details, lead time, review period or payment terms.

Creates or updates the unit price a supplier charges from a minimum quantity of a SKU.

Undo a deactivation.

Canonical inventory import template: header row + one example row.

Stock transfers between warehouses, optionally filtered by status.

Creates a stock transfer from one warehouse to another, with its lines.

Cancels a transfer that has not been received.

Close a partial transfer, writing the missing units off as shrinkage.

Records the quantities that arrived at the destination warehouse.

The tenant's warehouses.

Adds a warehouse, optionally as the default.

Names travel as query params, not path segments: a warehouse name may contain a slash and would break path matching once encoded.

Configured lanes only. A pair with no row falls back to the documented default (lead_time_days=1, cost_per_unit=0, fixed_cost=0) everywhere it is consumed — see backend/inventory/transfer_lane_service.py.

Creates or updates the lead time and costs of moving stock between two warehouses.

Set or clear the manual demand share for one warehouse (feature 5.4).

Every SKU that carried an ordering signal (PEDIR_YA/PEDIR_PRONTO) in the window: whether a purchase order followed, and — only where it did not and stock was later observed at or below zero — the estimated unserved units and their value. See `recommendation_reports.cost_of_ignoring` for the conservatism rules (no PO + no observed stockout => no loss claimed; no sale price => units reported, value null).

The SKU's latest recorded recommendation against the previous recorded one, decomposed into avg daily demand, lead time, stock on hand and safety stock — each tagged with whether it came from a new training session (a model opinion) or the tenant's own operational data. Returns `available: false` with a `reason` when there is not yet a previous row to compare against.

Undo a reception: take the received units back out of stock, reset the PO line's `received_qty` and the order's `reception_status`, and remove the lead-time observation(s) that reception taught the supplier scorecard. Refuses (409, with the offending SKU/warehouse named) rather than go negative if some of the received units are no longer in stock. See `reception_service.unreceive_po` for the full reasoning.

Undo `mark_po_sent`: clear `sent_at` so the order stops counting as incoming stock and drops off the cash-payables calendar. Does NOT recall the email/WhatsApp message a prior `/send` may have delivered — that left the system and nothing can pull it back. Refuses once a reception exists against this PO (undo that first). See `reception_service.unsend_po`.

Model Context Protocol endpoint, for an AI client the customer runs.

The active planning period and `active_session_id` — the session the app's own screens show.

Starts generating the session's report files; poll the status endpoint.

Outcome of the recent generation attempts for this session.

Downloads a generated report in the given format.

Removes a saved what-if scenario.

One saved what-if scenario with its parameters and results.

Saved scenarios for this session, newest first.

Save a named what-if scenario for this session.

Run inline rules against the session WITHOUT saving them, so the builder can show base vs scenario before the user commits to a name.

Run a saved scenario and return the BASE vs SCENARIO comparison.

Every schedule this tenant has, with the session's name.

What the scheduler has actually done, newest first.

Stops the session's scheduled retraining.

The session's cron schedule for automatic retraining.

Sets a cron expression for automatic retraining, and whether it is enabled.

Forecast sessions with their state. Paginated with skip and limit.

Creates a forecast session in DRAFT.

The sessions library: every session of the tenant, enriched (dataset name, horizon, SKU count, granularity, headline accuracy, models), searchable, filterable, sortable and paginated. `total` counts the rows matching the filters, so a pager can be drawn.

Deletes the session and its results.

One session's metadata and state.

Changes a session's name, description or tags.

How this forecast was produced: who or what started the run, the dataset's content hash and size, the full configuration, engine and library versions, per-model outcomes, stage timings and a hash of the forecast. Written once when the run ends and never changed. 404 `manifest_not_available` for a session that has not finished a run since manifests were introduced.

Bring an archived session back into the working list. Counts against the plan's saved-forecast ceiling like a new one: at the ceiling it is refused with the same message, and the session stays archived and intact.

Median and p95 training duration over the tenant's last `limit` runs, by catalogue-size bucket and by granularity, read from the lineage manifests (no new storage). For choosing a retrain cadence from evidence.

Readable by every role: any screen showing a scheduled time needs it.

Training runs of this tenant that are queued or running right now.

Cancels a queued or running training job.

A training job's state and progress.

The last `tail` log lines of a training job.

Training jobs run for the session.

Create a NEW session that forecasts from this session's stored models over newer sales, without retraining. The source session is never modified. Counts against the plan's saved-forecast ceiling; runs on the job queue.

Whether a re-forecast with newer sales is on offer for this session: stored models present, newer data than the forecast used, and the refit age of the models. `reason` is a stable code when it is not.

Queues a training run for a configured session. Poll /sessions/{session_id}/train/status.

Returns the latest job status for this session. Alias used by the Frontend — maps to GET /jobs/{job_id} for the most recent job.

Outgoing webhooks and the events they subscribe to.

Subscribes an https URL to business events (purchase orders, stockouts, commitments, jobs). The signing secret is returned once.

The events a webhook can subscribe to and the data keys each carries.

Removes the webhook and its delivery log.

The delivery log: status, attempts, last status code, last error and next retry.

Switches a webhook back on after it was disabled for repeated failures.

Issues a new signing secret, returned once. The old one stops verifying at once.

Queues a signed webhook.test delivery to the webhook.