openapi: 3.2.0
info:
title: Buk Colaboradores API
version: '1.0'
description: 'Operations tagged Colaboradores across 5 of this provider''s published API definitions: buk-data-access-api-brasil-openapi.yml, buk-data-access-api-chile-openapi.yml, buk-data-access-api-colombia-openapi.yml, buk-data-access-api-mexico-openapi.yml, buk-data-access-api-peru-openapi.yml. Each path carries the servers of the definition it was published in.'
host: demo.buk.cl
tags:
- name: Colaboradores
paths:
/employees:
get:
summary: 'Display Translation missing: en-br.{custom_translations.models.employee.other'
description: "Provides information of all Colaboradores.\n\n**Permisos requeridos para utilizar este endpoint:** \n* Employee permissions en: 'Lectura' o 'Lectura y Modificación'.\n"
tags:
- Colaboradores
parameters:
- name: status
in: query
type: string
description: 'Status of the Colaborador. allowed values are: active, inactive, pending'
- name: document_numberdocument_number
in: query
type: string
description: Document number
- name: code_sheet
in: query
type: string
description: Colaborador profile code
- name: company_id
in: query
type: string
description: ID of the Empresa
- name: update_start_date
in: query
type: string
format: date
description: Update date. If the company_id attribute is used, it will validate the active job at that date to determine the information to display. If empty, the current date will be considered
- name: custom_attr_job_name
in: query
type: string
description: Name of the custom job attribute
- name: custom_attr_job_value
in: query
type: string
description: Value of the custom Job attribute (if more than one, separate them by ::, e.g. Value1::Value2)
- name: email
in: query
type: string
description: Work email of the Colaborador
- name: code_recinto
in: query
type: string
description: Code of the Recinto
- name: page_size
in: query
type: integer
description: Size of the page
- name: page
in: query
type: integer
description: Page number
- name: sort
in: query
type: string
description: Parameter to sort records, the only possible value is "id"; if not sent, it is sorted by name
responses:
'200':
description: 'A list of Colaboradores that meet the search criteria.
'
schema:
$ref: '#/definitions/EmployeeResponseCountry'
post:
summary: Create an Colaborador
description: "Stores information of the Colaboradores. If the active key with value true is not sent, it will be created as inactive. The \"code_sheet\" identifier is optional; it will be autogenerated if not sent and the person does not previously exist (personal data sent are not used by another Colaborador).\n\n**Permisos requeridos para utilizar este endpoint:** \n* Employee permissions en: 'Lectura y Modificación'.\n"
tags:
- Colaboradores
parameters:
- name: Employee
in: body
description: Employee type object
required: true
schema:
$ref: '#/definitions/Employee::Response::Minimal'
responses:
'201':
description: Colaborador created.
schema:
title: ResponseBody
properties:
employee:
$ref: '#/definitions/EmployeeResponseCountry'
'400':
description: There is an error with the data submitted
schema:
$ref: '#/definitions/bad_request'
/employees/{id}/clone:
post:
summary: 'Create a new profile for an Translation missing: en-br.{custom_translations.models.employee.one'
description: "Allows creating a new record based on an existing one. This includes the details of each dependent family member. It receives the fields that will be different; the others will be copied from the reference record.\n\n**Permisos requeridos para utilizar este endpoint:** \n* Employee permissions en: 'Lectura y Modificación'.\n"
parameters:
- name: id
in: path
description: ID of the Colaborador to be cloned.
required: true
type: string
- name: Employee
in: body
description: Employee type object
required: true
schema:
$ref: '#/definitions/EmployeeInputCloneCountry'
tags:
- Colaboradores
responses:
'201':
description: Colaborador created.
schema:
title: ResponseBody
properties:
employee:
$ref: '#/definitions/EmployeeResponseCountry'
'400':
description: There is an error with the data submitted
schema:
$ref: '#/definitions/bad_request'
/employees/active:
get:
summary: List Colaboradores
description: "Returns all the active Colaboradores in the system. An active Colaborador is a Colaborador with an active plan and job on the selected date.<br><br> Optionally, it receives the date (in YYYY-MM-DD format) on which they must have an active contract as a parameter. If this parameter is not provided, today\\'s date from the open month in the application will be used.<br> Additionally, it can receive an optional parameter to exclude Colaboradores who are pending.\n\n\n**Permisos requeridos para utilizar este endpoint:** \n* Employee permissions en: 'Lectura' o 'Lectura y Modificación'.\n"
tags:
- Colaboradores
parameters:
- name: RUT
in: query
type: string
description: RUT
- name: code_sheet
in: query
type: string
description: Colaborador profile code
- name: date
in: query
type: string
format: date
description: Date to evaluate if the Colaboradores have an active contract, in YYYY-MM-DD format. If not entered, today's date on the platform will be used by default
- name: exclude_pending
in: query
type: boolean
description: Excludes pending Colaboradores if this parameter is sent as `true`
- name: page_size
in: query
type: integer
description: (OPTIONAL) Number of answers per page. By default it has a value of 25 and must be within a range of [25 - 100].
responses:
'200':
description: 'As a response, we receive an array (data) with the information of the other Colaboradores''.
'
schema:
properties:
pagination:
$ref: '#/definitions/Pagination'
data:
type: array
items:
$ref: '#/definitions/EmployeeResponseCountry'
/employees/{id}:
get:
summary: 'Display Translation missing: en-br.{custom_translations.models.employee.one'
description: "We receive specific information of the Colaborador whose ID or RUT we sent in the search query.\n\n\n**Permisos requeridos para utilizar este endpoint:** \n* Employee permissions en: 'Lectura' o 'Lectura y Modificación'.\n"
tags:
- Colaboradores
parameters:
- name: id
in: path
description: ID or Document Number of the Colaborador to query. If it is Document Number, it must not contain dots or hyphens.
required: true
type: string
responses:
'200':
description: '''As a response we receive all the fields corresponding to the information of the queried Colaborador''
'
schema:
$ref: '#/definitions/EmployeeResponseCountry'
patch:
summary: Update Colaborador
description: "Update the information of the Colaborador.\n\n**Permisos requeridos para utilizar este endpoint:** \n* Employee permissions en: 'Lectura y Modificación'.\n"
tags:
- Colaboradores
parameters:
- name: id
in: path
description: ID or Document Number of the Colaborador to query. If it is Document Number, it must not contain dots or hyphens.
required: true
type: string
- name: Employee
in: body
description: Employee type object
required: true
schema:
$ref: '#/definitions/EmployeeResponsePatch'
responses:
'200':
description: Colaborador updated.
schema:
title: ResponseBody
properties:
data:
$ref: '#/definitions/Employee::Response'
/employees/{id}/subordinates:
get:
summary: Display Colaboradores subordinate to other Colaborador
description: "We receive a list of subordinate Colaboradores\n\n**Permisos requeridos para utilizar este endpoint:** \n* Employee permissions en: 'Lectura' o 'Lectura y Modificación'.\n"
tags:
- Colaboradores
parameters:
- name: id
in: path
description: ID or Document Number of the Colaborador to query. If it is Document Number, it must not contain dots or hyphens.
required: true
type: string
- name: date
in: query
type: string
format: date
description: Date to evaluate if subordinate Colaboradores have an active contract, in YYYY-MM-DD format. If not entered, today's date on the platform will be used by default.
- name: page_size
in: query
type: integer
description: (OPTIONAL) Number of answers per page. By default it has a value of 25 and must be within a range of [25 - 100].
responses:
'200':
description: 'As a response, we receive an array (data) with the information of the other Colaboradores''.
'
schema:
properties:
pagination:
$ref: '#/definitions/Pagination'
data:
type: array
items:
$ref: '#/definitions/MinimalEmployee'
/employees/{id}/vacations_available:
get:
summary: Display number of days available for vacation
description: "We received the number of days.\n\n**Permisos requeridos para utilizar este endpoint:** \n* Vacation permissions en: 'Lectura' o 'Lectura y Modificación'.\n"
tags:
- Colaboradores
parameters:
- name: id
in: path
required: true
description: ID or Document Number of the Colaborador to query. If it is Document Number, it must not contain dots or hyphens.
type: string
- name: discount
in: query
description: Deduct future vacation taken (true, false).
enum:
- true
- false
type: boolean
- name: date
in: query
type: string
format: date
description: 'Date to calculate pending vacations (Format: DD-MM-YYYY); default is the last day of the open month'
responses:
'200':
description: '‘As a response, we receive an array (data) with the information of the Colaborador and their vacations''
'
schema:
$ref: '#/definitions/VacationsAvailable'
'400':
description: There is an error with the data submitted
schema:
$ref: '#/definitions/bad_request'
/employees/{id}/earned_vacations:
get:
summary: Show details of accrued vacation and proportional simulation
description: "Displays details of accrued vacations and proportional simulation up to a certain date.\n\n**Permisos requeridos para utilizar este endpoint:** \n* Vacation permissions en: 'Lectura' o 'Lectura y Modificación'.\n"
tags:
- Colaboradores
parameters:
- name: id
in: path
description: ID or Document Number of the Colaborador to query. If it is Document Number, it must not contain dots or hyphens.
required: true
type: string
- name: date
in: query
description: 'Date to calculate accrued vacations and simulate proportionals (Format: DD-MM-YYYY); default is today
'
type: string
format: date
- name: page
in: query
type: integer
description: (OPTIONAL) Page for query
- name: page_size
in: query
type: integer
description: (OPTIONAL) Number of answers per page. By default it has a value of 25 and must be within a range of [25 - 100].
responses:
'200':
description: 'As a response, we receive an array (data) with information about accrued and proportional vacations of the Colaborador
'
schema:
properties:
pagination:
$ref: '#/definitions/Pagination'
data:
type: array
items:
$ref: '#/definitions/EarnedVacations'
'400':
description: There is an error with the data submitted
schema:
$ref: '#/definitions/bad_request'
/employees/{employee_id}/family_responsibilities/{id}:
get:
summary: Display Dependents of a Colaborador
description: "Returns information of a Dependents associated with a Colaborador.\n\n**Permisos requeridos para utilizar este endpoint:** \n* Employee permissions en: 'Lectura' o 'Lectura y Modificación'.\n\n**General requerida para utilizar este endpoint:** \n* Habilitar grupo familiar, valor: true.\n"
tags:
- Colaboradores
parameters:
- name: employee_id
in: path
description: ID of the Colaborador to be queried.
required: true
type: string
- name: id
in: path
description: ID of the Dependents to query.
required: true
type: string
responses:
'200':
description: Information of the Dependents associated with the Colaborador.
schema:
properties:
data:
$ref: '#/definitions/EmployeeFamilyResponsibility'
'404':
description: The requested resource does not exist
name: errors
schema:
properties:
errors:
type: array
items:
type: string
/employees/{id}/pension_savings:
get:
summary: View pension savings
description: "Obtain pension savings using the ID of an Colaborador\n\n**Permisos requeridos para utilizar este endpoint:** \n* Employee permissions en: 'Lectura'.\n* Item permissions en: 'Lectura'.\n"
tags:
- Colaboradores
parameters:
- name: id
in: path
type: string
required: true
description: Colaborador ID
- name: date
in: query
type: string
format: date
description: Filter the pension savings that are current for this date
responses:
'200':
description: As a response, we receive a list of objects of pension savings type
schema:
properties:
data:
type: array
items:
$ref: '#/definitions/PensionSaving'
'404':
description: The requested resource does not exist
name: errors
schema:
properties:
errors:
type: array
items:
type: string
/employees/{id}/plans:
get:
summary: Display an employee's plans
description: "Displays the information of the plans associated to a Colaborador.\n(endpoint not implemented for Mexico)\n\n**Permisos requeridos para utilizar este endpoint:** \n* Employee permissions en: 'Lectura'.\n"
tags:
- Colaboradores
parameters:
- name: id
in: path
description: ID of the Colaborador to be queried.
required: true
type: string
responses:
'200':
description: An array (data) with the information of the plans associated to the Colaborador.
schema:
properties:
pagination:
$ref: '#/definitions/Pagination'
data:
type: array
items:
$ref: '#/definitions/PlanResponseCountry'
post:
summary: Add a plan to an employee
description: "Creates a new plan for the Colaborador in the system\n(endpoint not implemented for Mexico)\n\n**Permisos requeridos para utilizar este endpoint:** \n* Employee permissions en: 'Lectura y Modificación'.\n"
tags:
- Colaboradores
parameters:
- name: id
in: path
description: ID of the Colaborador to be queried.
required: true
type: string
- name: Plan
in: body
description: Plan type object
required: true
schema:
$ref: '#/definitions/PlanInputCountry'
responses:
'201':
description: As a response, we receive an array (data) with the information of the created plan
schema:
properties:
data:
$ref: '#/definitions/PlanResponseCountry'
'400':
description: There is an error with the data submitted
schema:
$ref: '#/definitions/bad_request'
/employees/{employee_id}/plans/{id}:
get:
summary: Display an employee's plan
description: "Returns the information of a plan associated with a Colaborador.\n(endpoint not implemented for Mexico)\n\n**Permisos requeridos para utilizar este endpoint:** \n* Employee permissions en: 'Lectura'.\n"
tags:
- Colaboradores
parameters:
- name: employee_id
in: path
description: ID of the Colaborador to be queried.
required: true
type: string
- name: id
in: path
description: ID of the plan to query.
required: true
type: string
responses:
'200':
description: The information of the plan associated with the Colaborador.
schema:
properties:
data:
$ref: '#/definitions/PlanResponseCountry'
patch:
summary: Update a plan to an employee
description: "Updates a plan linked with an Colaborador in the system\n(endpoint not implemented for Mexico)\n\n**Permisos requeridos para utilizar este endpoint:** \n* Employee permissions en: 'Lectura y Modificación'.\n"
tags:
- Colaboradores
parameters:
- name: employee_id
in: path
description: ID of the Colaborador to be updated.
required: true
type: string
- name: id
in: path
description: ID of the plan to be updated.
required: true
type: string
- name: Plan
in: body
description: Plan type object
required: true
schema:
$ref: '#/definitions/PlanInputCountry'
responses:
'201':
description: As a response, we receive an array (data) with the information of the updated plans
schema:
properties:
data:
$ref: '#/definitions/PlanResponseCountry'
'400':
description: There is an error with the data submitted
schema:
$ref: '#/definitions/bad_request'
/employees/{id}/jobs:
get:
summary: Display jobs of a Colaborador
description: "Displays the job information associated with a Colaborador.\n\n**Permisos requeridos para utilizar este endpoint:** \n* Employee permissions en: 'Lectura'.\n"
tags:
- Colaboradores
parameters:
- name: id
in: path
description: ID of the Colaborador to be queried.
required: true
type: string
responses:
'200':
description: An array (data) with the information of the jobs associated to the Colaborador.
schema:
properties:
pagination:
$ref: '#/definitions/Pagination'
data:
type: array
items:
$ref: '#/definitions/JobResponseCountry'
post:
summary: Add a job to Colaborador
description: "Creates a new job for the Colaborador in the system\n\n**Permisos requeridos para utilizar este endpoint:** \n* Employee permissions en: 'Lectura y Modificación'.\n"
tags:
- Colaboradores
parameters:
- name: id
in: path
description: ID of the Colaborador to be queried.
required: true
type: string
- name: Job
in: body
description: Job type object
required: true
schema:
$ref: '#/definitions/JobInputCountryPost'
responses:
'201':
description: As a response, we receive an array (data) with the information of the created job
schema:
properties:
data:
$ref: '#/definitions/JobResponseCountry'
'409':
description: Records are being updated concurrently.
name: errors
schema:
properties:
errors:
type: array
items:
type: string
'400':
description: There is an error with the data submitted
schema:
$ref: '#/definitions/bad_request'
/employees/{employee_id}/jobs/{id}:
patch:
summary: Update a job for a Colaborador
description: "Creates a new job for the Colaborador in the system\n\n**Permisos requeridos para utilizar este endpoint:** \n* Employee permissions en: 'Lectura y Modificación'.\n"
tags:
- Colaboradores
parameters:
- name: employee_id
in: path
description: ID of the Colaborador to be updated.
required: true
type: string
- name: id
in: path
description: ID of the job to be updated.
required: true
type: string
- name: Job
in: body
description: Job type object
required: true
schema:
$ref: '#/definitions/JobInputCountry'
responses:
'201':
description: As a response, we receive an array (data) with the information of the updated job
schema:
properties:
data:
$ref: '#/definitions/JobResponseCountry'
'400':
description: There is an error with the data submitted
schema:
$ref: '#/definitions/bad_request'
/employees/{employee_id}/jobs/{job_id}/cost_centers:
patch:
summary: Update the cost center in a job for a Colaborador
description: "The cost centers of a job are replaced, i.e., existing ones are deleted and new ones are added.\n\n\n\nRemember that the weights must sum up to 100.\n\n**Permisos requeridos para utilizar este endpoint:** \n* Employee permissions en: 'Lectura y Modificación'.\n"
tags:
- Colaboradores
parameters:
- name: employee_id
in: path
type: integer
- name: job_id
in: path
type: integer
- name: cost center
in: body
required: true
schema:
properties:
cost_centers_attributes:
type: array
items:
properties:
weight:
type: number
description: Weight
cost_center:
type: string
description: Cost Center
skip_webhook_notification:
type: boolean
description: (OPCIONAL) Si es true, omite el envío del webhook de notificación de cambios al modificar los centros de costo. Por defecto es false y el webhook se envía normalmente.
example: false
responses:
'201':
description: As a response, the information of the updated job cost centers is received.
schema:
properties:
data:
properties:
job_id:
type: integer
employee_id:
type: integer
cost_center:
type: string
cost_centers:
$ref: '#/definitions/CostCenterModel'
/employees/{id}/docs:
post:
summary: Add a document to employee
description: "We receive a document, which will be related to the employee.\n\n**Permisos requeridos para utilizar este endpoint:** \n* Permissions to upload documents en: 'Sí'.\n"
tags:
- Colaboradores
parameters:
- name: id
in: path
type: integer
required: true
description: ID of the employee to be queried.
- name: file
in: formData
description: Document to be uploaded.
required: false
type: file
- name: file_base64
in: formData
description: 'Document (base64 encoded) to be uploaded.
An object composed of the following attributes must be sent as JSON:
- content: Base64 encoded content.
- filename: Name that the uploaded document will have along with the extension (e.g. filename.pdf).
'
required: false
schema:
type: object
$ref: '#/definitions/EmployeeFileBase64'
- name: visible
in: query
type: boolean
enum:
- true
- false
description: 'Visible to the employee. Default: false'
- name: signable_by_employee
in: query
type: boolean
enum:
- true
- false
description: 'Requires employee signature. Default: false'
- name: signable_by_legal_agent
in: query
type: boolean
enum:
- true
- false
description: 'Requires the signature of the legal representative. Default: false'
- name: signable_by_second_legal_agent
in: query
type: boolean
enum:
- true
- false
description: 'Requires the signature of a second legal representative. Default: false'
- name: overwrite
in: query
type: boolean
enum:
- true
- false
description: 'Overwrite file. Applies only to documents that do not have all required signatures. Default: false'
- name: start_signature_workflow
in: query
type: boolean
enum:
- true
- false
description: 'Start automatic signature flow The document must be visible and must have signature or review requirements to select this option. Default: false'
- name: path
in: query
description: 'Path where the file will be saved. If left blank it will be created in the employee''s root folder. Example: personal/security'
required: false
type: string
- name: signatures
in: query
description: Array of objects of signature type. It is an optional parameter. If this parameter is used, the other parameters related to the signature will not be taken into account.
required: false
schema:
type: array
items:
$ref: '#/definitions/DocumentSignature'
- name: reviewer_id
in: query
description: Person's ID of the reviewer. This is an optional parameter, if you do not want to assign a reviewer, leave this field empty
required: false
type: integer
consumes:
- multipart/form-data
responses:
'201':
description: API response after creating documents.
schema:
properties:
employee_id:
type: integer
employee_file:
$ref: '#/definitions/EmployeeFileDetail'
'400':
description: There is an error with the data submitted
schema:
$ref: '#/definitions/bad_request'
get:
summary: Obtain employee documents
description: "Information is obtained from the employee's documents according to the date filters entered\n\n**Permisos requeridos para utilizar este endpoint:** \n* Permissions to View and download employee documents en: 'Sí'.\n"
tags:
- Colaboradores
parameters:
- name: id
in: path
type: integer
required: true
description: ID of the employee to be queried.
- name: from
in: query
type: string
format: date
description: 'From - Date range of document creation. Example: 2020/12/10'
- name: to
in: query
type: string
format: date
description: To - Date range of document creation. Example 2020/12/11
responses:
'200':
description: As a response, we receive an array with the employee's documents
schema:
type: array
items:
$ref: '#/definitions/EmployeeFileListDetail'
/employees/{id}/docs/{file_id}:
get:
summary: Obtains an employee document
description: "The possible file IDs are in the GET `/employees/{id}/docs` endpoint.\n\nThe redirection for the entered document of file_id is returned, hence it must be followed.\n\n* To follow the redirection, add the ‘-L’ option.\n* To save the response in a file, add the ‘-o’ option and pass the file name.\n\n**Example**\n````curl -L -X GET --header 'Accept: */*' --header 'auth_token: [AUTH TOKEN]' 'http://www.[COMPANY SUBDOMAIN].buk.cl/api/v1/employees/1/docs/1156' -o [FILE NAME]````\n\nTest with ‘curl’, the Try It button does not work for documents.\n\n\n**Permisos requeridos para utilizar este endpoint:** \n* Permissions to View and download employee documents en: 'Sí'.\n"
tags:
- Colaboradores
parameters:
- name: id
in: path
description: Employee ID
required: true
type: string
- name: file_id
in: path
description: Document ID
required: true
type: string
responses:
'200':
description: As a response, we received an employee document
schema:
$ref: '#/definitions/EmployeeFileDetail'
/docs/{id}:
get:
tags:
- Colaboradores
summary: Obtain document detailed information
description: "Receives the ID of a document and provides the specifications associated with that document.\n**Permisos requeridos para utilizar este endpoint:** \n* Permissions to View and download employee documents en: 'Sí'.\n"
parameters:
- name: id
in: path
description: Document ID
type: integer
required: true
responses:
'200':
description: As a response, we received an employee document
schema:
properties:
employee_id:
type: integer
employee_file:
$ref: '#/definitions/EmployeeFileDetail'
/employees/{id}/vacation_definitions:
get:
summary: List vacation policies associated with the employee.
description: "Displays an array with vacation policies associated with an employee\n\n**Permisos requeridos para utilizar este endpoint:** \n* Employee permissions en: 'Lectura'.\n* Vacation permissions en: 'Lectura'.\n"
tags:
- Colaboradores
parameters:
- name: id
description: Employee ID
in: path
type: integer
required: true
responses:
'200':
description: As a response, we receive a list of vacation policies associated with the employee.
schema:
$ref: '#/definitions/VacationDefinitionOutput'
'400':
description: There is an error with the data submitted
schema:
$ref: '#/definitions/bad_request'
post:
summary: Add a vacation policy to the employees
description: "Assign a vacation policy to employees. The parameters are:\n- employee_id : (REQUIRED) ID of the employee\n- body : (REQUIRED) JSON with the code of the vacation policy to assign.\n\n**Permisos requeridos para utilizar este endpoint:** \n* Employee permissions en: 'Lectura y Modificación'.\n* Vacation permissions en: 'Lectura y Modificación'.\n"
tags:
- Colaboradores
parameters:
- name: id
description:
# --- truncated at 32 KB (88 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/buk/refs/heads/main/openapi/buk-colaboradores-api-openapi.yml