La API de StockAI

Conecta tu ERP, tu punto de venta o tu propio sistema a StockAI con una API key: el mismo trabajo que haces en la app, sin que nadie la abra.

La API sirve para que otro sistema haga lo que tú harías a mano: subir el export de ventas, pedir un recálculo, leer el semáforo y registrar la orden de compra. Esta página explica cómo funciona sin entrar en código; la referencia completa, endpoint por endpoint y con ejemplos, está en la documentación para desarrolladores.

Las llaves de API

Una llave se crea en Automatización, pestaña «API Keys», con «Generar key». Le pones un nombre para reconocerla (por ejemplo «Integración ERP») y eliges qué puede hacer:

Solo leer

Actúa como un usuario de solo lectura: consulta el semáforo, los pronósticos, tus fuentes de datos y el estado de un entrenamiento, pero no cambia nada.

Leer y escribir

Actúa como un analista: además sube archivos, encola entrenamientos y registra órdenes de compra.

La llave completa empieza por sk_live_ y se muestra una sola vez, al crearla. StockAI no la guarda en ningún lado donde se pueda volver a leer: si la pierdes, crea otra y revoca la anterior. Revocar es inmediato; lo que estuviera usando esa llave deja de funcionar en la siguiente llamada.

Cómo se hace una llamada

Todas las rutas cuelgan de /api/v1 en el dominio de tu instalación, y la llave va en la cabecera Authorization:

curl https://<tu-dominio>/api/v1/planning \
  -H "Authorization: Bearer sk_live_..."

Esa llamada devuelve active_session_id, la actualización con la que se calcula hoy el semáforo. Pídela cada vez en lugar de guardarla: cambia cada vez que se entrena una actualización nueva.

Las respuestas correctas traen tu contenido dentro de data. Los errores traen un error_code estable y un texto en inglés en detail. Si tu sistema necesita decidir qué hacer ante un error, que lo decida por error_code: el texto puede cambiar de redacción, el código no.

Límites y consumo

• 120 llamadas por minuto por llave, en cualquier plan que incluya la API.
• 2.000 llamadas por día por llave en el plan completo; sin tope diario en el plan corporativo.
• Al pasarte recibes un 429 con la cabecera Retry-After, que dice cuántos segundos esperar antes de reintentar.
• Cada llamada que pasa todos los controles suma uno al consumo del día de esa llave. Las llamadas rechazadas no cuentan. Un administrador ve el consumo por clave y por día en la pantalla API.

Qué se puede hacer con una llave, y qué no

Con una llave puedes hacer casi todo lo que haces en la app: inventario, proveedores, pronósticos, fuentes de datos, entrenamientos, escenarios, órdenes de compra y recepciones. Hay cosas que nunca se alcanzan con una llave, a propósito, porque son de una persona y no de un sistema:

• Iniciar sesión, usuarios y roles, y las propias llaves de API.
• Preferencias personales, mensajes del equipo y conversaciones con el asistente.
• Exportar o borrar la cuenta, y la configuración de la instalación.
• Las reglas del semáforo, marcar una orden como pagada y cancelar o reabrir una orden.

Si lo intentas, la respuesta es api_key_route_not_exposed: «Esto no se puede hacer con una API key (usuarios, claves, configuración o borrado de la cuenta). Hazlo desde la app.» Si una llave de solo lectura intenta escribir, recibes api_key_scope_insufficient.

Probarla sin escribir código

La pantalla API de la app es a la vez una guía y una consola: muestra «La URL base» de tu instalación, tiene un campo «Tu API key» donde pegas la llave (vive solo en esa pestaña) y, en cada llamada, un botón «Ejecutar» que la corre de verdad contra tu cuenta y te muestra la respuesta, y un «Ejemplo» con el mismo llamado escrito como curl.

El ciclo típico de una integración

1. Crea una llave «Leer y escribir».
2. Pide GET /planning para saber qué actualización está activa.
3. Sube el export de ventas más reciente sobre la fuente que ya usas.
4. Encola el recálculo (o deja que lo haga una programación) y consulta su estado hasta que diga COMPLETED.
5. Lee el semáforo y arma la orden con la señal y la cantidad recomendada.
6. Cuando la orden salga de verdad, regístrala en StockAI. Sin ese registro la orden no existe para StockAI y nunca se aprende el tiempo de entrega real de tus proveedores.

Si lo que quieres no es que un sistema corra solo sino preguntarle a un asistente de IA qué comprar, mira MCP.