Usuarios

Tag: users
Descripción: Operaciones CRUD para usuarios del sistema

---

1. Crear usuario (POST /users)

• Descripción: Crea un nuevo usuario en el sistema (los nuevos usuarios se crean inactivos por defecto y con rol de usuario normal).
• Operation ID: UsersController_create
• Autenticación requerida: ❌ No
• Validaciones:
  • Email debe ser único (se verifica contra la base de datos)
  • El rol siempre se establece como “usuario normal” (rol_id: 3)
  • El estado siempre se establece como inactivo (is_active: false) inicialmente
  • La contraseña se hashea antes de almacenarse

Request Body

{
    "username": "juan_perez",
    "email": "juan@example.com",
    "password": "ContraseñaSegura123!",
    "first_name": "Juan",
    "last_name": "Pérez",
    "phone": "+5491155555555",
    "address": "Calle Falsa 123",
    "city": "Buenos Aires",
    "country": "Argentina",
    "postal_code": "C1425ABC"
}

Campos Requeridos

Campo	Tipo	Descripción	Validaciones	Ejemplo
username	string	Nombre de usuario único	Requerido, único	”juan_perez”
email	string	Correo electrónico	Requerido, formato email, único	”juan@example.com”
password	string	Contraseña	Requerido, min 8 caracteres	”ContraseñaSegura123!“
first_name	string	Nombre del usuario	Opcional	”Juan”
last_name	string	Apellido del usuario	Opcional	”Pérez”
phone	string	Teléfono	Opcional	”+5491155555555”
address	string	Dirección	Opcional	”Calle Falsa 123”
city	string	Ciudad	Opcional	”Buenos Aires”
country	string	País	Opcional	”Argentina”
postal_code	string	Código postal	Opcional	”C1425ABC”

Notas:

• Los campos role_id e is_active no pueden ser establecidos al crear un usuario (se asignan automáticamente)
• El sistema devolverá el usuario creado sin el campo de contraseña

Responses

Código	Descripción	Ejemplo de respuesta (sin password_hash)
201	Usuario creado exitosamente	json {"id": 1, "username": "juan_perez", "email": "juan@example.com", "is_active": false, "role_id": 3, ...}
400	Datos de entrada inválidos	json {"message": "Validation failed", "errors": [...]}
409	El email ya está registrado	json {"message": "El correo electrónico ya está registrado"}

Proceso Interno

1. Verifica que el email no esté registrado
2. Hashea la contraseña con bcrypt
3. Crea el usuario con:
   • is_active: false
   • role_id: 3 (usuario normal)
   • password_hash (versión hasheada de la contraseña)
4. Guarda el usuario en la base de datos
5. Devuelve el usuario creado (excluyendo el password_hash)

Responses

Código	Descripción
201	Usuario creado exitosamente
400	Datos de entrada inválidos
409	El email ya está registrado

---

2. Obtener todos los usuarios (GET /users)

• Descripción: Obtiene lista paginada de usuarios (solo administradores).
• Operation ID: UsersController_findAll
• Autenticación requerida: 🔒 Sí (Rol: admin)
• Parámetros Query:
  • page (default: 1) - Página actual
  • limit (default: 10) - Items por página

Responses

Código	Descripción
200	Lista de usuarios obtenida
403	Acceso no autorizado

---

3. Obtener usuario por ID (GET /users/:id)

• Descripción: Obtiene detalles de un usuario específico.
• Operation ID: UsersController_findOne
• Autenticación requerida: 🔒 Sí

Parámetros de Ruta

Nombre	Tipo	Descripción
id	number	ID del usuario

Responses

Código	Descripción
200	Usuario encontrado
404	Usuario no encontrado

---

4. Actualizar usuario (PATCH /users/:id)

• Descripción: Actualiza información de un usuario existente.
• Operation ID: UsersController_update
• Autenticación requerida: 🔒 Sí

Parámetros de Ruta

Nombre	Tipo	Descripción
id	number	ID del usuario

Request Body (Ejemplo)

{
    "email": "nuevo_email@ejemplo.com",
    "phone": "+9876543210"
}

Responses

Código	Descripción
200	Usuario actualizado
404	Usuario no encontrado

---

5. Eliminar usuario (DELETE /users/:id)

• Descripción: Elimina un usuario del sistema (solo administradores).
• Operation ID: UsersController_remove
• Autenticación requerida: 🔒 Sí (Rol: admin)

Parámetros de Ruta

Nombre	Tipo	Descripción
id	number	ID del usuario

Responses

Código	Descripción
200	Usuario eliminado
403	Acceso no autorizado
404	Usuario no encontrado

---

Resumen de Endpoints de Usuarios

Método	Endpoint	Descripción	Autenticación Requerida	Rol Requerido
POST	/users	Crear nuevo usuario	❌ No	-
GET	/users	Listar usuarios (paginado)	🔒 Sí	admin
GET	/users/:id	Obtener usuario por ID	🔒 Sí	admin
PATCH	/users/:id	Actualizar usuario	🔒 Sí	admin
DELETE	/users/:id	Eliminar usuario	🔒 Sí	admin

Notas adicionales:

1. Seguridad: Las contraseñas nunca se devuelven en las respuestas
2. Roles:
   • Solo usuarios con rol admin pueden listar y eliminar usuarios
   • Los nuevos usuarios siempre se crean con rol user (ID: 3)
3. Estado:
   • Los nuevos usuarios se crean como is_active: false
   • Requieren activación manual o hacer PATCH al usuario