Para comenzar, en esta guía aprenderás cómo funciona la estructura de áreas dentro de Buk y de qué manera puedes interactuar con ellas a través de nuestra API. Entenderás desde la jerarquía organizacional en forma de árbol que organiza a tu empresa, hasta la ejecución paso a paso de cada endpoint para consultar, crear, actualizar y eliminar áreas de manera eficiente.
Al finalizar este recorrido, contarás con todo el conocimiento necesario para integrar y manipular la estructura organizacional de tu tenant vía API, garantizando que los colaboradores y sus cargos queden asignados correctamente según las reglas de negocio del sistema.
Comprender la jerarquía organizacional y la profundidad (Depth)
Para iniciar, es fundamental comprender cómo representa Buk la estructura interna de una empresa. La gestión de áreas se organiza en una estructura jerárquica en forma de árbol, en la cual cada nivel establece una relación de padre e hijo.
El concepto clave en este diseño es depth (profundidad), un parámetro numérico que determina en qué nivel se ubica cada área dentro del árbol organizacional:
Depth 0 (División): Corresponde al nivel más alto de la organización. Es un nodo raíz que no depende de ninguna otra área (
parent_area: null).Depth 1 (Área / Gerencia): Es el nivel siguiente en la escala y depende directamente de una División (depth 0).
Depth 2 en adelante (Subárea / niveles subsiguientes): Son los niveles inferiores que dependen de los niveles anteriores.
División (depth 0)
|
|— — Área (depth 1)
|
|— — Subárea (depth 2)
|
|— — Cargos y TrabajadoresConsulta 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:
Permisos Requeridos:
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
GET /organization/areas/
Definición:
Permisos Requeridos:
Filtros:
Status (query, string):
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
POST /organization/areas/
Definición:
Permisos Requeridos:
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:
Permisos Requeridos:
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:
Permisos Requeridos:
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 |