Users API — CRUD Endpoints for System Users

The Users API gives Administrators full control over the system’s user accounts. Every endpoint under /api/users is protected by two middleware layers: verifyToken (validates the JWT) and authorizeRoles(1) (restricts access to id_rol: 1 — Administrator). Administrators can create users of any role, including other administrators, operators, and customers. Passwords are always hashed with bcrypt before being stored.

GET /api/users

Returns the complete list of user accounts in the system. Results are fetched via a JOIN between the USUARIOS and ROLES tables, so each object includes the resolved role name rather than the numeric role identifier. Auth required: Yes — Administrator (id_rol: 1)

Response `200 OK`

An array of user objects.

id_usuario

integer

Auto-incremented primary key.

nombre

string

First name.

apellido

string

Last name.

string

Unique email address.

telefono

string | null

Phone number, or null if not provided.

activo

boolean

Whether the account is active.

rol

string

Human-readable role name resolved from the ROLES table (e.g. "Administrador", "Operador", "Cliente").

curl -X GET https://api.ordervista.com/api/users \
  -H "Authorization: Bearer <token>"

[
  {
    "id_usuario": 1,
    "nombre": "Carlos",
    "apellido": "López",
    "email": "carlos.lopez@ordervista.com",
    "telefono": "+56911111111",
    "activo": true,
    "rol": "Administrador"
  }
]

Error responses

Status	`mensaje`	Cause
`401`	`"Token no proporcionado"` / `"Token inválido"`	Missing or invalid JWT.
`403`	`"Acceso denegado"`	Authenticated user does not have the Administrator role.
`500`	`"Error al obtener usuarios"`	Unexpected server-side error.

GET /api/users/:id

Retrieves a single user account by its primary key. Returns the full row from the USUARIOS table via SELECT *. Auth required: Yes — Administrator (id_rol: 1)

Path parameters

integer

required

The id_usuario of the user to retrieve.

Response `200 OK`

A single user object with the raw columns from the USUARIOS table.

id_usuario

integer

Auto-incremented primary key.

nombre

string

First name.

apellido

string

Last name.

string

Unique email address.

telefono

string | null

Phone number, or null if not provided.

id_rol

integer

Numeric role identifier. 1 = Administrator, 2 = Operator, 3 = Customer.

fecha_registro

string (datetime)

ISO 8601 timestamp of when the account was created.

activo

boolean

Whether the account is active.

curl -X GET https://api.ordervista.com/api/users/42 \
  -H "Authorization: Bearer <token>"

{
  "id_usuario": 42,
  "nombre": "Ana",
  "apellido": "García",
  "email": "ana.garcia@example.com",
  "telefono": "+56912345678",
  "id_rol": 3,
  "fecha_registro": "2024-03-20T08:15:00.000Z",
  "activo": true
}

Error responses

Status	`mensaje`	Cause
`401`	`"Token no proporcionado"` / `"Token inválido"`	Missing or invalid JWT.
`403`	`"Acceso denegado"`	Insufficient role.
`404`	`"Usuario no encontrado"`	No user exists with the given `id`.
`500`	`"Error al obtener usuario"`	Unexpected server-side error.

POST /api/users

Creates a new user account with an explicitly assigned role. Unlike self-registration via /api/auth/register, this endpoint allows the Administrator to assign any id_rol. Auth required: Yes — Administrator (id_rol: 1)

Request body

nombre

string

required

First name of the new user.

apellido

string

required

Last name of the new user.

string

required

Email address. Must be unique.

password

string

required

Plain-text password. Hashed with bcrypt before storage.

id_rol

integer

required

Role to assign. 1 = Administrator, 2 = Operator, 3 = Customer.

telefono

string

Optional phone number (up to 20 characters).

Response `201 Created`

mensaje

string

Confirmation message: "Usuario creado correctamente".

id_usuario

integer

The auto-generated primary key of the new user.

curl -X POST https://api.ordervista.com/api/users \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "María",
    "apellido": "Soto",
    "email": "maria.soto@ordervista.com",
    "password": "Operador456",
    "telefono": "+56922222222",
    "id_rol": 2
  }'

{
  "mensaje": "Usuario creado correctamente",
  "id_usuario": 55
}

Error responses

Status	`mensaje`	Cause
`400`	`"El correo ya existe"`	The email is already registered.
`401`	`"Token no proporcionado"` / `"Token inválido"`	Missing or invalid JWT.
`403`	`"Acceso denegado"`	Insufficient role.
`500`	`"Error al crear usuario"`	Unexpected server-side error.

PUT /api/users/:id

Updates one or more fields on an existing user account. All fields in the request body are written to the record; omitting a field sets it to undefined in the SQL update, so supply all fields you want to preserve. Auth required: Yes — Administrator (id_rol: 1)

Path parameters

integer

required

The id_usuario of the user to update.

Request body

nombre

string

New first name.

apellido

string

New last name.

string

New email address. Must remain unique.

password

string

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

telefono

string

New phone number.

id_rol

integer

New role assignment.

activo

boolean

Set to false to deactivate the account without deleting it.

Response `200 OK`

mensaje

string

Confirmation message: "Usuario actualizado correctamente".

curl -X PUT https://api.ordervista.com/api/users/42 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Ana",
    "apellido": "García",
    "email": "ana.garcia@example.com",
    "telefono": "+56933333333",
    "id_rol": 3,
    "activo": false
  }'

{
  "mensaje": "Usuario actualizado correctamente"
}

Error responses

Status	`mensaje`	Cause
`401`	`"Token no proporcionado"` / `"Token inválido"`	Missing or invalid JWT.
`403`	`"Acceso denegado"`	Insufficient role.
`500`	`"Error al actualizar usuario"`	Unexpected server-side error.

DELETE /api/users/:id

Permanently removes a user account from the system. Auth required: Yes — Administrator (id_rol: 1)

Path parameters

integer

required

The id_usuario of the user to delete.

Response `200 OK`

mensaje

string

Confirmation message: "Usuario eliminado correctamente".

curl -X DELETE https://api.ordervista.com/api/users/42 \
  -H "Authorization: Bearer <token>"

{
  "mensaje": "Usuario eliminado correctamente"
}

Error responses

Status	`mensaje`	Cause
`401`	`"Token no proporcionado"` / `"Token inválido"`	Missing or invalid JWT.
`403`	`"Acceso denegado"`	Insufficient role.
`500`	`"Error al eliminar usuario"`	Unexpected server-side error.

Overview

Endpoints

Users API — CRUD Endpoints for System Users

GET /api/users

Response `200 OK`

Error responses

GET /api/users/:id

Path parameters

Response `200 OK`

Error responses

POST /api/users

Request body

Response `201 Created`

Error responses

PUT /api/users/:id

Path parameters

Request body

Response `200 OK`

Error responses

DELETE /api/users/:id

Path parameters

Response `200 OK`

Error responses

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /api/users

​Response 200 OK

​Error responses

​GET /api/users/:id

​Path parameters

​Response 200 OK

​Error responses

​POST /api/users

​Request body

​Response 201 Created

​Error responses

​PUT /api/users/:id

​Path parameters

​Request body

​Response 200 OK

​Error responses

​DELETE /api/users/:id

​Path parameters

​Response 200 OK

​Error responses

Build docs developers (and LLMs) love

GET /api/users

Response `200 OK`

Error responses

GET /api/users/:id

Path parameters

Response `200 OK`

Error responses

POST /api/users

Request body

Response `201 Created`

Error responses

PUT /api/users/:id

Path parameters

Request body

Response `200 OK`

Error responses

DELETE /api/users/:id

Path parameters

Response `200 OK`

Error responses