Сотрудники

Группа методов /api/v1/employees позволяет выполнять полный цикл синхронизации сотрудников с внешними HR- и payroll-системами: создавать карточки, обновлять персональные данные, вести исторические таблицы трудоустройства, позиций и компенсаций, а также архивировать уволенных сотрудников.

Основные операции с сотрудником

Создать сотрудника

POST /api/v1/employees

Создаёт карточку нового сотрудника. Email не является обязательным при создании.

Обязательные поля:

Поле	Тип	Описание
first_name	string	Имя
last_name	string	Фамилия
date_effective_from	string (date)	Дата найма

Опциональные поля:

Поле	Описание
middle_name	Отчество
division_id	ID дивизиона
department_id	ID отдела
position_id	ID должности
position_level_id	ID грейда
location_id	ID локации
legal_entity_id	ID юридического лица
reporting_to_id	ID руководителя
employment_contract_id	ID типа договора
employment_type_id	ID типа трудоустройства
employment_work_pattern_id	ID графика работы
base_salary_gross	Зарплата gross
base_salary_net	Зарплата net
currency	Валюта (ISO 4217)
per_type	Период: hourly, weekly, monthly, yearly

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

{
  "first_name": "Иван",
  "last_name": "Петров",
  "date_effective_from": "2024-01-15",
  "department_id": 42,
  "position_id": 7,
  "base_salary_gross": "150000",
  "currency": "RUB",
  "per_type": "monthly"
}

---

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

GET /api/v1/employees/{employee_id}

Возвращает полную карточку сотрудника, включая текущую позицию, трудоустройство, компенсацию и кастомные поля (custom_fields).

---

Поиск сотрудников

POST /api/v1/employees/search

Возвращает страницу сотрудников. Фильтры: text, employee_ids, manager_ids, department_ids, division_ids, location_ids, job_profile_ids, job_role_ids, employment_type_ids, employment_contract_ids, employee_lifecycle_statuses и is_manager. Максимальный page_size - 500.

Связанные блоки по умолчанию не загружаются - каждый нужно перечислить в employee_fields, иначе соответствующее поле придёт пустым:

Значение	Заполняет	Что внутри
position_job_title, position_division, position_department, position_location, position_level, position_reporting_to, position_comment, position_change_reason	employee_position	Текущая позиция. Любое из значений поднимает весь блок
employment_employment_type, employment_employment_contract, employment_legal_entity, employment_work_pattern, employment_termination_reason	employee_employment	Текущее трудоустройство
compensation, compensation_change_reason	employee_compensation	Текущий оклад: base_salary_gross, base_salary_net, currency, per_type
lifecycle_status	lifecycle_status	Статус жизненного цикла
custom_fields	custom_fields	Кастомные поля со значениями и правами
time_off	time_off	Отпуск, в котором сотрудник находится сегодня - см. ниже
custom_tables	custom_tables	Строки кастомных таблиц - см. ниже
additional_compensations	additional_compensations	Выплаты текущего месяца - см. ниже

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

{
  "page_number": 1,
  "page_size": 100,
  "employee_fields": [
    "position_job_title",
    "position_department",
    "compensation",
    "custom_fields",
    "additional_compensations"
  ]
}

time_off

Заполняется, только если сотрудник в отпуске в день запроса - дата не параметризуется. У остальных приходит null.

{
  "date_from": "2024-03-04",
  "date_to": "2024-03-15",
  "category": { "id": 3, "title": "Ежегодный отпуск" },
  "balance_requested": "10.00"
}

Чтобы узнать, кто в отпуске за период, используйте POST /api/v1/time-off/availability/search.

custom_tables

По элементу на таблицу. У исторической таблицы приходит только актуальная строка; за всей историей обращайтесь к методам строк таблицы.

[{
  "table_id": 42,
  "rows": [{
    "id": 5,
    "date_effective_from": "2024-01-01",
    "is_current": true,
    "cells": [{ "field": { "slug": "bonus_amount" }, "value": { "value_float": 5000 } }]
  }]
}]

additional_compensations

Только выплаты, у которых date_effective_from попадает в текущий месяц (по UTC). За всю историю - GET /api/v1/employees/{employee_id}/additional-compensations.

[{
  "id": 1,
  "date_effective_from": "2024-03-01",
  "compensation_type": { "id": 7, "title": "Бонус" },
  "amount": "500.00",
  "amount_gross": "500.00",
  "amount_net": null,
  "currency": "USD",
  "description": "Бонус за Q1",
  "comment": null
}]

По сотрудникам, на которых у вызывающего нет права просмотра employee_additional_compensation, придёт пустой список.

---

Обновить персональные данные

PUT /api/v1/employees/{employee_id}

Обновляет персональные данные и кастомные поля сотрудника одним запросом.

Обязательные поля: first_name, last_name

Опциональные поля:

Поле	Описание
email	Рабочий email
email_personal	Личный email
phone	Рабочий телефон
phone_personal	Личный телефон
date_birth	Дата рождения
gender	Пол
personnel_number	Табельный номер
address_1, address_2, city, state, zip	Адрес
country_id	ID страны
custom_fields	dict: {slug: value} - значения кастомных полей сотрудника

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

{
  "first_name": "Иван",
  "last_name": "Петров",
  "email": "[email protected]",
  "personnel_number": "EMP-001",
  "custom_fields": {
    "snils": "123-456-789 00",
    "inn": "7712345678"
  }
}

---

Архивировать сотрудника

DELETE /api/v1/employees/{employee_id}

Переводит сотрудника в архив (увольнение). Это мягкое удаление - данные сохраняются.

---

История позиций

Позиция содержит информацию о подразделении, должности, руководителе и локации сотрудника на конкретную дату.

Добавить запись позиции

POST /api/v1/employees/{employee_id}/positions

Поле	Тип	Описание
date_effective_from	string (date)	Дата начала действия
division_id	integer	ID дивизиона
department_id	integer	ID отдела
position_id	integer	ID должности
position_level_id	integer	ID грейда
reporting_to_id	integer	ID руководителя
legal_entity_id	integer	ID юридического лица
location_id	integer	ID локации
comment	string	Комментарий

Обновить / удалить запись позиции

PUT  /api/v1/employees/{employee_id}/positions/{id}
DELETE /api/v1/employees/{employee_id}/positions/{id}

Поиск истории позиций

POST /api/v1/employees/{employee_id}/positions/search

Возвращает страницу записей позиций с полными объектами: department, division, position, manager, legal_entity, location. Поддерживает пагинацию.

---

История трудоустройств

Трудоустройство фиксирует тип договора, тип занятости, график работы и период работы.

Получить историю трудоустройств

GET /api/v1/employees/{employee_id}/employments

Возвращает полный список записей (текущую и прошлые).

Добавить запись трудоустройства

POST /api/v1/employees/{employee_id}/employments

Поле	Тип	Описание
date_effective_from	string (date)	Дата начала (дата найма)
date_effective_to	string (date)	Дата окончания / увольнения
employment_type_id	integer	ID типа трудоустройства
employment_contract_id	integer	ID типа договора
work_pattern_id	integer	ID графика работы
date_probation_ends	string (date)	Дата окончания испытательного срока
comment	string	Комментарий

Обновить / удалить запись трудоустройства

PUT    /api/v1/employees/{employee_id}/employments/{id}
DELETE /api/v1/employees/{employee_id}/employments/{id}

---

История компенсаций

Запись компенсации - версия пакета компенсации сотрудника, действующая с date_effective_from по date_effective_to (день перед началом следующей версии, null у действующей). В пакете лежат регулярные суммы: оклад, надбавки, удержания и взносы работодателя. Разовые выплаты - это дополнительные компенсации.

Добавить запись компенсации

POST /api/v1/employees/{employee_id}/compensations

Поле	Тип	Описание
date_effective_from	string (date)	Дата начала действия
base_salary_gross	number	Зарплата gross
base_salary_net	number	Зарплата net
currency	string	Валюта (ISO 4217)
per_type	string	hourly, weekly, monthly, yearly
change_reason_id	integer	ID причины изменения
comment	string	Комментарий

Метод записывает только оклад. Надбавки и другие строки пакета ведутся в Skailer.

Поиск истории компенсаций

POST /api/v1/employees/{employee_id}/compensations/search

Возвращает страницу версий пакета. В каждой версии есть lines - все регулярные суммы пакета:

{
  "id": 812,
  "date_effective_from": "2026-01-15",
  "date_effective_to": null,
  "base_salary_gross": "3000.00",
  "currency": "USD",
  "per_type": "monthly",
  "lines": [
    {
      "id": 1540,
      "compensation_type": { "id": 1, "title": "Basic salary", "is_archived": false },
      "amount_gross": "3000.00",
      "amount_net": null,
      "currency": "USD",
      "per_type": "monthly",
      "description": null,
      "kind": "earning",
      "is_included_in_gross": true,
      "is_payable_to_employee": true,
      "is_included_in_total_cost": true,
      "rate_type": "fixed_amount",
      "percent": null
    },
    {
      "id": 1541,
      "compensation_type": { "id": 2, "title": "Housing allowance", "is_archived": false },
      "amount_gross": "500.00",
      "amount_net": null,
      "currency": "USD",
      "per_type": "monthly",
      "description": null,
      "kind": "earning",
      "is_included_in_gross": true,
      "is_payable_to_employee": true,
      "is_included_in_total_cost": true,
      "rate_type": "fixed_amount",
      "percent": null
    }
  ]
}

Поле строки	Описание
compensation_type	Компонент компенсации. Тот же id приходит в compensation_type.id у доп. компенсаций
amount_gross, amount_net	Суммы строкой
currency, per_type	Валюта и период строки
kind	earning (начисление), deduction (удержание) или employer_contribution (взнос работодателя)
is_included_in_gross	Строка входит в gross
is_payable_to_employee	Строка выплачивается сотруднику
is_included_in_total_cost	Строка входит в полную стоимость для работодателя
rate_type, percent	fixed_amount или процентная строка со ставкой; у процентной строки суммы уже посчитаны

lines равен null, если у API-пользователя нет права на поле employee_compensation_lines. Выплаты вне ведомости не возвращаются.

Обновить / удалить запись компенсации

PUT    /api/v1/employees/{employee_id}/compensations/{id}
DELETE /api/v1/employees/{employee_id}/compensations/{id}

---

Дополнительные компенсации

Дополнительные компенсации - разовые выплаты: бонусы, премии, компенсации расходов. У выплаты одна дата - date_effective_from, даты окончания нет. Регулярные надбавки - это строки пакета компенсации.

Получить список доп. компенсаций

GET /api/v1/employees/{employee_id}/additional-compensations

Создать доп. компенсацию

POST /api/v1/employees/{employee_id}/additional-compensations

Поле	Тип	Описание
compensation_type_id	integer	ID компонента компенсации (обязательно)
date_effective_from	string (date)	Дата выплаты (обязательно)
amount_gross	number	Сумма gross
amount_net	number	Сумма net
amount	number	Устаревшее: пишется в amount_gross, если amount_gross не передан
currency	string	Валюта
description	string	Описание
comment	string	Комментарий
custom_fields	object	Значения кастомных колонок по слагу колонки

Прежние поля type, frequency_type и date_effective_to игнорируются: любая запись сохраняется как разовая выплата.

Обновить / удалить доп. компенсацию

PUT    /api/v1/employees/{employee_id}/additional-compensations/{id}
DELETE /api/v1/employees/{employee_id}/additional-compensations/{id}

---

Строки в кастомных таблицах сотрудника

Позволяет писать произвольные строки в кастомные таблицы, привязанные к сотруднику (например, «Бонусы начисленные», «Реквизиты выплат»). Список доступных таблиц и их slug полей получается через GET /api/v1/custom-fields/tables.

Добавить строку

POST /api/v1/employees/{employee_id}/field-tables/{table_id}/rows

Поле	Тип	Описание
date_effective_from	string (date)	Дата начала действия строки
cells	object	{slug: value} - значения ячеек

Поддерживаемые типы значений в cells:

• text / textarea / email / phone - строка
• number / currency / percentage - число
• date - строка YYYY-MM-DD
• datetime - строка ISO 8601
• select - ID опции
• switch - boolean
• employee_reference - integer (ID сотрудника)

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

{
  "date_effective_from": "2024-01-01",
  "cells": {
    "bonus_amount": 50000,
    "bonus_currency": "RUB",
    "bonus_comment": "Квартальный бонус Q1"
  }
}

Обновить / удалить строку

PUT    /api/v1/employees/{employee_id}/field-tables/{table_id}/rows/{id}
DELETE /api/v1/employees/{employee_id}/field-tables/{table_id}/rows/{id}

---

Структура организации

Справочники для полей department_id, division_id и команд у сотрудников и вакансий.

Департаменты

GET /api/v1/departments/all

Возвращает все департаменты, включая архивные: id, title, emoji, image_url, parent_id, manager (полная карточка сотрудника или null), employees_count и is_archived.

Нужно любое из прав: settings_roles_permissions, settings_departments, manage_jobs, manage_leave_policies, manage_approval_policy, see_departments_structure, employee_position_department.

Дивизионы

GET /api/v1/divisions/all

Возвращает все дивизионы, включая архивные: id, title и is_archived.

Нужно любое из прав: settings_roles_permissions, settings_divisions, manage_jobs, manage_leave_policies, manage_approval_policy, employee_position_division.

Команды

POST /api/v1/teams/search

Поле	Тип	Описание
text	string	Поиск по названию команды
employee_ids	array[integer]	Команды, в которых состоят эти сотрудники
page_number	integer	Номер страницы, с 1

Возвращает страницу команд, отсортированных по названию. В каждой команде id, title, description, emoji, background_url, links (title, url) и members (id, employee, role, sort, description).

Нужно любое из прав: manage_teams >= view, settings_roles_permissions, manage_leave_policies, manage_approval_policy.

---

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

Полный цикл создания нового сотрудника из HR/payroll-системы:

1. Создать сотрудника - POST /api/v1/employees с базовыми данными и датой найма.
2. Обновить персональные данные - PUT /api/v1/employees/{id} с email, телефоном, кастомными полями.
3. Зафиксировать трудоустройство - POST /api/v1/employees/{id}/employments с типом договора.
4. Зафиксировать компенсацию - POST /api/v1/employees/{id}/compensations с зарплатой.
5. Записать строки в кастомные таблицы - POST /api/v1/employees/{id}/field-tables/{table_id}/rows для бонусов, реквизитов и т.п.

При увольнении:

1. Закрыть трудоустройство - PUT /api/v1/employees/{id}/employments/{id} (добавить date_effective_to).
2. Архивировать сотрудника - DELETE /api/v1/employees/{id}.