Documentación pública · v1.0.0

06 · Sandbox y API Explorer

MSD-06-SBOX · Sandbox y API Explorer

Antes de integrar en producción, todo comienza en el Sandbox.

Toda la operación. Una sola plataforma.

Objetivo del capítulo

Definir el entorno oficial de pruebas (Sandbox) y el API Explorer de Roustix, permitiendo a desarrolladores, partners e integradores experimentar con la API en un entorno completamente aislado, utilizando datos de demostración y el contrato oficial de MAG v1.

El Sandbox proporciona una experiencia segura para desarrollar, validar integraciones y aprender a utilizar la plataforma sin riesgo para información de clientes.

→ MSD-02 · Developer Portal · MSD-03 · OpenAPI

1 · Filosofía

Toda integración debe poder desarrollarse sin acceder a un entorno productivo.

El Sandbox replica el comportamiento de la API oficial utilizando datos de demostración y aislamiento multi-tenant.

Developer
      │
      ▼
Developer Portal
      │
      ▼
 API Explorer
      │
      ▼
   Sandbox
      │
      ▼
  MAG v1

El comportamiento funcional debe ser equivalente al de producción — mismos endpoints, mismos códigos de error, mismo envelope JSON.

Producción	Sandbox
Datos reales de clientes	Datos ficticios
Integraciones externas	Deshabilitadas
SLA completo	Rate limit reducido
Persistencia indefinida	Reinicio periódico

2 · Objetivos

El Sandbox permite:

aprender la API
probar autenticación JWT
consumir recursos REST
validar SDK
probar la CLI
generar ejemplos
realizar pruebas automatizadas

Nunca debe utilizar información real de clientes.

3 · Tenant de demostración

Tenant oficial:

empresa-demo

Recurso	Estado
Activos	Datos de ejemplo
Inventario	Datos de ejemplo
Órdenes de trabajo	Datos de ejemplo
Compras	Datos de ejemplo
Usuarios	Limitados
Auditoría	Simulada

Los datos pueden reiniciarse periódicamente — los integradores no deben asumir persistencia a largo plazo.

→ MAG-03 · Multi-tenant

Entorno local (desarrollo):

python run.py
# Tenant demo según seed de la base de datos local

4 · API Explorer

El Portal para Desarrolladores incorpora un explorador interactivo basado en OpenAPI 3.1.

GET /api/v1/maintenance/assets

Funciones:

editar parámetros
ejecutar solicitudes
visualizar respuestas
copiar ejemplos
generar código

El Explorer consume openapi.v1.yaml — no definiciones duplicadas.

URL	Rol
`/msd/` → sección Sandbox	Acceso desde portal
OpenAPI spec	`/api/v1/openapi.json`

5 · Autenticación

El Sandbox utiliza el mismo flujo definido en MAG-02:

POST /api/v1/auth/login

Credenciales de demostración (publicadas únicamente en el Developer Portal):

Campo	Valor demo
Usuario	(publicado en portal)
Contraseña	(publicado en portal)
Empresa	`empresa-demo`

curl -X POST http://127.0.0.1:5000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"***","empresa_slug":"empresa-demo"}'

Legacy hoy: POST /api/auth/login

Las credenciales oficiales nunca se incluyen en el repositorio — solo en el portal o documentación controlada.

6 · Datos de ejemplo

Cada módulo incluye información representativa del contrato MAG:

Maintenance
├── Assets
├── Work Orders
├── Lubrication
└── Schedules

Inventory
├── Products
├── Stock
└── Movements

Todos los ejemplos siguen el contrato MAG-04 y convenciones MAG-05.

Ejemplo — activos demo:

{
  "data": [
    {
      "asset_id": 1,
      "asset_code": "M-001",
      "name": "Compresor A",
      "status": "operational",
      "critical": true
    }
  ],
  "meta": {
    "pagination": { "page": 1, "page_size": 50, "total": 3 }
  }
}

7 · Limitaciones

El Sandbox posee restricciones deliberadas:

Restricción	Motivo
Sin envío de correos reales	Seguridad
Sin integraciones externas	Aislamiento
Datos reiniciables	Consistencia
Rate limit reducido	Protección
Sin información sensible	Privacidad

→ MAG-10 · Límites

8 · Generación de ejemplos

El Explorer permite ejecutar cualquier endpoint documentado.

Ejemplo:

GET /api/v1/me

Respuesta inmediata en el navegador.

También genera ejemplos para:

Lenguaje	Origen
cURL	OpenAPI operation
Python	SDK / requests
JavaScript	fetch / SDK
PHP	SDK

Utilizando OpenAPI como fuente (MSD-03).

9 · Casos de uso

El Sandbox está pensado para:

Audiencia	Uso
Desarrolladores	Primera integración
Partners	Validación de conectores
Consultores	POC rápidos
Integradores	Pruebas de contrato
Capacitación	Formación interna
Demostraciones comerciales	MCM · ventas

Nota: el Sandbox no sustituye un entorno de staging corporativo del cliente.

Herramientas complementarias:

MSD-04 · SDK — pruebas desde código
MSD-05 · CLI — pruebas desde terminal
MSD-08 · Colecciones — Postman · Insomnia

10 · Buenas prácticas

#	Regla
1	Utilizar Sandbox antes de Producción
2	No almacenar datos importantes en el tenant demo
3	Asumir reinicio periódico de la información
4	Validar integraciones con OpenAPI
5	Utilizar siempre JWT
6	No depender de IDs específicos entre sesiones
7	Probar errores MAG-06 con respuestas simuladas (roadmap)

11 · Roadmap

Próximas funcionalidades:

datos de prueba personalizables
reinicio automático del tenant (POST /sandbox/reset)
colecciones Postman integradas en el Explorer
API Explorer avanzado (historial · entornos)
Mock Server (Prism) para desarrollo offline
pruebas de Webhooks (MAG-08)
simulación de errores MAG-06
escenarios completos por módulo (maintenance · inventory · sales)

Fase	Entrega
Fase 0 ✅	Especificación MSD-06 · tenant `empresa-demo` documentado
Fase 1	Sección Sandbox en `/msd/`
Fase 2	API Explorer UI desde OpenAPI
Fase 3	Sandbox API dedicado · reset programado

Filosofía del capítulo

El Sandbox convierte la documentación en una experiencia interactiva. Un desarrollador no solo lee cómo funciona la API: la prueba, experimenta con ella y valida su integración antes de escribir una sola línea de código para producción.

MSD-06 establece el entorno oficial de experimentación de Roustix, garantizando que cualquier integración pueda desarrollarse de forma segura, repetible y alineada con el contrato definido por MAG.

← 05 · CLI 07 · Quick Start →