Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/interezante456-pixel/Miercoles-Proyecto/llms.txt

Use this file to discover all available pages before exploring further.

El módulo de Usuarios es el núcleo del control de acceso de Tiendas Mi Cholo. Desde aquí, el administrador puede crear nuevas cuentas, asignar roles que determinan a qué partes del sistema puede acceder cada persona, y desactivar cuentas sin perder el historial de operaciones. Todos los endpoints de este módulo requieren un JWT válido con el rol ADMIN.
Solo los usuarios con rol ADMIN pueden acceder a cualquier endpoint bajo /api/usuarios. Cualquier otro rol recibirá 403 Forbidden.

​
Roles del Sistema

El sistema de Tiendas Mi Cholo reconoce exactamente tres roles. Cada usuario tiene asignado uno de ellos mediante el campo rolId en el momento de su creación.

ADMIN

Acceso completo a todos los módulos: usuarios, categorías, productos, ventas, compras, reportes PDF y configuración general del sistema.

VENDEDOR

Puede registrar ventas, gestionar clientes y proveedores, y consultar el inventario. No puede acceder a usuarios, categorías ni reportes.

ALMACENERO

Puede gestionar productos y compras (crear y recibir órdenes), consultar inventario, y gestionar clientes y proveedores. No puede registrar ventas ni acceder a reportes.

​
Campos del Usuario

Cada usuario almacenado en la tabla usuarios tiene la siguiente estructura. Al crear o actualizar un usuario, envía un UsuarioRequest con los campos descritos a continuación.
El campo password nunca se devuelve en ninguna respuesta de la API. El objeto Usuario serializado siempre omite ese campo por seguridad.
CampoTipoRequeridoValidaciónDescripción
nombreString✅max=100Nombre(s) del usuario
apellidoString✅max=100Apellido(s) del usuario
usernameString✅max=50, únicoNombre de usuario para el login
emailString✅formato email, únicoCorreo electrónico del usuario
passwordString⬜min=6, max=100Contraseña en texto plano (se almacena con BCrypt)
telefonoString⬜max=20Teléfono de contacto
rolIdLong✅—ID del rol a asignar (1=ADMIN, 2=VENDEDOR, 3=ALMACENERO)
activoBoolean⬜default=trueEstado de la cuenta

​
Endpoints

​
Listar usuarios activos

GET /api/usuarios
Authorization: Bearer <token>
Devuelve la lista de todos los usuarios con activo = true. Respuesta 200 OK 
[
  {
    "id": 1,
    "nombre": "Juan",
    "apellido": "Pérez",
    "username": "admin",
    "email": "admin@tienda.com",
    "telefono": "987654321",
    "activo": true,
    "rol": {
      "id": 1,
      "nombre": "ADMIN",
      "descripcion": "Administrador del sistema"
    },
    "createdAt": "2024-01-01T08:00:00",
    "updatedAt": "2024-01-15T10:00:00"
  }
]

​
Obtener usuario por ID

GET /api/usuarios/{id}
Authorization: Bearer <token>
​
id
Long
required
ID interno del usuario.
Respuesta 404 Not Found si el ID no existe: 
{
  "timestamp": "2024-01-15T10:30:00",
  "status": 404,
  "error": "Usuario no encontrado: 99"
}

​
Crear usuario

POST /api/usuarios
Authorization: Bearer <token>
Content-Type: application/json

{
  "nombre": "María",
  "apellido": "García",
  "username": "mgarcia",
  "email": "maria@tienda.com",
  "password": "segura123",
  "telefono": "912345678",
  "rolId": 2,
  "activo": true
}
La contraseña se encripta automáticamente con BCrypt antes de persistirse. Nunca se almacena en texto plano. Respuesta 200 OK: objeto Usuario creado (sin password).

​
Actualizar usuario

PUT /api/usuarios/{id}
Authorization: Bearer <token>
Content-Type: application/json
​
id
Long
required
ID del usuario a actualizar.
El cuerpo tiene la misma estructura que el POST. Ten en cuenta las siguientes reglas especiales:
  • Si password se omite o se envía como cadena vacía (""), la contraseña existente no se modifica.
  • Si activo se incluye, permite activar o desactivar la cuenta directamente desde el PUT.
  • El campo username no se puede cambiar. El valor enviado pasa validación @NotBlank (es obligatorio incluirlo en el body), pero el servidor lo descarta y no actualiza el username almacenado.

​
Eliminar usuario (baja lógica)

DELETE /api/usuarios/{id}
Authorization: Bearer <token>
​
id
Long
required
ID del usuario a desactivar.
El DELETE no borra el registro de la base de datos. Únicamente establece activo = false en la fila correspondiente. El usuario deja de poder iniciar sesión (Spring Security usa isEnabled() que retorna el valor de activo), pero todo su historial de ventas, compras y movimientos de inventario queda intacto. Respuesta 204 No Content — sin cuerpo.

​
Flujo de Creación de un Usuario

1

Consultar roles disponibles

Llama a GET /api/roles para obtener los IDs de los roles y elegir el rolId correcto.
2

Enviar el POST

Construye el UsuarioRequest con los datos del nuevo operador e incluye una contraseña de al menos 6 caracteres.
3

Guardar el ID devuelto

El objeto Usuario en la respuesta incluye el id generado, que necesitarás para futuras actualizaciones.
4

Verificar el login

Comprueba que el nuevo usuario puede autenticarse correctamente en POST /api/auth/login con sus credenciales.

​
Respuestas de Error Comunes

CódigoCausa
400 Bad RequestValidación fallida (campos requeridos vacíos, email inválido, password menor a 6 caracteres)
401 UnauthorizedToken JWT ausente, inválido o expirado
403 ForbiddenEl token pertenece a un rol distinto de ADMIN
404 Not FoundEl id o el rolId proporcionado no existe en la base de datos

Build docs developers (and LLMs) love

Get started for freeTalk to us