Users API: Registration, Auth, and Profile Endpoints

The Users API handles the full lifecycle of system accounts in the Sistema de Inventario Tecnológico. It covers registration, authentication, profile retrieval, profile updates, and soft-deletion. Most mutating endpoints require a valid JWT, which is issued by POST /api/login and stored in an acceso_token HTTP-only cookie. The GET /api/usuarios endpoint is additionally restricted to users holding the Superadministrador role.

POST /api/usuarios

Create a new user account. Location fields are normalized and stored both inside the user document (denormalized) and in the shared ubicaciones collection. Auth: Not required.

Request

username

string

required

Unique display name for the user. Stored in lowercase-normalized form for duplicate checks.

password

string

required

Plain-text password. Hashed with bcrypt (10 salt rounds) before storage.

rol

string

Role assigned to the user. Defaults to "usuario" if omitted. Use "Superadministrador" for full access.

cedula

string

required

National ID number. Must be unique across all users.

nombre

string

First name of the user.

apellido

string

Last name of the user.

correo

string

required

Email address. Used as the login credential identifier.

telefono

string

Contact phone number.

estado_persona

string

Account status. Defaults to "activo" if omitted.

region

string

required

Geographic region for the user’s office location.

estado

string

required

State/province within the region.

ciudad

string

required

City within the state.

sede

string

required

Office building or branch name.

piso

string

required

Floor number within the building.

alas

string

Wing or section on the floor. Optional.

Response

message

string

Human-readable confirmation: "Usuario creado exitosamente."

id_usuario

string

Firestore document ID of the newly created user.

Example

curl -X POST http://localhost:3001/api/usuarios \
  -H "Content-Type: application/json" \
  -d '{
    "username": "jperez",
    "password": "S3cur3P@ss",
    "rol": "usuario",
    "cedula": "12345678",
    "nombre": "Juan",
    "apellido": "Pérez",
    "correo": "jperez@empresa.com",
    "telefono": "0414-1234567",
    "estado_persona": "activo",
    "region": "Centro Occidental",
    "estado": "Lara",
    "ciudad": "Barquisimeto",
    "sede": "Torre Norte",
    "piso": "3",
    "alas": "A"
  }'

GET /api/usuarios

List all active users in the system. Each user object includes flattened location fields sourced from the embedded ubicacion sub-document. Auth: Required. Role: Superadministrador.

Request

No request body or query parameters.

Response

Returns a JSON array. Each element contains:

id_usuario

string

Firestore document ID.

cedula

string

National ID number.

nombre

string

First name.

apellido

string

Last name.

correo

string

Email address.

telefono

string

Contact phone number.

estado_persona

string

Account status ("activo" for all results since the query filters by active state).

username

string

Display name.

rol

string

User role.

region

string

Geographic region.

estado

string

State/province.

ciudad

string

City.

sede

string

Office building or branch name.

piso

string

Floor number.

alas

string

Wing or section.

Example

curl http://localhost:3001/api/usuarios \
  -H "Cookie: acceso_token=<JWT>"

PUT /api/usuarios/:id

Update an existing user’s profile. The password field is optional — if omitted or blank, the current hash is preserved. The account status is always reset to "activo" on update; estado_persona is not an accepted body field here. Any detected field changes are automatically written to the bitácora as an "Actualización de usuario" event. Auth: Required.

Request

string

required

Firestore document ID of the user to update.

username

string

New display name.

password

string

New plain-text password. Leave blank or omit to keep the existing password.

rol

string

Updated role assignment.

cedula

string

Updated national ID.

nombre

string

Updated first name.

apellido

string

Updated last name.

correo

string

Updated email address.

telefono

string

Updated phone number.

region

string

Updated region (location field).

estado

string

Updated state/province (location field). Note: the user account status (estado) is always reset to "activo" on update regardless of this field.

ciudad

string

Updated city.

sede

string

Updated office building.

piso

string

Updated floor.

alas

string

Updated wing.

Response

message

string

"Usuario actualizado y cambios registrados en bitácora."

Example

curl -X PUT http://localhost:3001/api/usuarios/abc123 \
  -H "Content-Type: application/json" \
  -H "Cookie: acceso_token=<JWT>" \
  -d '{
    "username": "jperez",
    "rol": "usuario",
    "cedula": "12345678",
    "nombre": "Juan",
    "apellido": "Pérez",
    "correo": "jperez@empresa.com",
    "telefono": "0414-9999999",
    "region": "Centro Occidental",
    "estado": "Lara",
    "ciudad": "Barquisimeto",
    "sede": "Torre Norte",
    "piso": "4"
  }'

PUT /api/usuarios/eliminado/:id

Soft-delete a user by setting their estado field to "inactivo". The user record is preserved in Firestore. A "Eliminar usuario" entry is written to the bitácora. Auth: Required.

This is a non-destructive operation. The user document is retained in Firestore and can be reactivated manually. The user will no longer appear in GET /api/usuarios since that endpoint filters by estado == "activo".

Request

string

required

Firestore document ID of the user to deactivate.

Response

message

string

"Usuario eliminado (lógicamente)."

Example

curl -X PUT http://localhost:3001/api/usuarios/eliminado/abc123 \
  -H "Cookie: acceso_token=<JWT>"

GET /api/usuarios/me

Returns the complete Firestore profile of the currently authenticated user, looked up by the correo claim embedded in the JWT. Unlike GET /api/me, this endpoint returns all stored fields — including cedula, telefono, ubicacion, and timestamps. Auth: Required.

The route /api/usuarios/me must be registered before /api/usuarios/:id in the router to avoid Express treating "me" as a document ID. This is already handled in the source routing order.

Request

No request body or query parameters.

Response

autenticado

boolean

Always true when the user is found.

user

object

Full Firestore document. Includes id (document ID), username, correo, rol, cedula, nombre, apellido, telefono, estado, ubicacion, id_ubicacion, createdAt, and updatedAt.

Example

curl http://localhost:3001/api/usuarios/me \
  -H "Cookie: acceso_token=<JWT>"

GET /api/me

Returns the lightweight JWT payload fields for the authenticated user. Useful for quickly checking the caller’s role and sede without a Firestore lookup. Auth: Required.

Request

No request body or query parameters.

Response

autenticado

boolean

Always true.

user.correo

string

Email address from the JWT payload.

user.username

string

Display name from the JWT payload.

user.rol

string

Role from the JWT payload.

user.sede

string

Office sede from the JWT payload.

Example

curl http://localhost:3001/api/me \
  -H "Cookie: acceso_token=<JWT>"

Authenticate a user with their email and password. On success, a signed JWT is returned in the response body and set as an HTTP-only cookie named acceso_token (expires in 1 hour). A "Login" event is written to the bitácora. Auth: Not required.

The cookie is configured with httpOnly: true and sameSite: "lax". The secure flag is currently false, meaning the cookie is sent over plain HTTP. Enable secure: true before deploying to a production HTTPS environment.

Request

correo

string

required

Registered email address.

password

string

required

Account password (plain text — transmitted over HTTPS in production).

Response

message

string

"Login exitoso"

token

string

Signed JWT containing id, rol, sede, username, and correo claims. Valid for 1 hour.

user.correo

string

Authenticated user’s email.

user.username

string

Authenticated user’s display name.

user.sede

string

Authenticated user’s office sede.

user.rol

string

Authenticated user’s role.

Example

curl -X POST http://localhost:3001/api/login \
  -H "Content-Type: application/json" \
  -d '{"correo": "jperez@empresa.com", "password": "S3cur3P@ss"}'

POST /api/logout

Clears the acceso_token session cookie. After this call the browser will no longer send the token with subsequent requests. Auth: Not required (the cookie is simply cleared regardless of its validity).

Request

No request body.

Response

message

string

"Sesión cerrada"

Example

curl -X POST http://localhost:3001/api/logout \
  -H "Cookie: acceso_token=<JWT>"

Overview

Endpoints

POST /api/usuarios

Request

Response

Example

GET /api/usuarios

Request

Response

Example

PUT /api/usuarios/:id

Request

Response

Example

PUT /api/usuarios/eliminado/:id

Request

Response

Example

GET /api/usuarios/me

Request

Response

Example

GET /api/me

Request

Response

Example

Request

Response

Example

POST /api/logout

Request

Response

Example

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​POST /api/usuarios

​Request

​Response

​Example

​GET /api/usuarios

​Request

​Response

​Example

​PUT /api/usuarios/:id

​Request

​Response

​Example

​PUT /api/usuarios/eliminado/:id

​Request

​Response

​Example

​GET /api/usuarios/me

​Request

​Response

​Example

​GET /api/me

​Request

​Response

​Example

​POST /api/login

​Request

​Response

​Example

​POST /api/logout

​Request

​Response

​Example

Build docs developers (and LLMs) love

POST /api/usuarios

Request

Response

Example

GET /api/usuarios

Request

Response

Example

PUT /api/usuarios/:id

Request

Response

Example

PUT /api/usuarios/eliminado/:id

Request

Response

Example

GET /api/usuarios/me

Request

Response

Example

GET /api/me

Request

Response

Example

POST /api/login

Request

Response

Example

POST /api/logout

Request

Response

Example