Entendimiento funcional
Un cargo en Buk es la definición estándar y reutilizable de un rol laboral dentro de la organización, que describe qué hace una persona en términos funcionales (propósito del rol, responsabilidades, funciones y requisitos), y que sirve como base común para ordenar y gestionar la información asociada a ese rol a lo largo del ciclo de vida del colaborador.
En términos funcionales, un cargo en Buk:
- Estandariza el “qué” del trabajo: nombre del rol y su alcance (funciones, responsabilidades, objetivos).
- Define el perfil esperado: competencias, conocimientos, experiencia y formación requeridas.
- Habilita gestión y control: permite asociar dotación, bandas salariales, activos y datos relevantes del rol.
- Soporta operación de RR.HH.: se usa como referencia para selección, onboarding, evaluación de desempeño y desarrollo.
- Aporta gobernanza: facilita criterios de acceso/visibilidad y la base para flujos internos relacionados al rol (según configuración).
Y para evitar confusiones con la estructura:
- Cargo = el rol (el qué).
- Área/Subárea = la ubicación organizacional (el dónde).
- Puesto de trabajo (si está disponible en tu configuración) = Cargo + Área/Subárea, es decir, la instancia específica del rol en un lugar de la estructura (el qué + dónde).
Consulta por API
Consideraciones generales:
- La API permite consultar empleados, devolviendo el role(cargo) las áreas a las cuales está vinculada.
- Al consultar por un cargo en específico, se usa el role_id y como respuesta se obtiene información respecto a este tal como descripción, áreas vinculadas, familia de cargos y atributos personalizados.
- A diferencia de las áreas, los cargos NO TIENEN una relación jerárquica entre ellos.
Consideraciones especiales:
- Cada cargo tiene un código numérico asociado al PK del registro de la base de datos.
- Cada cargo tiene un código alfanumérico irrepetible y separando palabras con guiones bajos (ejemplo: “presidente_del_directorio”)
- Un cargo debe tener áreas asignadas, al momento asignar un trabajo y asignar un cargo esta debe estar vinculada al área señalada en la petición.
- En Buk existen las familias de cargo, esto consiste en una agrupación lógica de puestos de trabajo con funciones y responsabilidades similares, se para organizar la estructura de la empresa, aplicar competencias comunes y facilitar la gestión del desarrollo del personal.
- Los atributos personalizados pueden estar configurados como “Atributo Sensible Para API”, en ese caso el token debe contar con permiso de lectura sensible.
🟦 GET /roles
Definición:
GET /roles: Retorna todos los cargos registrados en el sistema.
Permisos Requeridos:
Requiere un auth_token sin permisos especiales.
🟦 GET /roles - CURL Ejemplo
curl -X GET --header 'Accept: application/json' --header 'auth_token: {TOKEN}' 'https://{TENANT}.buk.cl/api/v1/chile/roles'🟦GET /roles - Ejemplo Respuesta
{ "pagination": { "next": "string", "previous": "string", "count": 0, "total_pages": 0 }, "data": [ { "id": 0, "code": "string", "name": "string", "description": "string", "requirements": "string", "role_family": { "id": 0, "name": "string", "quantity_of_roles": 0 }, "area_ids": [ 0 ], "custom_attributes": {} } ]}| Campo | Tipo | Descripción |
|---|---|---|
| pagination | object | Objeto que trae los datos de paginación de la petición. |
| next | string | Endpoint para realizar la petición a la siguiente página. |
| previous | string | Endpoint para realizar la petición a la siguiente página. |
| count | int | Cantidad de objetos que trae la petición actual. |
| total_pages | int | Cantidad de paginas que trae la petición. |
| data | array | Arreglo que trae los cargos asociados al tenant. |
| data.id | int | Id de la base de datos del Cargo |
| data.code | string | Código único del cargo. |
| data.name | string | Nombre del cargo |
| data.description | string | Descripción del cargo |
| data.requirements | string | Requisitos del cargo |
| data.area_ids | array | Arreglo de enteros que trae los ids de las áreas relacionadas a ese cargo |
| role_family | object | Objeto que trae la información de la familia de cargos a la cual está asociada el cargo. |
| role_family.id | int | Id de la familia de cargos a la cual está asociada el cargo. |
| role_family.name | string | Nombre de la familia de cargos a la cual está asociada el cargo. |
| role_family.quantity_of_roles | int | Cantidad de cargos que están asociados a esa familia de cargos. |
| custom_attributes | object | Objeto de tipo clave - valor que trae los atributos personalizados relacionados al cargo |
| custom_attributes.key | string | Es el nombre del atributo personalizado. |
| custom_attributes.key | object | Valor del atributo personalizado vinculado al cargo, puede ser de tipo string, int, date, array, file, |
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| search | string | NO | Campo que permite filtrar los roles por el nombre (campo name). |
| page_size | int | NO | Numero de respuestas por página. Por defecto tiene un valor de 25 y debe estar entre un rango de [25 - 100] |
🟦 GET /roles/{id}
Definición:
GET /roles/{id}: Retorna la información específica del cargo asociado al ID proporcionado.
Permisos Requeridos:
Requiere un auth_token sin permisos especiales.
🟦 GET/roles/{id} - CURL Ejemplo
curl -X GET --header 'Accept: application/json' --header 'auth_token: {TOKEN}' 'https://{TENANT}.buk.cl/api/v1/chile/roles/{ID_ROLE}'🟦GET /roles/{id}- Ejemplo Respuesta
{ "data": { "id": 0, "name": "string", "description": "string", "code": "string", "requirements": "string", "active": true, "area_ids": [ 0 ], "role_family_id": 0, "custom_attributes": {} }}| Campo | Tipo | Descripción |
|---|---|---|
| data | object | Objeto que trae los cargos asociados al tenant. |
| data.id | int | Id de la base de datos del Cargo |
| data.name | string | Nombre del cargo |
| data.description | string | Descripción del cargo |
| data.code | string | Código único del cargo. |
| data.requirements | string | Requisitos del cargo |
| role_family_id | int | Id de la familia de cargos a la cual está asociada el cargo. |
| custom_attributes | object | Objeto de tipo clave - valor que trae los atributos personalizados relacionados al cargo |
| custom_attributes.key | string | Es el nombre del atributo personalizado. |
| custom_attributes.key | object | Valor del atributo personalizado vinculado al cargo, puede ser de tipo string, int, date, array, file, |
🟩Creación Cargos
POST /roles
Definición:
POST /roles: Crea un nuevo cargo en el sistema
Permisos Requeridos:
Este endpoint no requiere permisos especiales.
🟩 POST /roles - CURL Ejemplo
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'auth_token: {TOKEN}' -d '{ \ "name": "string", \ "code": "string", \ "description": "string", \ "requirements": "string", \ "role_family_id": 0, \ "area_ids": [ \ 0 \ ], \ "custom_attributes": {} \ }' 'https://{TENANT}.buk.cl/api/v1/chile/roles'| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| name | string | SI | Nombre del cargo a crear |
| code | string | SI | Código único del cargo |
| description | string | NO | Descripción del cargo a crear. |
| requirements | string | NO | Requerimientos del cargo a crear |
| role_family_id | int | NO | Id de la familia de cargos |
| area_ids | array | NO | Arreglo de ids de las áreas relacionadas al cargo a crear |
| custom_attrs | object | NO | Objeto de atributos personalizados (clave/valor). |
🟩POST /roles - Reglas de Negocio
- Campos Personalizados: La cantidad, el nombre y el tipo de campos personalizados varían según la definición de cada cliente.
- Código Cargo: El código del cargo debe ser único y debe contener solo valores alfanuméricos y guiones bajos (sin espacios ni caracteres especiales).
- Jerarquía de Cargos: En BUK, los cargos no se ordenan jerárquicamente entre sí; la plataforma no establece relaciones de superioridad o dependencia entre cargos. La jerarquía organizacional se define a nivel de colaboradores, mediante la asignación de un jefe directo al momento de vincular un trabajo al colaborador.
🟧 Actualización de cargos.
🟧 PATCH /roles/{identifier}
Definición:
PATCH /roles/{identifier}: Es el método que te permite editar un cargo en el sistema.
Permisos Requeridos:
Este endpoint no requiere permisos especiales.
🟧PATCH /roles - CURL Ejemplo
curl -X PATCH --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'auth_token: {TOKEN}' -d '{ \ "name": "string", \ "description": "string", \ "requirements": "string", \ "active": true, \ "role_family_id": 0, \ "area_ids": [ \ 0 \ ], \ "custom_attributes": {} \ }' 'https://{TENANT}.buk.cl/api/v1/chile/roles/{ID_ROLE}'| Campo | Tipo | Descripción |
|---|---|---|
| name | string | Nombre del cargo a crear |
| description | string | Descripción del cargo a crear. |
| active | bool | Requerimientos del cargo a crear |
| role_family_id | int | Id de la familia de cargos |
| area_ids | array | Arreglo de ids de las áreas relacionadas al cargo a crear |
| custom_attrs | object | Objeto de atributos personalizados (clave/valor). |
🟦 GET /role_families
Definición:
GET /role_families: Retorna todas las familias de cargos registradas en el sistema.
Permisos Requeridos:
Requiere un auth_token sin permisos especiales.
🟦 GET /role_families- CURL Ejemplo
curl -X GET --header 'Accept: application/json' --header 'auth_token: {TOKEN}' 'https://{TENANT}.buk.cl/api/v1/chile/role_families'🟦GET /roles - Ejemplo Respuesta
{ "pagination": { "next": "string", "previous": "string", "count": 0, "total_pages": 0 }, "data": [ { "id": 0, "name": "string", "quantity_of_roles": 0 } ]}| Campo | Tipo | Descripción |
|---|---|---|
| pagination | object | Objeto que trae los datos de paginación de la petición. |
| next | string | Endpoint para realizar la petición a la siguiente página. |
| previous | string | Endpoint para realizar la petición a la siguiente página. |
| count | int | Cantidad de objetos que trae la petición actual. |
| total_pages | int | Cantidad de paginas que trae la petición. |
| data | array | Arreglo que trae las familias de cargos asociadas al tenant. |
| data.id | int | Id de la familia de cargos a la cual está asociada el cargo. |
| data.name | string | Nombre de la familia de cargos a la cual está asociada el cargo. |
| data.quantity_of_roles | int | Cantidad de cargos que están asociados a esa familia de cargos. |
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| search | string | NO | Campo que permite filtrar los roles por el nombre (campo name). |
| page_size | int | NO | Numero de respuestas por página. Por defecto tiene un valor de 25 y debe estar entre un rango de [25 - 100] |