MPA por dentro.
MAG por fuera.
Contrato oficial para integrar Roustix: REST, JWT, multi-tenant, /api/v1, webhooks y buenas prácticas.
No es solo una referencia de endpoints.
Toda la operación.Una sola plataforma.
| Sprint 8 | Estado |
|---|---|
| MAG-01 – 10 | ✅ Entregado |
| Sprint 8 | ✅ MAG v1.0 completo |
01 · Filosofía de la API
La forma oficial de integrarse.
MPA (05) describe la arquitectura interna. MAG (07) define el contrato externo.
| # | Principio |
|---|---|
| 1 | REST predecible · JSON |
| 2 | Tenant-first — toda operación en contexto de empresa |
| 3 | Segura por defecto — JWT, roles, límites |
| 4 | Versionada — /api/v1 estable |
02 · Autenticación JWT
Una identidad.
Un token.
Una empresa.
JWT identifica usuario, tenant, rol, plan y módulos. Sin reenviar credenciales en cada solicitud.
HS256 · SECRET_KEY · ±30 s skew · Refresh POST /api/v1/auth/refresh → MAG v2
03 · Multi-tenant
Una plataforma.
Miles de empresas.
Cero mezcla de datos.
Tenant (Empresa) · middleware Flask · Regla de Oro · 404 anti-enumeración.
Usuario → Tenant → Plan → Módulos → Permisos → Acción
| Componente | Estado |
|---|---|
| JWT + middleware | ✅ |
| Filtrado empresa_id | ✅ |
| Multi-sede | 🟡 |
04 · Recursos REST
La API no expone tablas.
Expone recursos de negocio.
/api/v1 ├── auth · me ├── maintenance/assets · work-orders ├── inventory/products · movements ├── purchasing · sales · crm └── admin · platform
Contrato en inglés · GET POST · data+meta+links · idempotencia
05 · Convenciones de nombres
Una API consistente
es una API predecible.
Style guide oficial · inglés en contrato · snake_case · ISO 8601 · UPPER_SNAKE_CASE errors
06 · Manejo de errores
Los errores también
forman parte del contrato.
Catálogo oficial · cross-tenant → 404 · X-Request-Id · sin stack traces
07 · Versionado
Una API cambia.
El contrato no se rompe.
/api/v1 · legacy + Deprecation/Sunset · OpenAPI por versión
08 · Webhooks
REST responde.
Webhooks notifican.
work_order.created · stock.low · X-Roustix-Signature · X-Event-Id
09 · Ejemplos y SDK
Una buena API se entiende.
Una excelente API también se ejecuta.
cURL · Python · JavaScript · ROUSTIX_API · OpenAPI → SDK · estructura alineada a MAG-04
10 · Límites y buenas prácticas
Una API rápida no basta.
Debe ser estable, segura y predecible.
Rate limit · timeouts · reintentos · paginación · caché · seguridad · checklist integradores
| MAG v1.0 | Estado |
|---|---|
| MAG-01 – 10 | ✅ Completo |
| Sprint 8 | ✅ Finalizado |
Siguiente: Sprint 9 · MSD v1.0 — SDK, OpenAPI y Developer Portal.