CafeteriaPM Users API — Create and Manage Staff Accounts

The /usuarios/ endpoints manage CafeteriaPM staff accounts. Every staff member — whether a waiter, kitchen worker, cashier, or administrator — is represented as a user with an assigned role that controls which endpoints they can access. All operations except GET /usuarios/me require the admin role. Passwords are bcrypt-hashed server-side before storage and are never returned in any response payload.

GET /usuarios/roles — List Available Roles

Required role: admin Returns the complete list of roles configured in the system. Use this endpoint to discover valid id_rol values before creating or updating users.

Response

integer

required

Unique role identifier. Pass this value as id_rol when creating or updating a user.

nombre

string

required

Internal role name (e.g. admin, mesero, cocina, caja).

descripcion

string

Human-readable description of the role’s permissions and responsibilities. May be null.

Example

curl -X GET "https://api.cafeteriapm.com/usuarios/roles" \
  -H "Authorization: Bearer <token>"

[
  { "id": 1, "nombre": "admin",  "descripcion": "Acceso total al sistema" },
  { "id": 2, "nombre": "mesero", "descripcion": "Toma y gestión de pedidos" },
  { "id": 3, "nombre": "cocina", "descripcion": "Gestión de productos e ingredientes" },
  { "id": 4, "nombre": "caja",   "descripcion": "Generación de tickets y cobro" }
]

Error codes

Status	Detail
`401`	Token missing or expired
`403`	Authenticated user is not `admin`

GET /usuarios/ — List Users

Required role: admin Returns a paginated-friendly list of all user accounts. Supports case-insensitive full-text search across the nombre and email fields, and optional filters by role and active status. All three query parameters are independent and can be combined freely.

Query Parameters

string

Case-insensitive substring match applied to both nombre and email. Returns users where either field contains the search string.

rol_id

integer

Filter results to users assigned to this role ID. Must correspond to a valid role from GET /usuarios/roles.

activo

boolean

Filter by active status. Pass true to show only active users, false for deactivated accounts. Omit to return all users regardless of status.

Response

Returns an array of UserOut objects. See UserOut schema below.

Example

# Search for active meseros named "carlos"
curl -X GET "https://api.cafeteriapm.com/usuarios/?search=carlos&rol_id=2&activo=true" \
  -H "Authorization: Bearer <token>"

[
  {
    "id": 7,
    "nombre": "Carlos Méndez",
    "email": "[email protected]",
    "activo": true,
    "role": { "id": 2, "nombre": "mesero", "descripcion": "Toma y gestión de pedidos" },
    "created_at": "2024-03-01T09:15:00"
  }
]

Error codes

Status	Detail
`401`	Token missing or expired
`403`	Authenticated user is not `admin`

GET /usuarios/me — Get Own Profile

Required role: Any authenticated user Returns the full profile of the currently authenticated user, identified from the JWT token. This is the only users endpoint accessible to non-admin roles and is the standard way for any logged-in user to retrieve their own account details.

Response

Returns a single UserOut object for the caller. See UserOut schema below.

Example

curl -X GET "https://api.cafeteriapm.com/usuarios/me" \
  -H "Authorization: Bearer <token>"

{
  "id": 12,
  "nombre": "Ana López",
  "email": "[email protected]",
  "activo": true,
  "role": { "id": 2, "nombre": "mesero", "descripcion": "Toma y gestión de pedidos" },
  "created_at": "2024-01-20T08:00:00"
}

Error codes

Status	Detail
`401`	Token missing or expired

GET /usuarios/ — Get Single User

Required role: admin Retrieves the full profile of any user by their numeric ID.

Path Parameters

user_id

integer

required

The unique ID of the user to retrieve.

Response

Returns a single UserOut object. See UserOut schema below.

Example

curl -X GET "https://api.cafeteriapm.com/usuarios/7" \
  -H "Authorization: Bearer <token>"

Error codes

Status	Detail
`404`	`"Usuario no encontrado"` — no user with the given ID exists
`401`	Token missing or expired
`403`	Authenticated user is not `admin`

POST /usuarios/ — Create User

Required role: admin Creates a new staff account. The supplied plain-text password is bcrypt-hashed before being written to the database — it is never stored or returned in plain text. Returns 201 Created on success.

Request Body

nombre

string

required

Full display name of the staff member (e.g. "María García").

string

required

Valid email address. Must be unique across all user accounts. Used as the login identifier.

password

string

required

Plain-text password. The API hashes this value with bcrypt before storage. Minimum recommended length: 8 characters.

id_rol

integer

required

Role to assign to the new user. Must be a valid role ID from GET /usuarios/roles.

activo

boolean

default:"true"

Whether the account is active and permitted to log in. Defaults to true.

Response

Returns the newly created UserOut object with HTTP 201 Created. See UserOut schema below.

Example

curl -X POST "https://api.cafeteriapm.com/usuarios/" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Luis Herrera",
    "email": "[email protected]",
    "password": "S3curePass!",
    "id_rol": 2,
    "activo": true
  }'

{
  "id": 15,
  "nombre": "Luis Herrera",
  "email": "[email protected]",
  "activo": true,
  "role": { "id": 2, "nombre": "mesero", "descripcion": "Toma y gestión de pedidos" },
  "created_at": "2024-06-10T14:32:00"
}

Error codes

Status	Detail
`400`	`"El email ya está registrado"` — another account already uses this email
`400`	`"Rol no encontrado"` — the supplied `id_rol` does not exist
`401`	Token missing or expired
`403`	Authenticated user is not `admin`

PATCH /usuarios/ — Update User (Partial)

Required role: admin Partially updates a user account. Only the fields included in the request body are modified; omitted fields retain their current values. The password field, if supplied, is re-hashed before storage.

Path Parameters

user_id

integer

required

The unique ID of the user to update.

Request Body

All fields are optional. Include only the fields you want to change.

nombre

string

New display name for the user.

string

New email address. Must not be in use by any other user account.

password

string

New plain-text password. Will be bcrypt-hashed before storage.

id_rol

integer

New role assignment. Must be a valid role ID from GET /usuarios/roles.

activo

boolean

Set to false to deactivate the account without deleting it, preventing login.

Response

Returns the updated UserOut object. See UserOut schema below.

Example

# Deactivate a user and change their role
curl -X PATCH "https://api.cafeteriapm.com/usuarios/7" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "activo": false,
    "id_rol": 4
  }'

{
  "id": 7,
  "nombre": "Carlos Méndez",
  "email": "[email protected]",
  "activo": false,
  "role": { "id": 4, "nombre": "caja", "descripcion": "Generación de tickets y cobro" },
  "created_at": "2024-03-01T09:15:00"
}

Error codes

Status	Detail
`400`	`"El email ya está en uso"` — the new email belongs to a different account
`400`	`"Rol no encontrado"` — the supplied `id_rol` does not exist
`404`	`"Usuario no encontrado"` — no user with the given ID exists
`401`	Token missing or expired
`403`	Authenticated user is not `admin`

DELETE /usuarios/ — Delete User

Required role: admin Permanently deletes a user account. Returns HTTP 204 No Content on success. This operation is irreversible. Two safety guards are enforced:

An admin cannot delete their own account — this prevents accidental self-lockout.
A user cannot be deleted if they have associated orders, sales, or expenses — the database enforces referential integrity via an IntegrityError.

Path Parameters

user_id

integer

required

The unique ID of the user to delete.

Example

curl -X DELETE "https://api.cafeteriapm.com/usuarios/7" \
  -H "Authorization: Bearer <token>"

A successful response returns HTTP 204 No Content with an empty body.

Error codes

Status	Detail
`400`	`"No puedes eliminarte a ti mismo"` — you cannot delete your own account
`400`	`"No se puede eliminar el usuario porque tiene pedidos, ventas o gastos asociados."` — database integrity constraint prevents deletion
`404`	`"Usuario no encontrado"` — no user with the given ID exists
`401`	Token missing or expired
`403`	Authenticated user is not `admin`

UserOut Response Shape

All endpoints that return user objects use the UserOut schema. The password_hash field is never included in any response.

integer

required

Auto-incremented unique identifier for the user.

nombre

string

required

Full display name of the staff member.

string

required

The user’s email address and login identifier.

activo

boolean

required

true if the account is active and permitted to authenticate; false if deactivated.

role

object

required

Nested role object containing the full role definition for this user.

Show role fields

integer

required

The numeric ID of the assigned role.

nombre

string

required

The role name string (e.g. "admin", "mesero", "cocina", "caja").

descripcion

string

Human-readable description of the role. May be null.

created_at

datetime

required

ISO 8601 timestamp of when the account was created (e.g. "2024-01-20T08:00:00").

Authentication

Resources

Analytics

CafeteriaPM Users API — Create and Manage Staff Accounts

GET /usuarios/roles — List Available Roles

Response

Example

Error codes

GET /usuarios/ — List Users

Query Parameters

Response

Example

Error codes

GET /usuarios/me — Get Own Profile

Response

Example

Error codes

GET /usuarios/ — Get Single User

Path Parameters

Response

Example

Error codes

POST /usuarios/ — Create User

Request Body

Response

Example

Error codes

PATCH /usuarios/ — Update User (Partial)

Path Parameters

Request Body

Response

Example

Error codes

DELETE /usuarios/ — Delete User

Path Parameters

Example

Error codes

UserOut Response Shape

Build docs developers (and LLMs) love

Authentication

Resources

Analytics

Documentation Index

​GET /usuarios/roles — List Available Roles

​Response

​Example

​Error codes

​GET /usuarios/ — List Users

​Query Parameters

​Response

​Example

​Error codes

​GET /usuarios/me — Get Own Profile

​Response

​Example

​Error codes

​GET /usuarios/ — Get Single User

​Path Parameters

​Response

​Example

​Error codes

​POST /usuarios/ — Create User

​Request Body

​Response

​Example

​Error codes

​PATCH /usuarios/ — Update User (Partial)

​Path Parameters

​Request Body

​Response

​Example

​Error codes

​DELETE /usuarios/ — Delete User

​Path Parameters

​Example

​Error codes

​UserOut Response Shape

Build docs developers (and LLMs) love

GET /usuarios/roles — List Available Roles

Response

Example

Error codes

GET /usuarios/ — List Users

Query Parameters

Response

Example

Error codes

GET /usuarios/me — Get Own Profile

Response

Example

Error codes

GET /usuarios/ — Get Single User

Path Parameters

Response

Example

Error codes

POST /usuarios/ — Create User

Request Body

Response

Example

Error codes

PATCH /usuarios/ — Update User (Partial)

Path Parameters

Request Body

Response

Example

Error codes

DELETE /usuarios/ — Delete User

Path Parameters

Example

Error codes

UserOut Response Shape