Отпуска (Time-off)

Группа методов /api/v1/time-off позволяет читать конфигурацию политик отпусков организации, историю начислений и списаний по каждому сотруднику, а также его актуальный баланс на любую дату.

Получить список категорий отпусков

GET /api/v1/time-off/categories

Возвращает все политики/категории отпусков организации.

Поля ответа (каждая категория):

Поле	Тип	Описание
id	integer	ID категории
title	string	Название
description	string	Описание
category_type	string	Тип: manual, accrues_time, flexible
paid_type	string	Оплачиваемость
period_track_type	string	Единица учёта: часы или дни
emoji	string	Эмодзи
color	string	Цвет
policies_count	integer	Количество привязанных политик
is_archived	boolean	Архивирована ли категория
is_parental_leave	boolean	Является ли декретным отпуском

Пример ответа:

[
  {
    "id": 3,
    "title": "Ежегодный оплачиваемый",
    "category_type": "accrues_time",
    "paid_type": "paid",
    "period_track_type": "days",
    "policies_count": 2,
    "is_archived": false,
    "is_parental_leave": false
  }
]

---

История отпусков сотрудника

POST /api/v1/time-off/logs/search

Возвращает страницу записей об отпусках - начисления, списания, истечения срока и корректировки.

Параметры запроса:

Поле	Тип	Описание
employee_id	integer	ID сотрудника (обязательно)
page_number	integer	Номер страницы
category_ids	array[integer]	Фильтр по категориям отпусков
action_types	array[string]	Типы: accrual, used, expired, adjustment
request_statuses	array[string]	Статусы заявок

Поля ответа (каждая запись):

Каждая запись содержит два объекта: time_off_log и, при наличии заявки, approval_request_details.

time_off_log:

Поле	Тип	Описание
id	integer	ID записи
date_adjustment	string (date)	Дата корректировки
employee_id	integer	ID сотрудника
category	object	Категория отпуска
balance	string	Изменение баланса
action	string	Тип действия
balance_type	string	Тип баланса
date_from	string	Начало периода отпуска
date_to	string	Конец периода отпуска
date_expire	string	Дата истечения начисления
comment	string	Комментарий
files	array	Прикреплённые файлы

approval_request_details (если есть заявка):

Поле	Тип	Описание
id	integer	ID заявки
type	string	Тип заявки
status	string	Статус заявки
confirmations	array	Список подтверждений
datetime_created_at	string	Дата создания

Пример запроса:

{
  "employee_id": 123,
  "page_number": 1,
  "action_types": ["used", "accrual"],
  "category_ids": [3, 5]
}

---

Баланс отпусков сотрудника на дату

POST /api/v1/time-off/employee/balance

Возвращает баланс по всем категориям отпусков, к которым подключён сотрудник, на указанную дату.

Параметры запроса:

Поле	Тип	Описание
employee_id	integer	ID сотрудника (обязательно)
date_balance	string (date)	Дата, на которую запрашивается баланс (обязательно)

Поля ответа (каждая категория):

Поле	Тип	Описание
id	integer	ID категории
title	string	Название категории
category_type	string	Тип категории
period_track_type	string	Единица учёта
balance.available_balance	string	Доступный баланс
balance.total_booked_amount	string	Забронировано (одобренные заявки)
is_archived	boolean	Архивирована ли категория

Пример запроса:

{
  "employee_id": 123,
  "date_balance": "2024-06-30"
}

Пример ответа:

[
  {
    "id": 3,
    "title": "Ежегодный оплачиваемый",
    "category_type": "accrues_time",
    "period_track_type": "days",
    "balance": {
      "available_balance": "12.5",
      "total_booked_amount": "3.0"
    },
    "is_archived": false
  }
]

---

Типичный сценарий интеграции

Задача: периодически синхронизировать данные об отпусках с payroll-системой.

1. Получить категории (один раз, кешировать):

   GET /api/v1/time-off/categories

2. Выгрузить историю за период по каждому сотруднику:

   POST /api/v1/time-off/logs/search

   С фильтром по action_types: ["used", "accrual"] и нужными category_ids.

3. Получить актуальный баланс на конец расчётного периода:

   POST /api/v1/time-off/employee/balance

   С параметром date_balance - датой среза.

Совет: используйте date_adjustment из time_off_log для инкрементальной синхронизации - запрашивайте только записи с датой корректировки позднее последней успешной синхронизации.