Colección Postman – E-Training API

Colección con todos los controladores del proyecto E-Training: overview en la colección, subcarpetas por módulo (Auth, Users, Organizations, Roles, Health, Config), requests documentados y variables de colección definidas.

Cómo crear la colección (importar)

La colección se crea importando el JSON del repo (incluye overview, subcarpetas y variables). No hace falta crearla a mano en Postman.

1. En Postman: Import → Upload Files (o arrastrar el archivo).
2. Selecciona: docs/postman/postman-collection-import.json.
3. Confirma Import. Se creará la colección E-Training API con:
4. Overview: descripción de la colección (pestaña Description al editar la colección).
5. Subcarpetas: Auth, Users, Organizations, Roles, Health, Config, cada una con sus requests.
6. Variables de colección: base_url, access_token, user_id, organization_id, role_id, internal_api_key.
7. Auth: Bearer {{access_token}} a nivel de colección.

8. Requests: todos con descripción y bodies de ejemplo donde aplica.

9. Si ya tenías una colección "E-Training API" y Postman te pregunta, elige Replace para sustituirla por esta versión.

Workspace recomendado: Capital Tech (o el que uses). Tras importar, la colección aparecerá en tu workspace.

Variables de colección (incluidas en el import)

Variable	Valor por defecto	Uso
base_url	http://localhost:3001	URL base del API (sin barra final).
access_token	(vacío)	JWT. Se rellena tras Login o Register (copiar de la respuesta).
user_id	(vacío)	UUID de usuario para Get user by id.
organization_id	(vacío)	UUID de organización para Get organization by id.
role_id	(vacío)	UUID de rol para Get role by id.
internal_api_key	(vacío)	Clave interna para Config → Set log levels (header x-internal-api-key).

La colección usa Bearer Token a nivel de colección con {{access_token}}. Las rutas públicas (register, login, health) no requieren token.

Estructura de la colección

Auth (públicas)

• Register – POST /auth/register – Registra organización con su administrador. Devuelve accessToken y refreshToken.
• Login – POST /auth/login – Autentica usuario. Devuelve accessToken y refreshToken. Copiar a access_token.
• Refresh – POST /auth/refresh – Renueva el access token usando el refresh token. Devuelve nuevo accessToken y refreshToken.

Users (requieren JWT)

• List users – GET /users (paginación: page[number], page[size]).
• Get user by id – GET /users/{{user_id}}.
• Create user – POST /users – Crea un usuario en la organización del token. Body: email, password, first_name, last_name, role_id. organization_id lo asigna el servidor desde el JWT.
• Update user – PUT /users/{{user_id}} – Actualiza usuario (parcial). Body: solo los campos a cambiar (first_name, last_name, role_id, active, level, password).
• Delete user – DELETE /users/{{user_id}} – Baja lógica (soft delete).

Organizations (requieren JWT + SUPER_ADMIN)

• List organizations – GET /organizations (paginación: page[number], page[size]).
• Get organization by id – GET /organizations/{{organization_id}}.

Roles (requieren JWT + ROLE:READ/ROLE:WRITE)

• List roles – GET /roles (paginación: page[number], page[size]). Requiere ROLE:READ.
• Get role by id – GET /roles/{{role_id}}. Requiere ROLE:READ.
• Create role – POST /roles. Requiere ROLE:WRITE.
• Update role – PUT /roles/{{role_id}}. Requiere ROLE:WRITE.
• Delete role – DELETE /roles/{{role_id}}. Requiere ROLE:WRITE.

Permissions (requieren JWT + ROLE:READ)

• List permissions – GET /permissions (paginación: page[number], page[size]). Lista permisos disponibles en el sistema.

Health (público)

• Health check – GET /health.

Config (interno)

• Set log levels – POST /config/logger – Requiere header x-internal-api-key (o Authorization: Bearer <INTERNAL_API_KEY>).

---

Bodies de ejemplo (JSON)

Auth

Register – POST /auth/register
Content-Type: application/json

{
  "organization": {
    "name": "Acme Corp",
    "slug": "acme-corp"
  },
  "user": {
    "email": "user@example.com",
    "password": "SecureP@ss123",
    "first_name": "John",
    "last_name": "Doe"
  },
  "info": {
    "deviceInfo": "Postman",
    "ipAddress": "127.0.0.1"
  }
}

Login – POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "deviceInfo": "Postman",
  "ipAddress": "127.0.0.1"
}

Refresh – POST /auth/refresh
Content-Type: application/json

{
  "refresh_token": "550e8400-e29b-41d4-a716-446655440000",
  "info": {
    "device_info": "Postman",
    "ip_address": "127.0.0.1"
  }
}

Nota: El campo info es opcional. device_info e ip_address dentro de info también son opcionales.

Users

List users – query params (opcionales):
page[number]=1, page[size]=10.

Create user – POST /users
Content-Type: application/json
Headers: Authorization: Bearer {{access_token}}

{
  "email": "newuser@example.com",
  "password": "SecureP@ss123",
  "first_name": "Jane",
  "last_name": "Doe",
  "role_id": "123e4567-e89b-12d3-a456-426614174000"
}

La organización se asigna desde el JWT; no enviar organization_id.

Update user – PUT /users/{{user_id}}
Content-Type: application/json
Solo enviar los campos que se desean cambiar. Ejemplo (solo perfil):

{
  "first_name": "Jane",
  "last_name": "Smith"
}

Ejemplo con rol, activo y nivel:

{
  "role_id": "123e4567-e89b-12d3-a456-426614174000",
  "active": true,
  "level": "NIVEL_2"
}

Ejemplo cambio de contraseña (mínimo 8 caracteres):

{
  "password": "NewSecureP@ss123"
}

Delete user – DELETE /users/{{user_id}}
Sin body. Respuesta 200 indica baja lógica correcta.

Organizations

List organizations – query params (opcionales):
page[number]=1, page[size]=10.

Roles

List roles – query params (opcionales):
page[number]=1, page[size]=10.

Config

Set log levels – POST /config/logger
Headers: Content-Type: application/json, x-internal-api-key: <INTERNAL_API_KEY>

{
  "level": "debug",
  "discordLevels": ["warn", "error"]
}

Niveles válidos: según LOG_LEVELS del proyecto (p. ej. debug, info, warn, error).

---

Buenas prácticas aplicadas

• Variables base_url, access_token para no repetir datos.
• Auth a nivel de colección (Bearer {{access_token}}); rutas públicas sin auth.
• Nombres claros por recurso y método (Register, Login, List users, Get role by id, etc.).
• Bodies de ejemplo en las requests que lo requieren; documentación en este archivo.
• Headers Content-Type: application/json en POST; x-internal-api-key solo en Config.
• Paginación documentada (Users, Organizations, Roles) con page[number] y page[size].
• Respuestas del API en JSON:API (application/vnd.api+json); Postman las muestra en Body.

Para guardar automáticamente los tokens tras Login, en la pestaña Tests de la request Login puedes añadir:

const res = pm.response.json();
if (res.data && res.data.attributes) {
  const attrs = res.data.attributes;
  if (attrs.accessToken)
    pm.collectionVariables.set('access_token', attrs.accessToken);
}

(Ajusta la ruta si tu API devuelve los tokens en otra estructura; el backend usa JSON:API con data.attributes.)

---

Descripción de la colección (para pegar en Postman)

En Postman: E-Training API → Edit → pestaña Description → pegar el siguiente Markdown:

# E-Training API

Colección oficial del backend **E-Training** (NestJS, DDD Hexagonal).

## Uso

- **base_url**: por defecto `http://localhost:3001`. Cambiar si usas otro host/puerto.
- **access_token**: JWT. Rellenar tras **Auth → Login** o **Register** (o pegar manualmente). La colección usa Bearer en todas las rutas protegidas.
- **user_id** / **organization_id** / **role_id**: opcionales; para Get by id.
- **internal_api_key**: solo para requests de Config (Set log levels).

Rutas **públicas** (Register, Login, Refresh, Health) no requieren token.

## Respuestas

Las respuestas siguen **JSON:API** (`application/vnd.api+json`). Los recursos van en `data` y atributos en `data.attributes`.

## Módulos

- **Auth**: register, login, refresh token.
- **Users**: listado, consulta, crear, actualizar y eliminar (soft) usuarios (JWT requerido).
- **Organizations**: listado y consulta de organizaciones (solo **SUPER_ADMIN**).
- **Roles**: listado y consulta de roles (solo **SUPER_ADMIN**).
- **Health**: chequeo de estado (Docker, balanceadores).
- **Config**: configuración interna (header `x-internal-api-key`).