Залишки відпусток (Employee Absences)¶

Залишки відпусток - це механізм управління балансом доступних і використаних днів відпустки для співробітників. Кожен запис про залишки прив'язаний до конкретного типу відпустки (щорічна, навчальна, тощо) та періоду (робочий рік або календарний рік).

Різниця між Залишками (Absences) та Задачами "Відпустка" (Vacation Tasks)¶

Важливо розуміти різницю між цими двома концепціями:

Приклад взаємодії¶

1. Створюється запис про залишки: співробітнику надається 24 дні щорічної відпустки на робочий рік

   {
     "absence_type": "annual",
     "allowed_days": 24,
     "left_days": 24,
     "date_start": "2024-01-15"
   }
   

2. Створюється задача "Відпустка": співробітник йде у відпустку на 10 днів

3. Система автоматично зменшує left_days з 24 до 14

4. used_days збільшується з 0 до 10

5. Оновлення залишків: HR може вручну скоригувати баланс через PATCH ендпоінт, наприклад, якщо була помилка або додано додаткові дні

Типи відпусток (Absence Types)¶

Кожен запис про залишки прив'язаний до одного з наступних типів:

Типи періодів¶

Робочий рік (Working Year)¶

• Відлік починається з дати прийому на роботу (date_joined)
• Наприклад, якщо співробітник прийнятий 15 січня 2024, робочий рік: 15.01.2024 - 14.01.2025
• Використовується для щорічних основних та додаткових відпусток

Календарний рік (Calendar Year)¶

• Відлік з 1 січня по 31 грудня
• Використовується для соціальних, навчальних та неоплачуваних відпусток

Поля запису про залишки¶

Обчислення used_days¶

used_days = allowed_days - left_days

Наприклад: - allowed_days: 24 (надано 24 дні) - left_days: 14 (залишилося 14 днів) - used_days: 10 (використано 10 днів)

API ендпоінти¶

1. Створити запис про залишки відпустки¶

POST /api/public/v1/employee/{employee_id}/absences

Створює новий запис про залишки відпустки для співробітника.

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

{
  "absence_type": "annual",
  "date_start": "2024-01-15",
  "allowed_days": 24,
  "left_days": 24
}

Приклад для користувацького типу:

{
  "absence_type": "custom",
  "date_start": "2024-01-01",
  "allowed_days": 10,
  "left_days": 10,
  "task_template_identifier": "123e4567-e89b-12d3-a456-426614174000"
}

Важливо: - Для типу custom обов'язково вказувати task_template_identifier - date_start визначає початок періоду і залежить від типу відпустки - allowed_days та left_days можуть бути дробовими числами (наприклад, 24.5)

2. Отримати список залишків відпусток¶

GET /api/public/v1/employee/{employee_id}/absences

Повертає список всіх записів про залишки відпусток для співробітника з обчисленням used_days.

Приклад відповіді:

{
  "detail": {
    "items": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "employee_id": "987e6543-e21b-12d3-a456-426614174001",
        "absence_type": "annual",
        "date_start": "2024-01-15",
        "allowed_days": 24,
        "left_days": 14,
        "used_days": 10
      },
      {
        "id": "456e7890-e12b-34c5-d678-426614174003",
        "employee_id": "987e6543-e21b-12d3-a456-426614174001",
        "absence_type": "vacation_social_pco",
        "date_start": "2024-01-01",
        "allowed_days": 14,
        "left_days": 14,
        "used_days": 0
      }
    ],
    "total": 2,
    "page_num": 1,
    "page_size": 100
  }
}

3. Оновити залишки відпустки¶

PATCH /api/public/v1/employee/{employee_id}/absences/{absence_id}

Оновлює кількість доступних днів відпустки. Використовується для коригування балансу, наприклад, при помилці або нарахуванні додаткових днів.

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

{
  "allowed_days": 26,
  "left_days": 16
}

Це збільшить баланс на 2 дні (було 24, стало 26).

Сценарії використання¶

Сценарій 1: Створення залишків при прийомі на роботу¶

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

1. Щорічна основна відпустка (24 дні):

   POST /api/public/v1/employee/{employee_id}/absences
   {
     "absence_type": "annual",
     "date_start": "2024-01-15",  // Дата прийому на роботу
     "allowed_days": 24,
     "left_days": 24
   }
   

2. Додаткова відпустка для учасника бойових дій (14 днів), якщо застосовується:

   POST /api/public/v1/employee/{employee_id}/absences
   {
     "absence_type": "vacation_social_pco",
     "date_start": "2024-01-01",  // Початок календарного року
     "allowed_days": 14,
     "left_days": 14
   }
   

Сценарій 2: Оформлення відпустки через задачу¶

1. Перевірити залишки перед створенням задачі:

   GET /api/public/v1/employee/{employee_id}/absences
   

   Переконатися, що left_days >= кількість днів відпустки

2. Створити задачу "Відпустка":

   POST /api/public/v1/vacation
   

   Система автоматично зменшить left_days та збільшить used_days

3. Перевірити оновлені залишки:

   GET /api/public/v1/employee/{employee_id}/absences
   

Сценарій 3: Коригування балансу¶

Якщо потрібно додати або зменшити кількість днів (наприклад, помилка або нарахування додаткових днів):

PATCH /api/public/v1/employee/{employee_id}/absences/{absence_id}
{
  "allowed_days": 28,  // Було 24, додаємо 4 дні
  "left_days": 18      // Було 14, додаємо 4 дні
}

Сценарій 4: Новий період (новий рік)¶

На початку нового періоду (робочого або календарного року) потрібно створити новий запис:

POST /api/public/v1/employee/{employee_id}/absences
{
  "absence_type": "annual",
  "date_start": "2025-01-15",  // Початок нового робочого року
  "allowed_days": 24,
  "left_days": 24
}

Старий запис залишається в системі для історії.

Важливі моменти¶

1. Автоматичне списання - при створенні задачі "Відпустка" система автоматично зменшує left_days у відповідному записі залишків. Ручне оновлення через PATCH не потрібне.

2. Дробові дні - кількість днів може бути дробовою (наприклад, 24.5), що дозволяє враховувати неповні дні відпустки.

3. Декілька періодів - один співробітник може мати декілька записів одного типу для різних періодів (наприклад, щорічна відпустка за 2024 та 2025 роки).

4. Валідація при створенні відпустки - система перевіряє наявність достатніх залишків перед створенням задачі "Відпустка". Якщо left_days менше за запитувану кількість днів, задача не буде створена.

5. Користувацькі типи - для типу custom обов'язково вказувати task_template_identifier, який відповідає ID шаблону відпустки, створеного через веб-інтерфейс.

6. Історія використання - старі записи не видаляються, що дозволяє переглядати історію використання відпусток за минулі періоди.

7. Зв'язок з шаблонами відпусток - тип залишків (absence_type) повинен відповідати типу шаблону відпустки. Див. документацію про відпустки для повної таблиці відповідностей.

Помилки та їх вирішення¶