Сотрудники

Группа методов /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).

---

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

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}

---

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

Компенсация фиксирует базовую зарплату (gross/net) с привязкой к дате начала действия.

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

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	Комментарий

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

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

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

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

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

---

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

Дополнительные компенсации - это надбавки и бонусы сотрудника как отдельная сущность (не путать с кастомными таблицами).

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

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

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

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

Поле	Тип	Описание
compensation_type_id	integer	ID типа компенсации (обязательно)
type	string	one_time или recurring (обязательно)
amount	number	Сумма (обязательно)
date_effective_from	string (date)	Дата начала (обязательно)
date_effective_to	string (date)	Дата окончания
frequency_type	string	monthly, quarterly, yearly (для recurring)
currency	string	Валюта
description	string	Описание
comment	string	Комментарий

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

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}

---

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

Полный цикл создания нового сотрудника из 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}.