Pronósticos y sesiones por API

Cómo subir las ventas, entrenar y esperar el resultado, y leer pronósticos, precisión y resultados de una sesión.

Una sesión es una actualización del pronóstico: unas ventas, una configuración y el resultado de entrenarla. La app trabaja con la sesión activa, la que devuelve GET /planning en active_session_id. Las sesiones nunca se borran: DELETE /sessions/{id} las archiva y POST /sessions/{id}/restore las devuelve.

El ciclo nocturno completo

Este es el trabajo que la mayoría de las integraciones necesita: reemplazar el archivo de ventas, reentrenar y esperar.

#!/usr/bin/env bash
set -euo pipefail
API=https://app.stockai.es/api/v1
AUTH="Authorization: Bearer $STOCKAI_KEY"

# 1. Replace the sales file in place (same source id, same column mapping)
curl -sf -X POST "$API/data-sources/$SOURCE_ID/file" -H "$AUTH" -F "file=@/exports/sales.csv"

# 2. Which session is active right now (ask every time, never hard-code it)
SESSION=$(curl -sf "$API/planning" -H "$AUTH" | jq -r '.data.active_session_id')

# 3. Retrain (skip this if the session has a schedule: it retrains when the file changes)
curl -sf -X POST "$API/sessions/$SESSION/train" -H "$AUTH" \
     -H "Content-Type: application/json" -d '{}'

# 4. Wait while it is QUEUED or RUNNING. Watching only RUNNING exits on the first pass.
while :; do
  ST=$(curl -sf "$API/sessions/$SESSION/train/status" -H "$AUTH" | jq -r '.data.status')
  case "$ST" in QUEUED|RUNNING) sleep 10 ;; *) break ;; esac
done
echo "Training finished: $ST"

1. Busca una vez el id de tu fuente de ventas con GET /data-sources (o GET /datasets) y guárdalo en tu configuración: ese id no cambia.
2. Cada noche reemplaza el archivo con POST /data-sources/{id}/file (multipart, campo file). La fuente conserva su id y su mapeo de columnas. Acepta .csv, .xlsx, .xls, .parquet y .json.
3. Pide la sesión activa con GET /planning.
4. Si la sesión tiene una tarea programada, StockAI reentrena solo cuando el archivo cambia y puedes saltarte este paso. Si no, encola el entrenamiento con POST /sessions/{id}/train.
5. Consulta GET /sessions/{id}/train/status cada pocos segundos mientras diga QUEUED o RUNNING. Termina en COMPLETED o FAILED.

{
  "session_id": "sess_cc9ab9137953",
  "status": "RUNNING",
  "job_id": "job_fe6d1a76b4f2",
  "job": {
    "status": "RUNNING",
    "created_by": "usr_97c71ad04a86",
    "progress": { "step": "ml_training", "message": "Training ML models", "percent": 27 },
    "error": null
  }
}

Fuentes de datos y datasets

Sesiones y configuración

Reentrenar con horario

curl -X POST https://app.stockai.es/api/v1/sessions/$SESSION/schedule \
  -H "Authorization: Bearer $STOCKAI_KEY" -H "Content-Type: application/json" \
  -d '{"cron_expr":"0 6 * * 1","enabled":true}'

cron_expr es una expresión cron (en el ejemplo: lunes a las 6:00). GET /schedules lista todas, GET /schedules/history sus corridas y DELETE /sessions/{id}/schedule quita el horario. Es lo mismo que la pestaña «Tareas programadas» de Automatización.

Leer el pronóstico

curl "https://app.stockai.es/api/v1/sessions/$SESSION/forecast-series/SKU-001" \
  -H "Authorization: Bearer $STOCKAI_KEY"

# "data": {
#   "sku": "SKU-001", "model": "ets", "available_models": ["ets"],
#   "historical": [{ "date": "2024-01-01", "value": 25.0 }, ...],
#   "forecast":   [{ "date": "2025-04-01", "value": 40.67,
#                    "p10": 35.53, "p50": 40.67, "p90": 45.81,
#                    "lower": 34.07, "upper": 47.26 }, ...]
# }

Datasets para BI

Para Power BI, Excel o Looker hay tablas planas pensadas para leerse enteras: /datasets/forecast-points, /datasets/inventory-status, /datasets/accuracy, /datasets/purchase-order-lines, /datasets/receptions y /datasets/committed-demand; /datasets/schema describe sus columnas. Aceptan format, page, limit y session_id. Como muchas herramientas de BI no dejan poner Authorization, usa X-API-Key.

curl "https://app.stockai.es/api/v1/datasets/forecast-points?format=csv&page=1" \
  -H "X-API-Key: $STOCKAI_KEY" -o forecast-points.csv