Empezar con la API

Qué es la API de StockAI, qué planes la incluyen, cuál es la URL base y cómo hacer tu primera llamada de principio a fin.

La API de StockAI deja que tu ERP, tu punto de venta o un script tuyo haga lo mismo que una persona hace en la app: subir las ventas, actualizar el stock, entrenar, leer el semáforo, registrar y recibir órdenes de compra y sacar las órdenes aprobadas hacia tu ERP. Esta sección es la guía paso a paso; la referencia completa de cada endpoint, generada desde el código, está en la documentación para desarrolladores.

Qué puedes hacer con la API

Catálogo e inventario

Leer y escribir el stock por SKU y bodega, proveedores, bodegas, conteos físicos y traslados. Ver Catálogo e inventario.

Pronósticos y sesiones

Reemplazar el archivo de ventas, entrenar, consultar el estado del entrenamiento y leer pronósticos, precisión y resultados. Ver Pronósticos y sesiones.

Pedidos y proveedores

Registrar órdenes, recibirlas y sacar las aprobadas hacia tu ERP con un cursor. Ver Pedidos y proveedores.

Sincronización

Empujar el stock desde tu sistema en lotes idempotentes y vigilar que esté al día. Ver Sincronización y archivos.

Webhooks

Que StockAI avise a tu sistema cuando se aprueba una orden o un producto está por agotarse. Ver Webhooks.

MCP

Conectar un asistente de IA que lee tu semáforo. Ver MCP.

Quién puede usarla

La API y el servidor MCP son funciones de pago. Lo que decide si tu cuenta los tiene es su plan:

En todos los planes con API, cada llave tiene además un tope de 120 llamadas por minuto. Si tu cuenta no incluye la API, crear una llave o usar una que ya existía se rechaza con 403 y error_code: "plan_feature_locked". Dentro de la cuenta, crear llaves lo pueden hacer analistas y administradores; un usuario de solo lectura no.

curl https://app.stockai.es/api/v1/entitlements \
  -H "Authorization: Bearer $STOCKAI_KEY"

# "data": {
#   "tier": "pro",
#   "limits":   { "max_api_keys": 3, "max_api_calls_per_day": 2000, ... },
#   "features": { "api": true, "mcp": true, "whatsapp_bot": true },
#   "usage":    { "max_api_keys": 1, ... }
# }

GET /entitlements te dice, con la misma llave, en qué plan está tu cuenta, sus topes y cuántas llaves usa: útil para que tu integración avise antes de chocar con un límite.

La URL base y el formato de las respuestas

https://app.stockai.es/api/v1

Si StockAI corre en un servidor propio de tu empresa, cambia app.stockai.es por su dominio; todo lo demás es igual. Todas las rutas de esta guía cuelgan de /api/v1.

Toda respuesta correcta viene envuelta del mismo modo. Lo que buscas está siempre dentro de data:

{
  "success": true,
  "data": { ... },
  "meta": { "timestamp": "2026-10-23T02:45:23.756880+00:00" }
}

Una respuesta con error no trae data: trae detail (un texto en inglés para personas) y casi siempre error_code y error_params. Tu código debe decidir por error_code, nunca por el texto. Los detalles están en Límites y errores.

Tu primera llamada, paso a paso

1. Entra a StockAI como analista o administrador y abre Automatización, pestaña «API Keys».
2. Pulsa «Generar key», escribe un nombre que diga qué sistema la usará (por ejemplo «ERP nocturno»), elige «Solo leer» y pulsa «Crear».
3. Copia la llave con «Copiar». Empieza por sk_live_ y no se vuelve a mostrar. Guárdala en el gestor de secretos de tu sistema, nunca en el código.
4. Desde una terminal, llama a GET /planning con la llave en la cabecera Authorization:

export STOCKAI_KEY="sk_live_..."   # from your secret manager, never from the repository

curl https://app.stockai.es/api/v1/planning \
  -H "Authorization: Bearer $STOCKAI_KEY"

La respuesta te dice con qué detalle (period: día, semana o mes) y sobre cuántos períodos (horizon) está calculado todo lo demás, y sobre todo active_session_id: la actualización con la que la app calcula hoy el semáforo.

{
  "success": true,
  "data": {
    "period": "daily",
    "horizon": 14,
    "available_periods": ["daily", "weekly"],
    "max_horizon": 90,
    "period_source": "auto",
    "period_reason": "natural_frequency",
    "requested_period": null,
    "active_session_id": "sess_cc9ab9137953"
  },
  "meta": { "timestamp": "2026-10-23T02:45:23.756880+00:00" }
}

1. Con ese id ya puedes leer el semáforo: GET /inventory/status?session_id=... (el parámetro es opcional; sin él se usa la sesión activa).
2. Cuando el sistema vaya a escribir (subir ventas, registrar órdenes), crea una segunda llave «Leer y escribir». Mira Llaves y autenticación.
3. Antes de tocar datos reales, prueba contra un sandbox.

Probar sin escribir código

La pantalla API de la app muestra la URL base de tu instalación, tiene un campo para pegar tu llave y un botón «Ejecutar» en cada llamada que la corre de verdad contra tu cuenta. Sirve para ver la forma real de una respuesta antes de programar nada.