Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/GuillermoNavarro/Proyecto_comunidades/llms.txt

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

The Users API manages Usuario records — the residents, admins, and platform managers who interact with the system. The API supports role-based scoping: SUPER_ADMIN users can list all accounts across the platform, while ADMIN users operate within their own community (derived automatically from their JWT). Regular USER accounts can read and update their own profile and change their password.
The password field is write-only. It is accepted in POST request bodies but is never returned in any GET response.
All endpoints require a valid JWT Bearer token in the Authorization header unless stated otherwise.

​
GET /api/usuarios

Returns every user registered on the platform, across all communities.
Required role: SUPER_ADMIN
curl -X GET https://api.example.com/api/usuarios \
  -H "Authorization: Bearer <token>"
Response 200 OK — array of Usuario objects.
​
[].id
number
Unique identifier of the user.
​
[].dni
string
National identity document number.
​
[].nombre
string
First name of the user.
​
[].apellidos
string
Surname(s) of the user.
​
[].puerta
string
Apartment / door identifier within the building (e.g. "2B").
​
[].telefono
string
Contact phone number.
​
[].email
string
Email address — used as the login username.
​
[].rol
string
Role assigned to the user. One of USER, ADMIN, or SUPER_ADMIN.
​
[].coeficiente
number
Ownership coefficient (share of communal expenses) as a decimal (e.g. 0.05 = 5 %).
​
[].estado
boolean
true if the account is active; false if soft-deleted.
​
[].cambiarPass
boolean
true if the user must change their password on next login.
​
[].comunidad
object
The community this user belongs to.
Example response
[
  {
    "id": 1,
    "dni": "12345678A",
    "nombre": "Ana",
    "apellidos": "García López",
    "puerta": "3A",
    "telefono": "600123456",
    "email": "[email protected]",
    "rol": "USER",
    "coeficiente": 0.08,
    "estado": true,
    "cambiarPass": false,
    "comunidad": {
      "id": 1,
      "nombre": "Comunidad Los Pinos",
      "direccion": "Calle Mayor 10",
      "ciudad": "Madrid",
      "codPostal": "28001"
    }
  }
]
StatusMeaning
200OK — list returned (may be empty).
403Forbidden — caller does not have SUPER_ADMIN role.

​
GET /api/usuarios/comunidad

Returns all users belonging to the community encoded in the caller’s JWT. Useful for admins who need a roster of their own residents.
Required role: ADMIN or SUPER_ADMIN
curl -X GET https://api.example.com/api/usuarios/comunidad \
  -H "Authorization: Bearer <token>"
Response 200 OK — array of Usuario objects (same schema as GET /api/usuarios, scoped to the caller’s community).
StatusMeaning
200OK — list returned (may be empty).
403Forbidden — caller does not have the required role.

​
GET /api/usuarios/{idUsuario}

Retrieves a single user by their numeric id.
Required role: ADMIN or SUPER_ADMIN

​
Path parameters

​
idUsuario
number
required
The unique identifier of the user to retrieve.
curl -X GET https://api.example.com/api/usuarios/1 \
  -H "Authorization: Bearer <token>"
Response 200 OK — a single Usuario object (same schema as above).
StatusMeaning
200OK — user found and returned.
404Not Found — no user with that id exists.
403Forbidden — caller does not have the required role.

​
GET /api/usuarios/me

Returns the profile of the currently authenticated user, identified by the email claim in their JWT.
Required role: Any authenticated user (USER, ADMIN, or SUPER_ADMIN)
curl -X GET https://api.example.com/api/usuarios/me \
  -H "Authorization: Bearer <token>"
Response 200 OK — the caller’s own Usuario object (same schema as above).
Example response
{
  "id": 5,
  "dni": "87654321B",
  "nombre": "Carlos",
  "apellidos": "Martínez Ruiz",
  "puerta": "1C",
  "telefono": "611987654",
  "email": "[email protected]",
  "rol": "USER",
  "coeficiente": 0.05,
  "estado": true,
  "cambiarPass": false,
  "comunidad": {
    "id": 1,
    "nombre": "Comunidad Los Pinos",
    "direccion": "Calle Mayor 10",
    "ciudad": "Madrid",
    "codPostal": "28001"
  }
}
StatusMeaning
200OK — profile returned.
401Unauthorized — no valid JWT supplied.

​
POST /api/usuarios

Creates a new user within the admin’s community. The community is derived automatically from the JWT — do not include a comunidad object in the request body.
Required role: ADMIN or SUPER_ADMIN
The community is taken from the JWT automatically. Any comunidad field you include in the request body will be overwritten.

​
Request body

​
dni
string
required
National identity document number.
​
nombre
string
required
First name of the user.
​
apellidos
string
required
Surname(s) of the user.
​
puerta
string
Apartment / door identifier (e.g. "2B").
​
telefono
string
Contact phone number.
​
email
string
required
Email address — must be unique across the platform.
​
password
string
required
Initial password (will be BCrypt-encoded before storage). Never returned in responses.
​
rol
string
Role to assign. One of USER (default), ADMIN, or SUPER_ADMIN.
​
coeficiente
number
Ownership coefficient as a decimal (e.g. 0.08).
curl -X POST https://api.example.com/api/usuarios \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "dni": "12345678A",
    "nombre": "Ana",
    "apellidos": "García López",
    "puerta": "3A",
    "telefono": "600123456",
    "email": "[email protected]",
    "password": "SecurePass123!",
    "rol": "USER",
    "coeficiente": 0.08
  }'
Response 200 OK — the newly created Usuario object (password field omitted).
StatusMeaning
200OK — user created and returned.
409Conflict — a user with the given email already exists.
403Forbidden — caller does not have the required role.

​
PUT /api/usuarios/modificar

Allows a user to update their own profile. The user being modified is identified by the id claim in their JWT — no path parameter is needed.
Required role: USER, ADMIN, or SUPER_ADMIN
This endpoint updates the profile of the caller — users cannot modify other accounts via this endpoint. Admins who need to edit another user’s record should use PUT /api/usuarios/admin/{id}.

​
Request body

​
nombre
string
Updated first name.
​
apellidos
string
Updated surname(s).
​
puerta
string
Updated door / apartment identifier.
​
telefono
string
Updated phone number.
​
email
string
Updated email address.
​
coeficiente
number
Updated ownership coefficient.
curl -X PUT https://api.example.com/api/usuarios/modificar \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Ana",
    "apellidos": "García Martínez",
    "telefono": "600999888",
    "email": "[email protected]",
    "puerta": "3A",
    "coeficiente": 0.08
  }'
Response 200 OK — the updated Usuario object.
StatusMeaning
200OK — profile updated and returned.
404Not Found — user from JWT not found (should not occur in normal operation).
403Forbidden — caller is not authenticated.

​
PUT /api/usuarios/admin/{id}

Allows an admin to update any user’s profile by specifying the target user’s id in the path.
Required role: ADMIN or SUPER_ADMIN

​
Path parameters

​
id
number
required
The unique identifier of the user to update.

​
Request body

Same fields as PUT /api/usuarios/modificar. 
curl -X PUT https://api.example.com/api/usuarios/admin/5 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Carlos",
    "apellidos": "Martínez Sanz",
    "telefono": "611000111",
    "email": "[email protected]",
    "puerta": "1C",
    "coeficiente": 0.05
  }'
Response 200 OK — the updated Usuario object.
StatusMeaning
200OK — user updated and returned.
404Not Found — no user with that id exists. Returns "Usuario no encontrado.".
403Forbidden — caller does not have the required role.

​
DELETE /api/usuarios/{idUsuario}

Performs a soft delete on a user by setting their estado field to false. The record is retained in the database and is excluded from active user queries, but no data is permanently destroyed.
Required role: ADMIN or SUPER_ADMIN

​
Path parameters

​
idUsuario
number
required
The unique identifier of the user to deactivate.
curl -X DELETE https://api.example.com/api/usuarios/5 \
  -H "Authorization: Bearer <token>"
StatusMeaning
200OK — user deactivated. Returns "Usuario eliminado correctamente.".
404Not Found — no user with that id exists. Returns "Usuario no encontrado.".
403Forbidden — caller does not have the required role.

​
PATCH /api/usuarios/pass

Allows any authenticated user to change their own password by supplying the current password for verification alongside the new one.
Required role: Any authenticated user (USER, ADMIN, or SUPER_ADMIN)

​
Request body

​
oldPassword
string
required
The user’s current password, used for verification before the change is applied.
​
newPassword
string
required
The desired new password.
curl -X PATCH https://api.example.com/api/usuarios/pass \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "oldPassword": "OldPass123!",
    "newPassword": "NewSecurePass456!"
  }'
StatusMeaning
200OK — password changed. Returns "Contraseña modificada".
400Bad Request — either oldPassword or newPassword is missing or blank.
401Unauthorized — oldPassword does not match the stored password.
404Not Found — user from JWT not found.

​
PATCH /api/usuarios/admin/{id}

Resets a user’s password to a system-generated value and sends the new credentials to the user via email. No body is required.
Required role: ADMIN or SUPER_ADMIN

​
Path parameters

​
id
number
required
The unique identifier of the user whose password should be reset.
After a password reset, the user’s cambiarPass flag is set to true, forcing them to change their password on next login.
curl -X PATCH https://api.example.com/api/usuarios/admin/5 \
  -H "Authorization: Bearer <token>"
StatusMeaning
200OK — password reset and email sent.
404Not Found — no user with that id exists.
403Forbidden — caller does not have the required role.

Build docs developers (and LLMs) love

Get started for freeTalk to us