Documentación pública · v1.0.0

02 · Developer Portal

MSD-02-PORT · Developer Portal

La API es el producto.

El Developer Portal es la puerta de entrada.

Toda la operación. Una sola plataforma.

Objetivo del capítulo

Definir el Developer Portal oficial de Roustix (Portal para Desarrolladores), el punto único desde el cual cualquier desarrollador puede:

descubrir la plataforma
autenticarse
consultar la documentación
probar la API
descargar SDKs
seguir la evolución del ecosistema

Si MAG define el contrato técnico, MSD define la experiencia del desarrollador.

1 · Filosofía

El Portal para Desarrolladores no es únicamente un sitio web.

Es la interfaz oficial entre Roustix y los integradores.

Debe permitir que un desarrollador pueda:

entender la plataforma
obtener un token
realizar su primera llamada
descargar el SDK
consultar OpenAPI
probar endpoints
seguir cambios del contrato

Todo desde un único lugar.

→ MSD-01 · Filosofía del ecosistema

2 · URL oficial

Producción

https://developer.roustix.app

Desarrollo

http://127.0.0.1:5000/msd/

python run.py

El Developer Portal forma parte del ecosistema Roustix, pero mantiene una identidad propia orientada exclusivamente a desarrolladores.

Recurso relacionado	URL local
API	`http://127.0.0.1:5000/api/v1`
MAG (contrato)	`http://127.0.0.1:5000/mag/`
Docs suite	`http://127.0.0.1:5000/docs/`

Estado del Portal

Aspecto	Valor
Portal	MSD v1.0.0
API	MAG v1.0
OpenAPI	v1.0 (core publicado)
SDK	Roadmap · estrategia MSD-04 ✅

3 · Estructura general

Developer Portal
│
├── Inicio
├── Quick Start
├── API Reference
├── OpenAPI
├── SDK
├── CLI
├── Sandbox
├── Changelog
├── Estado API
└── Comunidad

Cada sección responde a una necesidad distinta durante el ciclo de integración.

Sección	Capítulo MSD	Fase
Quick Start	MSD-07	📋
OpenAPI · API Reference	MSD-03	▶️ Siguiente
SDK	MSD-04	📋
CLI	MSD-05	📋
Sandbox · Explorer	MSD-06	📋
Colecciones	MSD-08	📋
Publicación	MSD-09	📋

4 · Página principal

La portada resume todo el ecosistema.

ROUSTIX
Developer Portal

Toda la operación.
Una sola plataforma.

[ Comenzar ]

Quick Start    API Reference    OpenAPI    SDK    Sandbox

Debe permitir comenzar una integración en menos de diez minutos.

Above the fold:

Hero + CTA «Comenzar» → Quick Start
Accesos directos — Quick Start · API Reference · OpenAPI · SDK · Sandbox
Badge de versión API (v1.0) y estado operativo
Callout multi-tenant — JWT + empresa_slug

5 · Navegación

El menú principal mantiene la misma organización documental del ecosistema.

Sección	Contenido
Quick Start	Primera integración
API	Documentación MAG
OpenAPI	Especificación REST
SDK	Librerías oficiales
CLI	Herramienta de línea de comandos
Sandbox	Ambiente de pruebas
Changelog	Cambios del contrato
Estado	Disponibilidad de la API

Barra global

Elemento	Destino
Logo · Roustix Developers	Inicio portal
Quick Start	MSD-07
API Reference	MAG + OpenAPI UI
SDK	MSD-04
Sandbox	MSD-06
Changelog	Historial API · MSD

6 · Integración con MAG

El Portal para Desarrolladores no duplica documentación.

MAG continúa siendo la referencia técnica.

Ejemplo — API Reference · Maintenance Assets:

Maintenance · Assets
Ver especificación → MAG-04

Cada recurso del portal enlaza directamente con el capítulo correspondiente.

Recurso portal	Capítulo MAG
Autenticación	MAG-02
Multi-tenant	MAG-03
Recursos REST	MAG-04
Errores	MAG-06
Versionado	MAG-07
Webhooks	MAG-08
Buenas prácticas	MAG-10

Regla: enlazar, nunca copiar contenido MAG al portal.

7 · Integración con OpenAPI

El Developer Portal utiliza OpenAPI como fuente de información.

openapi.v1.yaml
        │
        ▼
     Portal
        │
        ▼
Referencia interactiva

No existen definiciones manuales duplicadas.

La documentación visible debe generarse desde el contrato OpenAPI.

→ MSD-03 · OpenAPI 3.1 · docs/api/openapi.v1.yaml

8 · SDK oficiales

Desde el Portal para Desarrolladores podrán descargarse los SDK oficiales.

Python:

pip install roustix

JavaScript:

npm install @roustix/sdk

PHP:

composer require roustix/sdk

Cada SDK comparte exactamente el mismo contrato definido por MAG.

→ MSD-04 · SDK oficiales

9 · Sandbox

El portal ofrece un ambiente de pruebas aislado.

Elemento	Valor
Tenant	`empresa-demo`
Token	JWT temporal
Datos	Ficticios
Producción	Sin afectar

Cada desarrollador puede experimentar libremente.

→ MSD-06 · Sandbox · MAG-03

10 · API Explorer

Cada endpoint podrá ejecutarse desde el navegador.

GET /api/v1/me

[ Ejecutar ]

Respuesta:

{
  "user": "...",
  "empresa": "..."
}

El Explorer utiliza el mismo OpenAPI publicado.

→ MSD-06 · Sandbox & API Explorer

11 · Changelog

Todas las modificaciones públicas de la API aparecen registradas.

Fecha	Versión	Cambio
2026-07-10	v1.0.0	Publicación inicial MAG · contrato `/api/v1`
—	v1.0.1	Nuevo endpoint Inventory (planificado)
—	v1.1.0	Webhooks implementados (planificado)

El historial permite conocer la evolución del contrato.

→ MAG-07 · Versionado · MSD changelog

12 · Estado de la API

El portal incorpora un panel de disponibilidad.

API REST
● Operativa
99.95%

Información visible:

disponibilidad
incidentes
mantenimientos
historial

Estado actual: panel planificado · blueprint /msd/ operativo en desarrollo.

13 · Documentación relacionada

El Portal para Desarrolladores concentra toda la documentación pública conectada.

MAG
├── API · JWT · Recursos · Versionado · Webhooks
MRL
MPA
MSD

Manual	Rol en portal
MAG	Contrato API · guías profundas
MRL	Exportaciones · reportes
MSD	Este manual · herramientas

Toda la documentación permanece conectada — sin silos.

14 · Diseño

El Developer Portal reutiliza el Design System de Roustix.

Componentes:

Cards
Sidebar
Breadcrumb
Hero
Search
Tabs
Code Blocks
Dark Mode

No existen estilos independientes. La identidad visual permanece consistente.

Referencia	Manual
Marca	MBB
UI	MDL · componentes `mtx-*`
Docs shell	Brand Book CSS · `msd-docs.css`

15 · Arquitectura

Pipeline documental del Portal para Desarrolladores:

Markdown
      │
      ▼
  OpenAPI
      │
      ▼
Generador Docs
      │
      ▼
Flask Blueprint
      │
      ▼
Developer Portal

Archivos actuales:

Archivo	Rol
`docs/msd/`	Manual MSD · capítulos · catálogo HTML
`docs/api/openapi.v1.yaml`	Contrato machine-readable (MSD-03)

Toda la documentación continúa viviendo como archivos Markdown versionados en el repositorio.

16 · Arquitectura del ecosistema

Relación entre los componentes del Developer Portal:

                 Developer Portal
                        │
        ┌───────────────┼───────────────┐
        ▼               ▼               ▼
     OpenAPI          MAG Docs        Quick Start
        │               │
        ▼               ▼
       SDK         API Reference
        │
        ▼
      Sandbox

Este diagrama resume cómo MSD organiza MAG, OpenAPI, SDK y sandbox antes de profundizar en cada capítulo.

17 · Roadmap

Versiones futuras del Developer Portal incorporarán:

Portal
├── Search
├── API Explorer
├── SDK
├── Sandbox
├── autenticación del desarrollador
├── API Keys
├── Playground
├── snippets automáticos
├── documentación por módulo
├── ejemplos interactivos
└── IA contextual

Search será uno de los componentes principales — acceso unificado a MAG, MSD, OpenAPI y guías.

Fase	Entrega
Fase 0 ✅	Blueprint `/msd/` · catálogo MSD
Fase 1	Nav completa · home con CTA · Search (básico)
Fase 2	OpenAPI UI · referencia interactiva (MSD-03)
Fase 3	Sandbox · API Explorer (MSD-06)
Fase 4	`developer.roustix.app` producción

18 · Buenas prácticas

#	Regla
1	OpenAPI es la única fuente técnica
2	No duplicar documentación de MAG
3	Todo ejemplo debe ser ejecutable
4	El Quick Start debe mantenerse actualizado
5	Todo SDK debe generarse desde OpenAPI
6	El Portal es público
7	Todo cambio de API debe reflejarse en el Changelog

Filosofía del capítulo

Una buena API necesita una buena documentación.

Un gran producto necesita una excelente experiencia para desarrolladores.

El Developer Portal convierte la documentación de Roustix en una plataforma viva, donde descubrir, aprender, integrar y evolucionar ocurren desde un único lugar. Es el punto de entrada oficial para todo desarrollador que construya sobre Roustix.

← 01 · Filosofía 03 · OpenAPI →