Отпуска (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]	Статусы заявок
date_from	string (date)	Оставить только записи, пересекающиеся с периодом
date_to	string (date)	Оставить только записи, пересекающиеся с периодом

date_from и date_to независимы - можно передать только одну границу. Запись попадает в выдачу, если её собственный период пересекается с запрошенным, поэтому отпуск, начавшийся до date_from и закончившийся внутри периода, тоже вернётся. Если date_from позже date_to, метод отвечает 422.

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

Каждая запись содержит два объекта: 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],
  "date_from": "2026-01-01",
  "date_to": "2026-12-31"
}

---

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

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

---

Дни отпусков сотрудников

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

Возвращает конкретные даты, в которые сотрудники находятся в отпуске внутри запрошенного периода. Многодневные отпуска разворачиваются в отдельные дни и обрезаются по периоду, поэтому пересекать интервалы самостоятельно не нужно.

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

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

Поле	Тип	Описание
date_from	string (date)	Начало периода (обязательно)
date_to	string (date)	Конец периода (обязательно)
employee_ids	array[integer]	Фильтр по ID сотрудников
category_ids	array[integer]	Фильтр по категориям отпусков
department_ids	array[integer]	Фильтр по подразделениям
team_ids	array[integer]	Фильтр по командам
division_ids	array[integer]	Фильтр по дивизионам
location_ids	array[integer]	Фильтр по локациям

Период не должен превышать 366 дней, а date_from не может быть позже date_to - иначе метод отвечает 422.

Поля ответа (каждый сотрудник):

Поле	Тип	Описание
employee_id	integer	ID сотрудника
days	array	Дни отпусков сотрудника по возрастанию

days[]:

Поле	Тип	Описание
date	string (date)	Дата, в которую сотрудник в отпуске
time_off_category_id	integer	Категория этого отпуска - склеивается с GET /api/v1/time-off/categories
is_pending	boolean	true, пока заявка не согласована

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

{
  "date_from": "2026-05-01",
  "date_to": "2026-05-07",
  "department_ids": [5]
}

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

[
  {
    "employee_id": 123,
    "days": [
      { "date": "2026-05-04", "time_off_category_id": 3, "is_pending": false },
      { "date": "2026-05-05", "time_off_category_id": 3, "is_pending": false }
    ]
  }
]

Сотрудники без отпусков в периоде возвращаются с пустым массивом days - так отличается «свободен весь период» от «недоступен этому токену».

Внимание: is_pending: true означает, что отпуск оформлен, но ещё не согласован, и может быть отклонён. Считайте такие дни занятыми только если сценарий должен учитывать несогласованные заявки.

Требуется permission access_to_leave_timeline=edit. Сотрудники, к которым у токена нет доступа, не попадают в ответ и не вызывают ошибку - поэтому пустой список может означать, что сервисной учётке не хватает прав.

Фильтр category_ids сужает и состав сотрудников: те, у кого нет отпусков запрошенных категорий, из ответа выпадают полностью.

---

Праздничные календари

Праздничный календарь хранит праздники, перенесённые рабочие дни и компенсирующие выходные. Календарь сотрудника определяется по локации, департаменту и дивизиону текущей позиции. Все три метода требуют permission manage_holidays=edit.

Получить праздничные календари

GET /api/v1/calendar-holidays

Возвращает все календари компании: id, title и country (id, title или null).

Получить даты календарей за период

POST /api/v1/calendar-holidays/dates/search

Поле	Тип	Описание
date_from	string (date)	Начало периода включительно (обязательно)
date_to	string (date)	Конец периода включительно (обязательно)
calendar_holiday_ids	array[integer]	Календари; пустой или не переданный список - все календари

Период не больше 366 дней, date_from не позже date_to - иначе 422.

[
  {
    "id": 3051,
    "calendar_holiday_id": 4,
    "date": "2026-01-01",
    "title": "New Year's Day",
    "type": "non_working"
  }
]

type	Значение
non_working	Праздник, выходной день
working	Рабочий день, перенесённый на выходной
compensated	Выходной, перенесённый с праздника, выпавшего на выходной

Получить календарь каждого сотрудника

POST /api/v1/calendar-holidays/employees/search

Поле	Тип	Описание
employee_ids	array[integer]	Сотрудники; без списка - все сотрудники
page_number	integer	Номер страницы, с 1
page_size	integer	Размер страницы, 1-500, по умолчанию 20

В каждом элементе employee_id и calendar_holiday_id. calendar_holiday_id равен null, если к сотруднику не применяется ни один календарь.

Календарь берётся по текущей позиции и не исторический: после переезда прошлые даты считаются по новому календарю.

---

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

Задача: периодически синхронизировать данные об отпусках с 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 для инкрементальной синхронизации - запрашивайте только записи с датой корректировки позднее последней успешной синхронизации.

---

Сценарий: кто отсутствует на конкретную дату

Задача: построить календарь или расписание, которое знает, когда человек в отпуске.

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

   GET /api/v1/time-off/categories

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

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

   С периодом и, при необходимости, department_ids или employee_ids.

3. Проверить нужную дату в массиве days. Если даты там нет - отпуск на неё не оформлен.

4. Учесть праздники, если они нужны календарю: календарь каждого сотрудника - POST /api/v1/calendar-holidays/employees/search, его даты - POST /api/v1/calendar-holidays/dates/search. См. Праздничные календари.