Залишки відпусток (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 збільшується з 0 до 10 (додається рядок списання в usages)

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

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

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

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

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

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

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

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

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

Збережений запис про залишки (Absence) містить наступні поля:

Поле date_start приймається лише як вхідний параметр при створенні запису (POST) і визначає початок періоду; у збереженому записі дата зберігається в межах періоду.

Обчислювані поля при отриманні списку (GET)¶

При отриманні списку залишків (GET) кожен запис додатково містить обчислювані поля:

Наприклад, для запису з allowed_days = 24, за яким списано 7 днів (5 за задачею + 2 ручним коригуванням):

• used: 7 (сума usages)
• left_days_for_period: 17 (24 - 7)
• left_days: значення збереженого балансу (окреме, залежить від автоматичних списань за задачами)

Поле used як вхідний параметр (POST / PATCH)¶

Окрім обчислення на GET, used можна задати вручну в запитах POST і PATCH. Передане значення трактується як абсолютна кількість використаних за період днів (а не приріст): бекенд обчислює різницю відносно поточного used і записує коригування в історію (usages + подія балансу). Це коригування не впливає на left_days. null або відсутнє поле означає «не змінювати used».

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"
}

Приклад із зазначенням використаних днів (used):

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

Створює запис і одразу фіксує 5 використаних за період днів (додається рядок ручного коригування в usages). Поле used не впливає на left_days.

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

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

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

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

Відповідь має вкладену структуру: кожен елемент списку — це робочий період (FullWorkingPeriodAbsence) з полями id, employee_id, date_start, date_end та масивом absences. Кожен запис у масиві absences містить деталі залишків за цим типом відпустки разом з обчислюваними полями (used, accrued, left_days_for_period, usages).

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

{
  "detail": {
    "items": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "employee_id": "987e6543-e21b-12d3-a456-426614174001",
        "date_start": "2024-01-15",
        "date_end": "2025-01-14",
        "absences": [
          {
            "id": "456e7890-e12b-34c5-d678-426614174003",
            "period_id": "123e4567-e89b-12d3-a456-426614174000",
            "absence_type": "annual",
            "task_template_identifier": null,
            "allowed_days": 24,
            "left_days": 14,
            "monthly_changes": [],
            "task_template": null,
            "used": 10,
            "accrued": null,
            "left_days_for_period": 14,
            "usages": [
              {
                "id": "aaa11111-2222-3333-4444-555566667777",
                "absence_id": "456e7890-e12b-34c5-d678-426614174003",
                "task_id": "789e0123-e45b-67c8-d901-426614174005",
                "used_days": 10,
                "is_manual_adjustment": false
              }
            ]
          }
        ]
      }
    ],
    "page_num": 1,
    "page_size": 100,
    "has_prev": false,
    "has_next": false,
    "total_items": 1,
    "total_pages": 1
  }
}

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

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

Оновлює кількість доступних (allowed_days, left_days) та/або використаних (used) днів відпустки. Використовується для коригування балансу, наприклад, при помилці або нарахуванні додаткових днів. Передаються лише ті поля, які потрібно змінити — відсутні поля залишаються без змін.

Приклад запиту (коригування наданих днів):

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

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

Приклад запиту (коригування використаних днів):

{
  "used": 5
}

Встановлює абсолютну кількість використаних за період днів у 5. Бекенд обчислює різницю відносно поточного used і записує коригування в історію (usages). Це поле не змінює left_days — використані та залишкові дні керуються незалежно.

Поля запиту:

4. Масово створити або оновити залишки¶

POST /api/public/v1/absences/bulk

Синхронний пакетний запит для інтеграцій, які регулярно (наприклад, щоночі) передають повний стан залишків по всіх співробітниках. Один запит приймає до 200 рядків; кожен рядок — це повний бажаний стан одного запису про залишки для одного співробітника за один період. Результат по кожному рядку повертається одразу в тілі відповіді — без черги, без полінгу.

Природний ключ рядка. Записи ідентифікуються не внутрішнім id, а комбінацією

employee_id + date_start + absence_type + task_template_identifier

Якщо запису з таким ключем ще немає — його буде створено (created); якщо є — оновлено (updated). Зберігати absence_id на боці інтегратора не потрібно. Повторне надсилання того самого стану нічого не змінює і не породжує записів в історії (skipped).

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

{
  "items": [
    {
      "employee_id": "0b1f2c3d-4e5f-6789-abcd-ef0123456789",
      "absence_type": "annual",
      "date_start": "2026-03-10",
      "allowed_days": 24,
      "left_days": 18.5,
      "used": 5.5,
      "apply_from": "2026-08-01",
      "row_ref": "erp-2026-1001"
    },
    {
      "employee_id": "0b1f2c3d-4e5f-6789-abcd-ef0123456789",
      "absence_type": "custom",
      "date_start": "2026-01-01",
      "task_template_identifier": "123e4567-e89b-12d3-a456-426614174000",
      "allowed_days": 10,
      "left_days": 10,
      "row_ref": "erp-2026-1002"
    }
  ]
}

Поля рядка:

Семантика полів така ж, як у поодиноких POST / PATCH. Пропущені поля не змінюються: рядок лише з used не занулить allowed_days і left_days у наявному записі.

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

{
  "detail": {
    "summary": {"total": 3, "created": 1, "updated": 1, "skipped": 0, "failed": 1},
    "items": [
      {
        "index": 0,
        "row_ref": "erp-2026-1001",
        "status": "updated",
        "absence_id": "a9c1b2d3-1111-2222-3333-444455556666",
        "error_code": null,
        "error_message": null,
        "field": null
      },
      {
        "index": 1,
        "row_ref": "erp-2026-1002",
        "status": "created",
        "absence_id": "b7d2e3f4-1111-2222-3333-444455556666",
        "error_code": null,
        "error_message": null,
        "field": null
      },
      {
        "index": 2,
        "row_ref": "erp-2026-1003",
        "status": "error",
        "absence_id": null,
        "error_code": "employee_not_found",
        "error_message": "Employee 5e6f7a8b-... does not belong to this company.",
        "field": "employee_id"
      }
    ]
  }
}

Часткове застосування. Рядки обробляються незалежно: один невалідний рядок не скасовує решту. Валідні рядки записуються, невалідні повертаються зі status = "error". Повторно надсилати треба лише невдалі рядки — їх зручно зібрати за row_ref.

Коди помилок рівня рядка (закритий список, на нього можна писати автоматичну обробку):

Помилки рівня запиту (жоден рядок не застосовується):

Обмеження.

• До 200 рядків за запит. 10 000 записів — це 50 послідовних викликів; батч, у якому нічого не змінилося, обробляється за частки секунди, батч із записами — приблизно 1 с.
• Запит нічого не видаляє: запис, якого немає в payload, лишається в системі без змін. Щоб обнулити залишок, надішліть його явно (allowed_days: 0, left_days: 0).
• Захисту від паралельних запусків немає. used — абсолютне значення, дельта якого рахується відносно поточного стану, тож два одночасні запуски по тих самих записах можуть подвоїти коригування. Запускайте синхронізацію послідовно, одним процесом.

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

Сценарій 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

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 дні
}

Щоб вручну виправити кількість використаних за період днів (наприклад, синхронізувати з зовнішньою системою обліку), передайте used — абсолютне значення:

PATCH /api/public/v1/employee/{employee_id}/absences/{absence_id}
{
  "used": 5  // Встановити «використано за період» рівним 5 (не змінює left_days)
}

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

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

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

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

Сценарій 5: Регулярна синхронізація з обліковою системою¶

Облікова система (УВП) щоночі передає повний стан залишків по всіх співробітниках і типах відпусток:

для кожної пачки по 200 записів:
    POST /api/public/v1/absences/bulk       → результат по кожному рядку
    зібрати рядки зі status = "error" за row_ref
виправити дані на своєму боці й надіслати лише невдалі рядки повторно

Рядки, стан яких не змінився з минулої ночі, повертаються як skipped і не породжують записів в історії.

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

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

2. used та left_days незалежні - ручне коригування used (через POST/PATCH) записує запис у історію використання, але не змінює left_days. І навпаки — зміна left_days не змінює used. Автоматичне списання за задачею "Відпустка" оновлює обидва (додає рядок у usages і зменшує left_days).

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

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

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

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

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

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

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