Відпустка (vacation)¶

Відпустка - це задача, яка дозволяє співробітнику отримати відпустку на певний період часу. Вона створюється на основі шаблону відпустки, який визначає тип відпустки, тривалість та інші параметри.

Налаштування доступних типів відпусток, а також стандартних підписантів і набір документів для підпису доступний лише через веб-інтерфейс Вчасно.Кадри. API дозволяє лише створювати задачі на основі вже налаштованих шаблонів відпусток.

Як налаштувати шаблони відпусток?.

Доступні шаблони відпусток можна отримати через ендпоінт https://kadry.vchasno.ua/api/public/v1/vacation/template. Далі можна створити задачу "Відпустка" на основі обраного шаблону через ендпоінт https://kadry.vchasno.ua/api/public/v1/vacation. Обов'язково необхідно передати: template_version_identifier (ID версії шаблону відпустки), initiator_id (ID співробітника, для якого створюється задача), а також date_start і date_end (дати початку та кінця відпустки). Опціональним полем є external_id, яке може бути використано для ідентифікації задачі в зовнішніх системах.

Приклад запиту:

{
  "initiator_id": "987e6543-e21b-12d3-a456-426614174001",
  "template_version_identifier": "123e4567-e89b-12d3-a456-426614174000",
  "date_start": "2024-07-01",
  "date_end": "2024-07-10",
  "external_id": "ext-123"
}

Після створення задачі "Відпустка", автоматично створяться документи для підпису, які можна переглянути через ендпоінт https://kadry.vchasno.ua/api/public/v1/vacation/{task_id}/document. На даному етапі ці документи ще не були надіслані на підпис, і їх можна редагувати, наприклад, змінювати підписантів або змінювати файл документу.

Зміна файлу на підпис¶

При надсиланні документів на підпис, система атоматично згенерує файл заяви та наказу на основі шаблонів і підписантів. Це можна змінити, завантаживши свій файл до надсилання на підпис через ендпоінт https://kadry.vchasno.ua/api/public/v1/vacation/{task_id}/document/{document_id}/upload.

Зміна підписантів¶

До моменту надсилання документів, можна додати або видалити підписантів через ендпоінт https://kadry.vchasno.ua/api/public/v1/vacation/{task_id}/document/{document_id}/signer. Ці ендаоінти оперують ID співробітників, і приймають тільки співробітників, які мають статус working.

Надсилання документів на підпис¶

В рамках задачі "Відпустка" можна надіслати до двох документів: Заяву та/або Наказ. Якщо присутні обидва документи, то їх можна надіслати на підпис одночасно, або окремо. Для цього використовується ендпоінт https://kadry.vchasno.ua/api/public/v1/vacation/{task_id}/send-documents. Тіло запиту містить поле documents_to_send — масив документів для надсилання. Кожен елемент масиву ідентифікує документ через document_id і містить його власні параметри. При послідовному надсиланні, спочатку надсилається Заява, і тільки після повного підписання, є можливість надіслати Наказ. При надсиланні Наказу, у відповідному елементі documents_to_send необхідно передати номер наказу (order_number), а також періоди, за які надається відпустка (periods). Ці поля задаються на рівні окремого документа, а не на верхньому рівні запиту.

Приклад запиту:

{
  "documents_to_send": [
    {
      "document_id": "456e7890-e12b-34c5-d678-426614174003",
      "order_number": "12-В",
      "periods": {
        "dates": [
          {
            "start_date": "2024-07-01",
            "end_date": "2024-07-10"
          }
        ]
      }
    }
  ]
}

Очікувана послідовність дій для задачі "Відпустка"¶

1. Отримати доступні шаблони відпусток

2. Створити задачу "Відпустка", передавши ID шаблону та ID співробітника

3. Отримати документи для підпису

4. При необхідності, змінити файл документу

5. Додати або видалити підписантів

6. Надіслати документи на підпис, передавши необхідні параметри для Наказу, якщо він є

Додаткові операції¶

Робота з шаблонами відпусток¶

Створити новий шаблон відпустки або оновити наявний за ідентифікатором версії шаблону:

Отримання задач¶

Отримати список усіх відпусток компанії (з фільтрацією) або одну задачу за task_id:

Оновлення задачі¶

Оновити дані або статус задачі «Відпустка» через PATCH /api/public/v1/vacation/{task_id}:

Скасування задачі¶

Скасувати задачу «Відпустка» за task_id. Обов'язкове поле cancellation_reason:

Робота з документами¶

Створити додатковий документ, оновити статус документа або видалити документ у межах задачі:

Скачати підписаний документ (рекомендовано лише для документів у статусі completed):

Маршрути задачі¶

Отримати список маршрутів задачі з інформацією про виконавців та статуси:

Підписанти документа¶

Отримати список підписантів документа та їхній статус:

За потреби перевизначити список підписантів (видаляє старих і додає нових) або видалити окремого підписанта:

Надіслати нагадування підписанту документа:

Маршрути погодження¶

Отримати маршрути погодження задачі та перевизначити список погоджувачів:

Вкладення задачі¶

Отримати список додатків (вкладень) задачі:

Типи відпусток¶