Entendimiento funcional
En Buk, la gestión de áreas se basa en una estructura jerárquica en forma de árbol, donde cada nivel representa una relación padre-hijo que define la organización interna de la empresa. Esta estructura permite organizar divisiones, áreas y sub áreas de manera flexible, asegurando que los colaboradores y sus cargos sean asignados correctamente según las reglas establecidas.
El concepto de depth (profundidad) es clave para entender la jerarquía, ya que determina el nivel en el que se encuentra un área dentro del árbol organizacional. Desde depth 0 (División) hasta niveles más profundos, cada área tiene una única área padre y puede contener múltiples subáreas, con la restricción de que sólo a partir de depth 2 se pueden asignar cargos y colaboradores.
- Jerarquía de Niveles (Depth):
- Depth 0: Nivel más alto, no depende de otra área. Ejemplo: "División".
- Depth 1: Nivel siguiente. Ejemplo: "Área".
- Depth 2 en adelante: Niveles subsiguientes, donde pueden estar asociados los colaboradores.
División (depth 0)
|
| — — Área (depth 1)
|
|— — Subárea (depth 2)
|
| — — Cargos, Trabajadores.
Los cargos y colaboradores solo se pueden agregar a partir del Nivel 2 (sub área), teniendo en cuenta que pueden existir un sin fin de subáreas, ya que éstas dependen de la estructura definida que pueda tener el cliente; con éste lineamiento en buk, los colaboradores y cargos, se asignan al último nível creado en la jerarquía, independiente de la cantidad de niveles por división.
Consulta por API
Consideraciones generales:
- La API permite consultar empleados, devolviendo el current_job y el área asociada.
- Al consultar por un área específica, se usa area_id y se devuelve información sobre su nivel (depth) y su área padre (parent_area).
- Un área puede tener varías children_area pero solo un parent_area.
Consideraciones especiales:
- El nodo “División” siempre contará con el parámetro depth: 0, correspondiente al nivel más alto del nodo, quiere decir que no depende de otra área, donde parámetro parent_area: null
- No puede existir un área de ningún nivel (depth>0) que no dependa de una división.
- Tener en cuenta que solo desde depth 2 hacía adelante pueden tener un trabajo asociado que pueda representar el concepto área dentro del frontend.
- Lo que está mapeado como área en frontend, en el endpoint nunca tendrá dependencia, es decir, el parámetro children_area: [ ] (vacío)
- depth:0 y depth:1 siempre corresponderá a división y gerencia respectivamente (no existirá variabilidad para depth en ambos casos)
- El parámetro area_id en el endpoint de employee, siempre corresponderá al concepto área del frontend.
| ÍTEM/REGLA | Descripción funcional |
|---|---|
| Consulta de Colaborador → área | Desde /employees, se obtiene current_job.area_id. |
| Consulta de área por ID | Con el area_id anterior, se consulta en /areas para obtener depth, parent_area y children_area. |
| Trazado jerárquico hacia arriba | Usando recursivamente parent_area, se reconstruye el árbol: División (depth 0) → Gerencia (depth 1) → Subgerencias/Áreas (depth ≥ 2). |
| Identificación del área mostrada en frontend | El área mostrada como “área” en frontend corresponde al nodo donde está el trabajo (current_job.area_id), que debe ser es_area_asignable = true (depth ≥ 2 y sin hijos). |
| Restricción de áreas de nivel alto | depth 0 (División) y depth 1 (Gerencia/Área) son fijos como conceptos de negocio. No se asignan colaboradores ni cargos directamente a estos niveles. |
| Consistencia jerárquica | No puede existir un área con depth > 0 sin una División raíz: cualquier área debe poder remontarse por parent_area hasta un nodo con depth=0 y parent_area=null. |
GET /organization/areas/{id}
Definición:
GET /organization/areas/{id}: Retorna el área correspondiente al ID, incluyendo aquellas de nivel 0 y nivel 1.
Permisos Requeridos:
Requiere un auth_token sin permisos especiales.
GET/organization/areas/{id} - CURL Ejemplo
curl -X GET --header 'Accept: application/json' --header 'auth_token: {{AUTH_TOKEN}}' 'https://{{TENANT}}.buk.cl/api/v1/chile/organization/areas/{ID_AREA}'GET/organization/areas/{id}- Ejemplo Respuesta
{ "data": { "id": 0, "name": "string", "address": "string", "children_area": [ { "id": 0, "name": "string", "commune": "string", "city": "string", "address": "string" } ], "parent_area": { "id": 0, "name": "string", "commune": "string", "city": "string", "address": "string" }, "first_level_id": 0, "first_level_name": "string", "second_level_id": 0, "second_level_name": "string", "depth": 0, "cost_center": "string", "status": "string", "custom_attributes": {}, "city": "string" }}| Campo | Tipo | Descripción |
|---|---|---|
| id | integer | Id del área consultada |
| name | string | nombre del área consultada |
| children_area | object | Objeto con Área hijas. (id, name, city, comune, address) |
| parent_area | object | Objeto con Área padre. (id, name, city, comune, address) |
| first_level_id | int | Dirección del Id del área de primer nivel del Área |
| first_level_name | string | Nombre del área de primer nivel del Área. |
| second_level_id | int | Id del área de segundo nivel del Área. |
| second_level_name | string | Nombre del área de segundo nivel del Área. |
| cost_center | string | Código centro de costo |
| status | string | Estado del Área (activo o inactivo). |
| custom_attributes | object | Atributos personalizados. |
| city | string | Ciudad del Área. |
GET/organization/areas/{ID} - 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.
Jerarquía: Las áreas de nivel 0 no tienen parent_area
GET /organization/areas/
Definición:
GET /organization/areas/: Es el método que te permite obtener el maestro de las áreas.
Permisos Requeridos:
Requiere un auth_token sin permisos especiales.
Filtros:
- Status (query, string):
Define el estado de las áreas a filtrar. Los valores permitidos son:
- active
- inactive
- both (default)
- page_size (query, integer):
- El tamaño de la página determina la cantidad de objetos que trae la consulta, el mínimo es 25 y el máximo 100.
- page (query, integer):
- Por rendimiento de la respuesta, los resultados son paginados.
GET/organization/areas - CURL Ejemplo
curl -X GET \ "https://{{TENANT}}.buk.cl/api/v1/chile/organization/areas?status=both&page_size=25&page=1" \ -H "auth_token: {{AUTH_TOKEN}}" \ -H "Accept: application/json"GET/organization/areas - Ejemplo Respuesta
{ "pagination": { "next": "string", "previous": "string", "count": 0, "total_pages": 0 }, "data": [ { "id": 0, "name": "string", "address": "string", "children_area": [ { "id": 0, "name": "string", "commune": "string", "city": "string", "address": "string" } ], "parent_area": { "id": 0, "name": "string", "commune": "string", "city": "string", "address": "string" }, "first_level_id": 0, "first_level_name": "string", "second_level_id": 0, "second_level_name": "string", "depth": 0, "cost_center": "string", "status": "string", "custom_attributes": {}, "city": "string" } ]}GET/organization/areas - 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.
POST /organization/areas/
Definición:
POST /organization/areas/: Es el método que te permite crear un área en el sistema.
Permisos Requeridos:
Este endpoint no requiere permisos especiales.
POST /organization/areas - CURL Ejemplo
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'auth_token: {{AUTH_TOKEN}}' -d '{ \ "parent_id": 0, \ "location_id": 0, \ "name": "string", \ "accounting_prefix": "string", \ "city": "string", \ "address": "string", \ "cost_center_id": "string", \ "role_ids": [ \ 0 \ ], \ "custom_attrs": {} \ }' 'https://{{TENANT}}.buk.cl/api/v1/chile/organization/areas'| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| parent_id | integer | CONDICIONAL | ID del Área padre. Define la jerarquía. |
| location_id | integer | SI | ID de la ubicación asociada al Área. |
| name | string | SI | Nombre del Área a crear. |
| accounting_prefix | string | NO | Prefijo de costos. |
| city | string | NO | Ciudad del Área. |
| address | string | NO | Dirección del Área |
| cost_center_id | string | NO | ID del centro de costo asociado |
| role_ids | array | SI | Ids de los roles del Área a crear |
| custom_attrs | object | SI | Objeto de atributos personalizados (clave/valor). |
POST /organization/areas - 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.
- Locación: El campo location_id identifica la unidad geográfica (Comuna, Provincia o Región) y debe obtenerse a través del endpoint GET /locations.
- Nota: Se recomienda utilizar localidades con depth 3 (nivel comuna). Esto garantiza una vinculación de datos más directa y eficiente entre las tablas relacionadas.
- Centro de costo: El campo cost_center_id puede ser obtenido desde el endpoint get /centro_costo_definitions.
- Roles: El campo role_ids recibe la lista de identificadores de cargos asociados al área creada.
- Nota: Dado que un área puede contener múltiples cargos, al asignar un trabajo a un colaborador es obligatorio validar que el cargo seleccionado pertenezca efectivamente al área indicada.
- Jerarquía y Niveles: La estructura de áreas se organiza en tres niveles mediante el campo parent_id: División, Área y Sub-área.
- Nota: Aunque la jerarquía permite tres niveles, la vinculación de trabajos o colaboradores está restringida exclusivamente al último nivel (Sub-área, identificada con depth: 2). No se permite asignar trabajos a niveles superiores (División o Área).
PATCH /organization/areas/{ID}
Definición:
PATHC /organization/areas/{ID}: Es el método que te permite editar un área en el sistema.
Permisos Requeridos:
Este endpoint no requiere permisos especiales.
PATCH /organization/areas - CURL Ejemplo
curl -X PATCH --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'auth_token: {token}' -d '{ \ "name": "string", \ "accounting_prefix": "string", \ "city": "string", \ "address": "string", \ "cost_center_id": "string", \ "location_id": 0, \ "active": true, \ "role_ids": [ \ 0 \ ], \ "custom_attrs": {} \ }' 'https://{tenant}.buk.cl/api/v1/chile/organization/areas/{id}'| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| location_id | integer | NO | ID de la ubicación asociada al Área. |
| name | string | NO | Nombre del Área a crear. |
| accounting_prefix | string | NO | Prefijo de costos. |
| city | string | NO | Ciudad del Área. |
| address | string | NO | Dirección del Área |
| cost_center_id | string | NO | ID del centro de costo asociado |
| role_ids | array | NO | Ids de los roles del Área a crear |
| custom_attrs | object | NO | Objeto de atributos personalizados (clave/valor). |
| active | bool | NO | Estado del Área |
PATCH /organization/areas/{id} - 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.
- Locación: El campo location_id identifica la unidad geográfica (Comuna, Provincia o Región) y debe obtenerse a través del endpoint GET /locations.
- Nota: Se recomienda utilizar localidades con depth 3 (nivel comuna). Esto garantiza una vinculación de datos más directa y eficiente entre las tablas relacionadas.
- Centro de costo: El campo cost_center_id puede ser obtenido desde el endpoint get /centro_costo_definitions.
- Roles: El campo role_ids recibe la lista de identificadores de cargos asociados al área creada.
- Nota: Dado que un área puede contener múltiples cargos, al asignar un trabajo a un colaborador es obligatorio validar que el cargo seleccionado pertenezca efectivamente al área indicada.
- Jerarquía y Niveles: El campo parent_id no es modificable.
- Estado: Al cambiar el estado de un área a false esta dejará de ser visible en la interfaz.
DELETE /organization/areas
Definición:
DELETE /organization/areas: Es el método que te permite eliminar un área en el sistema.
Permisos Requeridos:
Este endpoint no requiere permisos especiales.
DELETE /organization/areas - CURL Ejemplo
curl -X DELETE --header 'Accept: application/json' --header 'auth_token: Fe2zaWXu1jf69QaCmCQaqEa8' 'https://{tenantCliente}.buk.cl/api/v1/chile/organization/areas?id={idArea}'
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
id | integer | SI | ID del área a eliminar |