Documentación pública

10 · Límites y buenas prácticas

MAG-10-LIM · Límites y buenas prácticas

Una API rápida no es suficiente. Debe ser estable, segura y predecible.

Toda la operación. Una sola plataforma.

Objetivo del capítulo

Definir las políticas oficiales de uso responsable, límites operativos y buenas prácticas para consumir la API de Roustix.

Este capítulo cierra la especificación MAG v1.0, consolidando las reglas que deben seguir integradores, SDKs y futuros clientes móviles para garantizar una plataforma escalable y confiable.

1 · Filosofía

La API de Roustix es un recurso compartido entre miles de empresas.

Por ello, todas las integraciones deben:

respetar los límites establecidos
minimizar llamadas innecesarias
manejar errores de forma adecuada
mantener compatibilidad con futuras versiones

Una buena integración consume la API de forma eficiente, no agresiva.

2 · Rate Limiting

Para proteger la plataforma se aplican límites por IP, usuario y tenant.

Endpoint	Límite
Login	5 intentos / 15 min
API autenticada	120 solicitudes / minuto (valor inicial)
Webhooks	Sin límite de recepción
Exportaciones	Según plan contratado

Cuando se supera un límite:

HTTP/1.1 429 Too Many Requests

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Se ha excedido el límite de solicitudes."
  }
}

El servidor puede incluir:

Retry-After: 60

→ MAG-06 · RATE_LIMIT_EXCEEDED

Implementación hoy:

Endpoint	Estado
`POST /api/auth/login`	✅ 5 / 15 min por IP (`@limiter`)
API autenticada general	📋 Planificado (120 / min)
Exportaciones por plan	📋 Planificado

Legacy hoy: login en /api/auth/login — contrato v1: /api/v1/auth/login (MAG-07).

3 · Timeouts

Los clientes deben configurar tiempos de espera razonables.

Operación	Recomendado
Lectura	10 s
Escritura	30 s
Exportaciones	60 s
Webhooks	5 s

Nunca esperar indefinidamente.

4 · Reintentos

Solo deben reintentarse errores temporales.

Código	Reintentar
429	✅ Sí
503	✅ Sí
Timeout	✅ Sí
500	⚠️ Opcional
400	❌ No
401	❌ No
403	❌ No
404	❌ No
422	❌ No

Se recomienda backoff exponencial.

Ejemplo:

1 s → 2 s → 4 s → 8 s → 16 s

Respetar el header Retry-After cuando esté presente.

→ MAG-06 · Reintentos

5 · Paginación

Nunca solicitar listas completas cuando existan múltiples páginas.

Correcto:

GET /api/v1/inventory/products?page=1&page_size=50

Incorrecto:

GET /api/v1/inventory/products?page_size=100000

Límite máximo permitido:

page_size = 200

Para volúmenes grandes usar exportaciones (MRL) en lugar de paginación masiva.

→ MAG-04 · Paginación

6 · Caché

Los datos que cambian poco pueden almacenarse temporalmente.

Ejemplos cacheables:

activos
productos
sedes
usuarios

No deben almacenarse en caché:

permisos
autenticación
stock crítico
órdenes activas

Cuando el recurso incluya ETag o Last-Modified, el cliente debería utilizarlos.

Incluir siempre la clave de tenant (empresa_id / slug) en la clave de caché del cliente.

7 · Seguridad

Toda integración debe:

utilizar HTTPS en producción
proteger el JWT
validar certificados
renovar tokens expirados
verificar firmas de Webhooks

Nunca:

almacenar tokens en texto plano
compartir un mismo JWT entre empresas
enviar credenciales por URL

→ MAG-02 · JWT · MAG-08 · Webhooks

8 · Diseño de clientes

Los clientes oficiales deben:

reutilizar conexiones HTTP
centralizar autenticación
registrar X-Request-Id
encapsular el manejo de errores
utilizar el SDK oficial cuando exista

No construir URLs manualmente.

→ MAG-09 · SDK

9 · Observabilidad

Toda integración debería registrar:

endpoint
método HTTP
tiempo de respuesta
código HTTP
error.code
X-Request-Id

Ejemplo:

GET /maintenance/assets
200
152 ms
Request ID: 6c1d0d82...

Esto facilita el diagnóstico junto con el equipo de soporte.

10 · Compatibilidad

Los clientes deben asumir que pueden aparecer:

nuevos campos JSON
nuevos recursos
nuevos módulos
nuevos códigos opcionales

No deben fallar ante propiedades desconocidas.

Solo deben utilizar los campos documentados.

→ MAG-07 · Versionado

11 · Integraciones recomendadas

Roustix está diseñado para integrarse con:

Plataforma	Estado
Power BI	📋
Excel	✅
ERP	📋
CRM	📋
Zapier	Roadmap
Make	Roadmap
n8n	Roadmap
Microsoft Power Automate	Roadmap

Todas las integraciones utilizan el contrato MAG.

12 · Checklist para integradores

Antes de poner una integración en producción:

[ ] Utiliza /api/v1
[ ] Implementa autenticación JWT
[ ] Maneja correctamente 401, 403, 404, 429 y 503
[ ] Respeta la paginación
[ ] Implementa backoff exponencial
[ ] Registra X-Request-Id
[ ] Utiliza HTTPS
[ ] No depende de campos no documentados
[ ] Valida firmas de Webhooks (si aplica)

13 · Roadmap

Próximas capacidades del contrato MAG:

Refresh Tokens
OAuth 2.1
API Keys para servicios
GraphQL Gateway (evaluación)
SDK oficiales
Portal para desarrolladores
Sandbox público
Marketplace de integraciones

Siguiente hito: · MSD v1.0 (Roustix SDK & Developer Portal)

Entrega MSD	Descripción
Portal	developer.roustix.app
OpenAPI 3.1	`openapi.v1.yaml`
SDK	Python · JavaScript · PHP
CLI	`roustix-cli`
Sandbox	API Explorer
Quick Start	Guías paso a paso
Colecciones	Postman e Insomnia

Filosofía del capítulo

Una API bien diseñada no solo define qué puede hacerse, sino también cómo hacerlo correctamente. Las buenas prácticas garantizan que todas las integraciones se comporten de forma consistente, segura y eficiente, permitiendo que Roustix escale sin sacrificar estabilidad.

MAG-10 cierra la especificación oficial de Roustix API Guidelines (MAG v1.0), estableciendo las reglas de convivencia entre la plataforma y todos sus consumidores.

MAG v1.0 · Índice completo

Código	Capítulo	Estado
MAG-01	Filosofía de la API	✅
MAG-02	Autenticación JWT	✅
MAG-03	Multi-tenant	✅
MAG-04	Recursos REST	✅
MAG-05	Convenciones de nombres	✅
MAG-06	Manejo de errores	✅
MAG-07	Versionado	✅
MAG-08	Webhooks	✅
MAG-09	Ejemplos y SDK	✅
MAG-10	Límites y buenas prácticas	✅

· Estado

(MAG v1.0) queda 100% completado.

Con este sprint, Roustix dispone de un estándar de API de nivel empresarial — comparable en estructura documental con plataformas como Stripe, GitHub, Microsoft Graph o Notion — adaptado a la arquitectura multi-tenant y modular de Roustix.

← 09 · Ejemplos Portal SDK →