Documentación pública · v1.0.0

07 · Quick Start

MSD-07-QS · Quick Start

La mejor documentación es aquella que permite realizar la primera integración en menos de diez minutos.

Toda la operación. Una sola plataforma.

Objetivo del capítulo

Definir la guía oficial de Quick Start de Roustix, permitiendo que cualquier desarrollador:

obtenga un JWT
consulte la API
recupere su primer recurso

…utilizando el contrato definido por MAG v1.

El Quick Start es el punto de entrada recomendado para todos los nuevos integradores y constituye el recorrido principal del Developer Portal.

→ MSD-02 · Developer Portal · MSD-06 · Sandbox

1 · Filosofía

La primera experiencia determina la percepción de toda la plataforma.

Un desarrollador debe ser capaz de:

autenticarse
obtener un JWT
consultar la API
recibir una respuesta válida
comprender el flujo completo

…sin necesidad de leer toda la documentación.

Crear cuenta / credenciales Sandbox
      │
      ▼
     Login
      │
      ▼
     JWT
      │
      ▼
 Primer endpoint
      │
      ▼
Primera integración

Objetivo: completar este recorrido en menos de 10 minutos.

2 · Requisitos

Antes de comenzar, el desarrollador necesita:

Requisito	Detalle
Developer Portal	/msd/
Credenciales Sandbox	tenant `empresa-demo`
Conexión	HTTPS (prod) · HTTP local en dev
Herramienta	cURL · Postman · SDK · CLI

Entorno: toda la guía utiliza el Sandbox — nunca producción en la primera prueba.

Local:

python run.py
# API: http://127.0.0.1:5000

Variables recomendadas:

export ROUSTIX_API=http://127.0.0.1:5000/api/v1
export ROUSTIX_TOKEN=<jwt>

Legacy hoy: login en /api/auth/login · /me en /api/me · activos en /api/activos. Los pasos muestran contrato v1; ver notas por paso.

3 · Paso 1 · Autenticación

Solicitud:

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "demo.user",
  "password": "********",
  "empresa_slug": "empresa-demo"
}

Respuesta (contrato v1):

{
  "token": "<jwt>",
  "expires_in": 28800
}

Legacy hoy:

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

{
  "token": "<jwt>",
  "empresa_id": 4,
  "empresa_slug": "empresa-demo",
  "rol": "admin",
  "username": "admin"
}

Conservar el JWT para las siguientes solicitudes.

→ MAG-02 · JWT

4 · Paso 2 · Obtener información del usuario

GET /api/v1/me
Authorization: Bearer <token>

Respuesta (contrato v1):

{
  "data": {
    "user_id": 15,
    "name": "Demo User",
    "role": "admin",
    "empresa": "Empresa Demo"
  }
}

Legacy hoy (GET /api/me):

{
  "user_id": 15,
  "empresa_id": 4,
  "empresa_slug": "empresa-demo",
  "rol": "admin"
}

Este endpoint confirma que la autenticación y el contexto tenant fueron exitosos.

5 · Paso 3 · Consultar el primer recurso

GET /api/v1/maintenance/assets
Authorization: Bearer <token>

Respuesta (contrato v1):

{
  "data": [
    {
      "asset_id": 25,
      "asset_code": "CMP-001",
      "name": "Compressor B"
    }
  ],
  "meta": {
    "pagination": { "page": 1, "page_size": 50, "total": 1 }
  }
}

Legacy hoy (GET /api/activos):

{
  "total": 3,
  "items": [
    {
      "id": 1,
      "codigo": "M-001",
      "nombre": "Compresor A",
      "status": "operativo"
    }
  ]
}

El desarrollador ya ha realizado su primera consulta completa a la API.

→ MAG-04 · Recursos

6 · Ejemplos por lenguaje

Todos los ejemplos oficiales se ofrecen en cURL, Python, JavaScript y PHP.

Los ejemplos se generan desde OpenAPI (MSD-03) para permanecer sincronizados con MAG.

cURL (recorrido completo)

# 1 · Login
TOKEN=$(curl -s -X POST http://127.0.0.1:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"***","empresa_slug":"empresa-demo"}' \
  | jq -r .token)

# 2 · Me
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:5000/api/me | jq

# 3 · Activos
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:5000/api/activos | jq

Python

import os
import requests

BASE = os.getenv("ROUSTIX_API", "http://127.0.0.1:5000/api/v1")
# Legacy local: usar http://127.0.0.1:5000/api para auth/login y /activos

r = requests.post(
    f"{BASE.replace('/api/v1', '/api')}/auth/login",
    json={
        "username": "admin",
        "password": "***",
        "empresa_slug": "empresa-demo",
    },
    timeout=30,
)
token = r.json()["token"]

me = requests.get(
    f"{BASE.replace('/api/v1', '/api')}/me",
    headers={"Authorization": f"Bearer {token}"},
    timeout=10,
)
print(me.json())

assets = requests.get(
    f"{BASE.replace('/api/v1', '/api')}/activos",
    headers={"Authorization": f"Bearer {token}"},
    timeout=10,
)
print(assets.json())

JavaScript

const BASE = "http://127.0.0.1:5000/api";

const login = await fetch(`${BASE}/auth/login`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    username: "admin",
    password: "***",
    empresa_slug: "empresa-demo",
  }),
});
const { token } = await login.json();

const me = await fetch(`${BASE}/me`, {
  headers: { Authorization: `Bearer ${token}` },
});
console.log(await me.json());

const assets = await fetch(`${BASE}/activos`, {
  headers: { Authorization: `Bearer ${token}` },
});
console.log(await assets.json());

PHP

$base = 'http://127.0.0.1:5000/api';

$ch = curl_init("$base/auth/login");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'username' => 'admin',
        'password' => '***',
        'empresa_slug' => 'empresa-demo',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$token = json_decode(curl_exec($ch), true)['token'];

$headers = ["Authorization: Bearer $token"];
$me = file_get_contents("$base/me", false, stream_context_create([
    'http' => ['header' => implode("\r\n", $headers)],
]));
echo $me;

7 · Uso del SDK

Python (conceptual · MSD-04):

from roustix import RoustixClient

client = RoustixClient(
    base_url="http://127.0.0.1:5000/api/v1",
    token="JWT",
)

assets = client.maintenance.assets.list()
print(assets)

El mismo flujo existe para JavaScript y PHP cuando los paquetes estén publicados.

8 · Uso de la CLI

roustix login
roustix whoami
roustix assets list

La CLI utiliza el mismo contrato que el SDK y la API REST → MSD-05.

9 · Próximos pasos

Una vez completado el Quick Start:

Paso	Recurso
Explorar recursos REST	MAG-04
API Explorer	MSD-06
Descargar OpenAPI	MSD-03 · `/api/v1/openapi.json`
Instalar SDK	MSD-04
Probar Webhooks	MAG-08
Sandbox avanzado	MSD-06
Errores y límites	MAG-06 · MAG-10

El Quick Start es únicamente el punto de partida.

10 · Buenas prácticas

#	Regla
1	Utilizar siempre el Sandbox para las primeras pruebas
2	Conservar el JWT de forma segura
3	Revisar los códigos de error definidos en MAG-06
4	Utilizar los SDK oficiales cuando estén disponibles
5	Consultar OpenAPI antes de implementar nuevos recursos
6	Migrar a Producción únicamente tras validar la integración

Filosofía del capítulo

El Quick Start representa la primera experiencia con Roustix. Debe ser breve, práctico y reproducible. En pocos minutos, cualquier desarrollador debe comprender el flujo de autenticación, ejecutar su primera llamada a la API y estar preparado para construir una integración completa.

MSD-07 establece el recorrido oficial de onboarding para desarrolladores, convirtiendo la documentación en una experiencia guiada y lista para usar.

← 06 · Sandbox 08 · Colecciones →