Sandbox y versiones

Un entorno aparte con datos de demostración para construir tu integración sin tocar tus datos reales, y la política de versiones con sus cabeceras Deprecation y Sunset.

En esta página
  1. El sandbox
  2. Política de versiones
  3. Las cabeceras Deprecation y Sunset

El sandbox

Un sandbox es una cuenta desechable, separada de la tuya, con la historia de ventas de demostración ya cargada y una llave de escritura ya creada. Construyes y pruebas contra él con la misma URL y las mismas rutas que en producción; cuando funciona, cambias la llave.

Quién lo crea
Un administrador de la cuenta, desde la tarjeta «Sandbox para desarrolladores» en Automatización → «API Keys». Una llave de API no puede crear sandboxes.
Cuánto dura
7 días. Después se borra solo, con sus datos y su llave. Se puede borrar antes con «Eliminar».
Cuántos
Hasta 2 vivos a la vez por empresa (409 sandbox_limit_reached si pides un tercero). Una cuenta de prueba no puede crear sandboxes.
Sus límites
Los de una cuenta de prueba: 30 SKUs, 1 llave, 120 llamadas por minuto y 200 por día.
Aislamiento
La llave del sandbox no alcanza tu cuenta real, y tus llaves reales no alcanzan el sandbox: cada llamada se limita a la cuenta de su llave.
Sin salida
El sandbox no puede mandar correos ni WhatsApp a nadie.
  1. Como administrador, abre Automatización, pestaña «API Keys», y baja hasta «Sandbox para desarrolladores».
  2. Pulsa «Crear sandbox». Aparece «Sandbox creado» con dos datos: «Clave de API del sandbox:» y «Acceso para ver qué hicieron tus llamadas en la aplicación:» (un correo y una contraseña).
  3. Copia la clave: «Se muestra una sola vez: cópialo ahora.».
  4. Si quieres ver en la app lo que hicieron tus llamadas, entra con ese acceso en otra ventana privada.
  5. Cuando termines, pulsa «Eliminar» en su fila y confirma «¿Eliminar este sandbox?». Tus datos reales no se tocan.
# 1. An administrator presses "Create sandbox" (Automation > API Keys).
#    The card shows the sandbox key ONCE, plus a login to look at it in the app.
export STOCKAI_KEY="sk_live_..."      # the SANDBOX key

# 2. Build against it exactly as against production: same URL, same routes.
curl https://app.stockai.es/api/v1/planning -H "Authorization: Bearer $STOCKAI_KEY"

# 3. When it works, swap the key for a production one. Nothing else changes.

Política de versiones

Todas las rutas viven en /api/v1. Dentro de una versión hay cambios que pueden ocurrir en cualquier momento y cambios que nunca ocurren:

Pueden llegar sin aviso
Un endpoint nuevo, un campo nuevo en una respuesta, un parámetro opcional nuevo, un error_code nuevo para una situación nueva. Escribe tu cliente para ignorar los campos que no conoce.
Nunca dentro de v1
Quitar o renombrar un endpoint, un campo o un parámetro; cambiar el tipo o el significado de un campo; volver obligatorio un campo opcional; cambiar un error_code existente.
Un cambio que rompe
Sale como versión nueva (/api/v2). La anterior sigue funcionando al menos 12 meses después del anuncio.
Retirar un solo endpoint
Con al menos 180 días de aviso. Sigue funcionando hasta la fecha de retiro.

Las cabeceras Deprecation y Sunset

Desde el día en que se anuncia el retiro de un endpoint, cada respuesta suya trae estas cabeceras, así tu sistema se entera por la propia llamada:

HTTP/1.1 200 OK
Deprecation: @1798761600
Sunset: Tue, 29 Jun 2027 00:00:00 GMT
Link: </v2/alerts>; rel="successor-version", <https://app.stockai.es/desarrolladores#versionado>; rel="deprecation"
Deprecation
El momento del anuncio, como @ + segundos Unix (RFC 9745).
Sunset
La fecha HTTP desde la que el endpoint puede desaparecer (RFC 8594).
Link con rel="successor-version"
La ruta que lo reemplaza, cuando hay una.
Link con rel="deprecation"
La página de esta política.

Hoy ningún endpoint está en retiro, así que no verás estas cabeceras. Registra las cabeceras de respuesta en tus logs, o alerta si aparece Sunset, para enterarte a tiempo el día que llegue.