Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/JorLOrT/rappi2/llms.txt

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

The Roles API implements role-based access control (RBAC). A role (Rol) groups a set of permissions (Permiso). Each permission grants a specific accion on a named recurso. Every user is assigned exactly one role, and their allowed operations are derived from the permissions attached to that role. All endpoints require a valid Bearer token. Read operations require roles:read; mutations require roles:write; deletion of roles requires roles:delete.

​
Available resources and actions

recursoDescription
usuariosUser accounts
rolesRoles and permissions
sesionesRefresh token sessions
clientesClient records and addresses
ordenesDelivery orders, payments, invoices
conductoresDriver records
vehiculosVehicle fleet
asignacionesDelivery assignments
rutasPlanned routes and stops
trackingGPS pings
geocercasGeofences
incidenciasIncident reports and evidence
notificacionesNotifications
reportesAnalytics and reporting endpoints
auditoriaHTTP audit logs
*Wildcard — matches any resource
accionDescription
readList and retrieve
writeCreate and update
deleteDelete or revoke
*Wildcard — grants all actions

​
GET /api/roles/

List all roles together with their associated permissions. Authentication: Bearer token required.
Permission required: roles:read

​
Response — 200 OK

Returns an array of RolResponse objects.
​
id
number
required
Auto-incremented role ID.
​
nombre
string
required
Unique role name. Maximum 50 characters.
​
permisos
array
required
Permissions assigned to this role.
curl --request GET \
  --url https://api.example.com/api/roles/ \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

[
  {
    "id": 1,
    "nombre": "Cliente",
    "permisos": []
  },
  {
    "id": 2,
    "nombre": "Admin",
    "permisos": [
      { "id": 1, "rol_id": 2, "recurso": "*", "accion": "*" }
    ]
  }
]

​
POST /api/roles/

Create a new role. The new role starts with no permissions; add them with POST /api/roles/{rol_id}/permisos. Authentication: Bearer token required.
Permission required: roles:write

​
Request body

​
nombre
string
required
Unique role name. Maximum 50 characters.

​
Response — 201 Created

Returns the created RolResponse. 
curl --request POST \
  --url https://api.example.com/api/roles/ \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  --header 'Content-Type: application/json' \
  --data '{"nombre": "Supervisor"}'

{
  "id": 4,
  "nombre": "Supervisor",
  "permisos": []
}

​
GET /api/roles/

Retrieve a single role by ID, including all its permissions. Authentication: Bearer token required.
Permission required: roles:read

​
Path parameters

​
rol_id
number
required
ID of the role to retrieve.

​
Response — 200 OK

Returns a RolResponse. See GET /api/roles/ for the field list. 
curl --request GET \
  --url https://api.example.com/api/roles/4 \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

{
  "id": 4,
  "nombre": "Supervisor",
  "permisos": []
}

​
PATCH /api/roles/

Update a role’s name. Invalidates the permission cache for the role. Authentication: Bearer token required.
Permission required: roles:write

​
Path parameters

​
rol_id
number
required
ID of the role to update.

​
Request body

​
nombre
string
New unique name for the role. Maximum 50 characters.

​
Response — 200 OK

Returns the updated RolResponse. 
curl --request PATCH \
  --url https://api.example.com/api/roles/4 \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  --header 'Content-Type: application/json' \
  --data '{"nombre": "Coordinador"}'

{
  "id": 4,
  "nombre": "Coordinador",
  "permisos": []
}

​
DELETE /api/roles/

Delete a role permanently. The role must have no users assigned to it — reassign any existing users before deleting. Authentication: Bearer token required.
Permission required: roles:delete
This operation is permanent. If any users are still assigned to the role the request will return 409 Conflict. Reassign those users to a different role first.

​
Path parameters

​
rol_id
number
required
ID of the role to delete.

​
Response — 204 No Content

No response body is returned on success. 
curl --request DELETE \
  --url https://api.example.com/api/roles/4 \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

{
  "detail": "No se puede eliminar el rol: tiene usuarios asociados. Reasigna esos usuarios a otro rol antes de borrarlo."
}

​
GET /api/roles/permisos/all

List all permissions across all roles, with optional filters. Authentication: Bearer token required.
Permission required: roles:read

​
Query parameters

​
rol_id
number
Filter permissions to a specific role.
​
recurso
string
Filter permissions to a specific resource name (e.g. usuarios, ordenes).

​
Response — 200 OK

Returns an array of PermisoResponse objects.
​
id
number
required
Permission ID.
​
rol_id
number
required
ID of the role this permission belongs to.
​
recurso
string
required
Resource name.
​
accion
string
required
Granted action (read, write, delete, or *).
curl --request GET \
  --url 'https://api.example.com/api/roles/permisos/all?recurso=ordenes' \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

[
  { "id": 5, "rol_id": 3, "recurso": "ordenes", "accion": "read" },
  { "id": 6, "rol_id": 3, "recurso": "ordenes", "accion": "write" }
]

​
GET /api/roles/permisos/

Retrieve a single permission by ID. Authentication: Bearer token required.
Permission required: roles:read

​
Path parameters

​
permiso_id
number
required
ID of the permission to retrieve.

​
Response — 200 OK

Returns a PermisoResponse. See GET /api/roles/permisos/all for the field list. 
curl --request GET \
  --url https://api.example.com/api/roles/permisos/5 \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

{ "id": 5, "rol_id": 3, "recurso": "ordenes", "accion": "read" }

​
POST /api/roles//permisos

Add a permission to a role. The combination of rol_id, recurso, and accion must be unique. Invalidates the permission cache for the role. Authentication: Bearer token required.
Permission required: roles:write

​
Path parameters

​
rol_id
number
required
ID of the role to add the permission to.

​
Request body

​
recurso
string
required
Resource name the permission applies to (e.g. usuarios, ordenes, or *).
​
accion
string
required
Action to grant: read, write, delete, or *.

​
Response — 201 Created

Returns the created PermisoResponse. 
curl --request POST \
  --url https://api.example.com/api/roles/3/permisos \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  --header 'Content-Type: application/json' \
  --data '{"recurso": "ordenes", "accion": "write"}'

{ "id": 7, "rol_id": 3, "recurso": "ordenes", "accion": "write" }

​
DELETE /api/roles//permisos/

Remove a permission from a role. Invalidates the permission cache for the role. Authentication: Bearer token required.
Permission required: roles:write

​
Path parameters

​
rol_id
number
required
ID of the role that owns the permission.
​
permiso_id
number
required
ID of the permission to remove.

​
Response — 204 No Content

No response body is returned on success. 
curl --request DELETE \
  --url https://api.example.com/api/roles/3/permisos/7 \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

{ "detail": "Permiso no encontrado" }

Build docs developers (and LLMs) love

Get started for freeTalk to us