Skip to main content

​
Rol (Role) API

The Role API manages user roles within the transportation request system. Roles define access permissions and are assigned to user profiles to control system capabilities.

​
Endpoints

Create Role

Create a new role entry

List All Roles

Get all active roles (unpaginated)

Get Role

Retrieve a specific role

List Roles

List roles with pagination

Update Role

Update an existing role

Delete Role

Soft delete a role

​
Create Role

POST /rol Create a new role in the system.

​
Request Body

​
codigo
string
required
Unique role code (e.g., “ADMIN”, “SOLICITANTE”, “APROBADOR”)
​
nombre
string
required
Role name (e.g., “Administrador”, “Solicitante”, “Aprobador”)

​
Example

curl -X POST https://api.example.com/rol \
  -H "Content-Type: application/json" \
  -d '{
    "codigo": "COORD_TRANS",
    "nombre": "Coordinador de Transporte"
  }'

​
Response

{
  "exito": true,
  "mensaje": "Rol creado exitosamente",
  "datos": {
    "id": 5,
    "codigo": "COORD_TRANS",
    "nombre": "Coordinador de Transporte",
    "eliminado": false,
    "fechaHoraCreacion": "2026-03-10T12:00:00",
    "fechaHoraActualizacion": "2026-03-10T12:00:00"
  }
}

​
List All Roles

GET /rol/todos/lista Retrieve all active roles without pagination. Ideal for dropdown menus and role assignment forms.

​
Query Parameters

​
codigo
string
Filter by role code (partial match)
​
nombre
string
Filter by role name (partial match)
​
busqueda
string
General search across codigo and nombre fields

​
Example

curl https://api.example.com/rol/todos/lista?busqueda=admin

​
Get Role by ID

GET /rol/ Retrieve a specific role by its ID.

​
Path Parameters

​
id_rol
integer
required
Role ID

​
Response

{
  "exito": true,
  "mensaje": "Rol obtenido exitosamente",
  "datos": {
    "id": 5,
    "codigo": "COORD_TRANS",
    "nombre": "Coordinador de Transporte",
    "eliminado": false,
    "fechaHoraCreacion": "2026-03-10T12:00:00",
    "fechaHoraActualizacion": "2026-03-10T12:00:00"
  }
}

​
List Roles (Paginated)

GET /rol List roles with pagination and filtering capabilities.

​
Query Parameters

​
pagina
integer
default:"1"
Page number (starts at 1)
​
por_pagina
integer
default:"10"
Records per page (max 100)
​
codigo
string
Filter by role code (partial match)
​
nombre
string
Filter by role name (partial match)
​
busqueda
string
General search across codigo and nombre fields

​
Example

curl https://api.example.com/rol?pagina=1&por_pagina=20

​
Response

{
  "exito": true,
  "mensaje": "Listado de roles obtenido exitosamente",
  "datos": {
    "registros": [
      {
        "id": 1,
        "codigo": "ADMIN",
        "nombre": "Administrador"
      },
      {
        "id": 2,
        "codigo": "SOLICITANTE",
        "nombre": "Solicitante"
      },
      {
        "id": 3,
        "codigo": "APROBADOR",
        "nombre": "Aprobador"
      }
    ],
    "paginacion": {
      "paginaActual": 1,
      "registrosPorPagina": 20,
      "totalRegistros": 3,
      "totalPaginas": 1
    }
  }
}

​
Update Role

PUT /rol/ Update an existing role. All fields are optional.

​
Path Parameters

​
id_rol
integer
required
Role ID

​
Request Body

​
codigo
string
Updated role code (must remain unique)
​
nombre
string
Updated role name (must remain unique)

​
Example

curl -X PUT https://api.example.com/rol/5 \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Coordinador General de Transporte"
  }'

​
Delete Role

DELETE /rol/ Soft delete a role. The role is marked as inactive rather than physically deleted.

​
Path Parameters

​
id_rol
integer
required
Role ID
Cannot delete roles that are currently assigned to active user profiles. Remove role assignments first.

​
Example

curl -X DELETE https://api.example.com/rol/5

​
Response

{
  "exito": true,
  "mensaje": "Rol eliminado exitosamente",
  "datos": {
    "id": 5,
    "codigo": "COORD_TRANS",
    "nombre": "Coordinador General de Transporte",
    "eliminado": true,
    "fechaHoraEliminacion": "2026-03-10T15:30:00"
  }
}

​
Response Codes

  • 200 - Success
  • 201 - Created
  • 404 - Role not found
  • 409 - Conflict (duplicate codigo or nombre, or role in use)
  • 500 - Internal server error

​
Common Roles

Typical roles in the system include:
  • ADMIN - System administrator with full access
  • SOLICITANTE - User who can create transport requests
  • APROBADOR - User who can approve/reject requests
  • COORD_TRANS - Transport coordinator managing missions
  • MOTORISTA - Driver with mobile app access

Build docs developers (and LLMs) love

Get started for freeTalk to us