Buk Documents API

openapi: 3.2.0
info:
  description: '# Buk Data Access API.


    To use the API, you need to obtain an **API Key**.

    You can manage access within the platform, in **Settings => API Access.**


    Once an API Key is created, you must send the value as a header in the HTTP request, in the `auth_token` field.


    ## For more details, you can review the article "How to integrate with Buk through an API"


    # Endpoints'
  title: Buk Documents API
servers:
- url: https://demo.buk.cl/api/v1/brasil
tags:
- name: Documents
paths:
  /employees/{id}/docs:
    post:
      summary: Add a document to employee
      description: 'We receive a document, which will be related to the employee.


        **Permisos requeridos para utilizar este endpoint:**

        * Permissions to upload documents en: ''Sí''.'
      tags:
      - Documents
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the employee to be queried.
        schema:
          type: integer
      - name: visible
        in: query
        description: 'Visible to the employee. Default: false'
        schema:
          type: boolean
          enum:
          - true
          - false
      - name: signable_by_employee
        in: query
        description: 'Requires employee signature. Default: false'
        schema:
          type: boolean
          enum:
          - true
          - false
      - name: signable_by_legal_agent
        in: query
        description: 'Requires the signature of the legal representative. Default: false'
        schema:
          type: boolean
          enum:
          - true
          - false
      - name: signable_by_second_legal_agent
        in: query
        description: 'Requires the signature of a second legal representative. Default: false'
        schema:
          type: boolean
          enum:
          - true
          - false
      - name: overwrite
        in: query
        description: 'Overwrite file. Applies only to documents that do not have all required signatures. Default: false'
        schema:
          type: boolean
          enum:
          - true
          - false
      - name: start_signature_workflow
        in: query
        description: 'Start automatic signature flow The document must be visible and must have signature or review requirements to select this option. Default: false'
        schema:
          type: boolean
          enum:
          - true
          - 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
        schema:
          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: '#/components/schemas/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
        schema:
          type: integer
      responses:
        '201':
          description: API response after creating documents.
          content:
            application/json:
              schema:
                properties:
                  employee_id:
                    type: integer
                  employee_file:
                    $ref: '#/components/schemas/EmployeeFileDetail'
            application/pdf:
              schema:
                properties:
                  employee_id:
                    type: integer
                  employee_file:
                    $ref: '#/components/schemas/EmployeeFileDetail'
        '400':
          description: There is an error with the data submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request'
            application/pdf:
              schema:
                $ref: '#/components/schemas/bad_request'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  description: Document to be uploaded.
                  format: binary
                file_base64:
                  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).

                    '
      operationId: postEmployeesByIdDocs
      x-operation-id-source: derived
    get:
      summary: Obtain employee documents
      description: 'Information is obtained from the employee''s documents according to the date filters entered


        **Permisos requeridos para utilizar este endpoint:**

        * Permissions to View and download employee documents en: ''Sí''.'
      tags:
      - Documents
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the employee to be queried.
        schema:
          type: integer
      - name: from
        in: query
        description: 'From - Date range of document creation. Example: 2020/12/10'
        schema:
          type: string
          format: date
      - name: to
        in: query
        description: To - Date range of document creation. Example 2020/12/11
        schema:
          type: string
          format: date
      responses:
        '200':
          description: As a response, we receive an array with the employee's documents
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EmployeeFileListDetail'
            application/pdf:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EmployeeFileListDetail'
      operationId: getEmployeesByIdDocs
      x-operation-id-source: derived
  /employees/{id}/docs/{file_id}:
    get:
      summary: Obtains an employee document
      description: 'The possible file IDs are in the GET `/employees/{id}/docs` endpoint.


        The redirection for the entered document of file_id is returned, hence it must be followed.


        * To follow the redirection, add the ‘-L’ option.

        * To save the response in a file, add the ‘-o’ option and pass the file name.


        **Example**

        ````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]````


        Test with ‘curl’, the Try It button does not work for documents.


        **Permisos requeridos para utilizar este endpoint:**

        * Permissions to View and download employee documents en: ''Sí''.'
      tags:
      - Documents
      parameters:
      - name: id
        in: path
        description: Employee ID
        required: true
        schema:
          type: string
      - name: file_id
        in: path
        description: Document ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: As a response, we received an employee document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeFileDetail'
            application/pdf:
              schema:
                $ref: '#/components/schemas/EmployeeFileDetail'
      operationId: getEmployeesByIdDocsByFileId
      x-operation-id-source: derived
  /docs/{id}:
    get:
      tags:
      - Documents
      summary: Obtain document detailed information
      description: 'Receives the ID of a document and provides the specifications associated with that document.

        **Permisos requeridos para utilizar este endpoint:**

        * Permissions to View and download employee documents en: ''Sí''.'
      parameters:
      - name: id
        in: path
        description: Document ID
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: As a response, we received an employee document
          content:
            application/json:
              schema:
                properties:
                  employee_id:
                    type: integer
                  employee_file:
                    $ref: '#/components/schemas/EmployeeFileDetail'
            application/pdf:
              schema:
                properties:
                  employee_id:
                    type: integer
                  employee_file:
                    $ref: '#/components/schemas/EmployeeFileDetail'
      operationId: getDocsById
      x-operation-id-source: derived
  /docs/{id}/signatures/process:
    post:
      summary: Start document signature workflow
      tags:
      - Documents
      description: 'We receive a document ID, and the signature process begins. If the document had already started the signature process, an error with status 409 is displayed.


        **Permisos requeridos para utilizar este endpoint:**

        * Permissions to upload documents en: ''Sí''.'
      parameters:
      - name: id
        in: path
        description: Document ID
        required: true
        schema:
          type: integer
      responses: {}
      operationId: postDocsByIdSignaturesProcess
      x-operation-id-source: derived
  /docs/{id}/signatures:
    put:
      summary: Add signers to a document
      description: 'We receive the signatures or reviewer to be assigned. Changes will only be made to parameters that are submitted.

        - In the case of signatures:


        We receive the type of signature to assign, this can be a string from the following list:

        - employee_signature

        - legal_agent_signature

        - second_legal_agent_signature

        - supervisor_signature

        - other_signature

        - second_other_signature


        Along with a valid person id with a user. In case of choosing the type of signature legal_agent_signature

        or second_legal_agent_signature, the person ID must be of a legal representative configured. If choosing the type of signature employee_signature or supervisor_signature, it''s not necessary to add the person ID.


        If you want to add an order to the signatures, you should add the attribute "position" within each signature. Where you must indicate the order of the signatures to assign with numerical values from 1 up to the number of signatures, these values cannot be repeated. If you do not want an order for the signatures, do not send the "position" attribute.


        To remove the signatures from a document, you must send an empty list.


        - In the case of the reviewer:


        We receive the person ID of the reviewer. To be valid, it must have an active user and at least one active job. To remove a reviewer, you must send null in the field.


        **Permisos requeridos para utilizar este endpoint:**

        * Permissions to View and download employee documents en: ''Sí''.


        If you are reassigning a signer to a document generated from a template, the template will not be modified. The reassignment will apply only to the selected document and it will be reloaded with the current content of the template.'
      tags:
      - Documents
      parameters:
      - name: id
        in: path
        description: Document ID
        required: true
        schema:
          type: integer
      responses:
        '201':
          description: As a response we received the information of the signatures and the document reviewer.
          content:
            application/json:
              schema:
                properties:
                  employee_file_id:
                    $ref: '#/components/schemas/Signature'
            application/pdf:
              schema:
                properties:
                  employee_file_id:
                    $ref: '#/components/schemas/Signature'
        '400':
          description: There is an error with the data submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request'
            application/pdf:
              schema:
                $ref: '#/components/schemas/bad_request'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Signature'
        description: Signature specification object
        required: true
      operationId: putDocsByIdSignatures
      x-operation-id-source: derived
components:
  schemas:
    EmployeeFileListDetail:
      properties:
        file_id:
          type: integer
        filename:
          type: string
        path:
          type: string
        created_at:
          type: string
    DocumentSignature:
      properties:
        signature_type:
          type: string
        person_id:
          type: number
        position:
          type: number
        status:
          type: string
        signed_at:
          type: string
        confirmation_code_channel:
          type: string
        created_at:
          type: string
    Signature:
      properties:
        signatures:
          type: array
          items:
            properties:
              signature_type:
                type: string
              person_id:
                type: integer
              position:
                type: integer
        reviewer_id:
          type: integer
    bad_request:
      properties:
        errors:
          type: array
          items:
            type: string
    EmployeeFileDetail:
      properties:
        id:
          type: integer
        employee_folder_id:
          type: integer
        document_template_id:
          type: integer
        original_filename:
          type: string
        is_visible:
          type: boolean
        settings:
          type: object
          properties:
            pdf_orientation:
              type: string
            employee_sign:
              type: boolean
            legal_agent_sign:
              type: boolean
            second_legal_agent_sign:
              type: boolean
            is_external:
              type: boolean
        signatures:
          type: array
          items:
            $ref: '#/components/schemas/DocumentSignature'
        reviewer_id:
          type: integer
  securitySchemes:
    auth_token:
      type: apiKey
      name: auth_token
      in: header