Модель данных

На этой странице описаны сущности организационной структуры: пользователи, юрлица, сотрудники, отделы и должности. Остальные сущности (документы, маршруты подписания, уведомления и др.) описаны в разделах, где они используются.

Когда использовать

Используйте эту страницу, когда проектируете синхронизацию оргструктуры, сопоставляете пользователей HRlink с внешней системой или разбираетесь, почему один человек представлен несколькими записями Employee.

Что нужно заранее

Что нужно	Где получить
tenantHost	Адрес тенантаTenant Экземпляр системы HRlink на отдельном домене (например, company.hr-link.ru). Внутри одного тенанта может быть несколько пространств клиентов. HRlink
clientId	Текущий пользователь
Токен	Аутентификация
Юрлица, отделы и должности во внешней системе	В HR-системе клиента

Типовые сценарии

Сопоставить пользователя и сотрудника

1. Найдите пользователя клиента (ClientUser) по СНИЛС или данным сотрудника.
2. Получите сотрудников через Получить сотрудников.
3. Сопоставьте записи Employee с юрлицами: один ClientUser может иметь несколько записей Employee.

Проверить руководителей в оргструктуре

1. Получите сотрудников через Получить сотрудников.
2. Проверьте поля headManager и functionalManager.
3. Не используйте эти поля как автоматический признак подписанта от работодателя — это отдельная роль в документообороте.

Ограничения и ошибки

• client в API означает пространство клиента, а не заказчика или контрагента.
• Один человек может иметь несколько записей Employee в разных юрлицах или ставках.
• Юрлица не уникальны по ИНН, ОГРН и КПП, поэтому интеграция должна хранить устойчивые идентификаторы.
• При обновлении сущностей передавайте актуальное значение version, иначе сервер вернёт ошибку конфликта.

Основные сущности

Tenant — тенант

ТенантTenant Экземпляр системы HRlink на отдельном домене (например, company.hr-link.ru). Внутри одного тенанта может быть несколько пространств клиентов. — это экземпляр HRlink на отдельном домене, например company.hr-link.ru. Внутри одного тенантаTenant Экземпляр системы HRlink на отдельном домене (например, company.hr-link.ru). Внутри одного тенанта может быть несколько пространств клиентов. живёт одно или несколько пространств клиентов. В OpenAPI и ответах API тенантTenant Экземпляр системы HRlink на отдельном домене (например, company.hr-link.ru). Внутри одного тенанта может быть несколько пространств клиентов. обозначается как tenant. Подробнее — в разделе Обзор API.

User — пользователь системы

Физическое лицо. Один UserUser Физическое лицо в системе HRlink. Один User соответствует одному реальному человеку. С пользователем связаны персональные данные, документы (СНИЛС, паспорт, ИНН) и логины (email, телефон). соответствует одному реальному человеку. С пользователем связаны:

• Персональные данные — ФИО, пол, дата рождения
• Документы (СНИЛС, паспорт, ИНН) — номер документа уникален внутри типа, у одного пользователя может быть только один документ каждого типа
• Логины (email, телефон, Telegram) — уникальны внутри типа канала, требуют подтверждения

Когда не получится создать пользователя

В тенантеTenant Экземпляр системы HRlink на отдельном домене (например, company.hr-link.ru). Внутри одного тенанта может быть несколько пространств клиентов. нельзя создать пользователя, если уже существует другой пользователь с таким же:

• СНИЛС — номер СНИЛС уникален в тенантеTenant Экземпляр системы HRlink на отдельном домене (например, company.hr-link.ru). Внутри одного тенанта может быть несколько пространств клиентов.
• Серия и номер паспорта — паспортные данные уникальны в тенантеTenant Экземпляр системы HRlink на отдельном домене (например, company.hr-link.ru). Внутри одного тенанта может быть несколько пространств клиентов.
• ИНН — номер ИНН уникален в тенантеTenant Экземпляр системы HRlink на отдельном домене (например, company.hr-link.ru). Внутри одного тенанта может быть несколько пространств клиентов.
• Email или телефон — один email или номер телефона привязан только к одному пользователю

При попытке создать пользователя с дублирующими данными API вернёт ошибку.

Client — пространство клиента

Изолированное пространство внутри тенантаTenant Экземпляр системы HRlink на отдельном домене (например, company.hr-link.ru). Внутри одного тенанта может быть несколько пространств клиентов.. Юрлица, записи ClientUser и сотрудники принадлежат конкретному клиенту. Один клиент может объединять несколько юрлиц — например, группу компаний.

Название client — техническое и не означает «заказчик» или «контрагент». Подробнее о причинах такого нейминга — в разделе Обзор API → Что такое client.

ClientUser — пользователь клиента

ClientUser — связь пользователя с клиентом, пара (userId, clientId). Один пользователь относится к нескольким клиентам, но внутри одного клиента существует только одна запись ClientUser на него (ограничение уникальности). Поле externalId связывает запись с внешней системой — подробнее в разделе Идентификаторы.

LegalEntity — юридическое лицо

Юрлицо в пространстве клиента. Ограничений уникальности по ИНН, ОГРН и КПП нет: через API создаётся несколько юрлиц с одинаковыми реквизитами. Не создавайте такие дубли — при поиске и фильтрации вы не отличите их друг от друга по реквизитам.

Employee — сотрудник

Employee — связь пользователя пространства клиента с юрлицом, пара (clientUserId, legalEntityId). Один пользователь пространства клиента может:

• относиться к нескольким юрлицам одного пространства клиента
• иметь несколько записей EmployeeEmployee Связь пользователя пространства клиента с юрлицом — пара (clientUserId, legalEntityId). Один пользователь может иметь несколько записей Employee в разных юрлицах или даже в одном. в одном юрлице (например, разные ставки)

Department — отдел

Подразделение юрлица. Отделы образуют дерево: у каждого отдела есть parentDepartmentId, указывающий на родительский отдел.

Корневой отдел — отдел без parentDepartmentId. HRlink создаёт его автоматически вместе с пространством клиента. Через API создать ещё один корневой отдел нельзя: при создании отдела parentDepartmentId обязателен.

Отдел можно деактивировать (active: false) — он перестаёт отображаться в оргструктуре, но остаётся в базе. Отдел можно отметить как филиал юрлица.

Position — должность

Плоский справочник названий должностей на уровне пространства клиента. Справочник общий для всех юрлиц клиента. PositionPosition Название должности из плоского справочника на уровне пространства клиента. Справочник общий для всех юрлиц. Position — именно название должности, а не позиция штатного расписания. — это именно название должности (например, «Главный бухгалтер»), а не позиция штатного расписания. Штатное расписание, ставки и вакансии в модели данных HRlink не реализованы.

Цепочка User → ClientUser → Employee

Один человек может быть сотрудником в нескольких юрлицах одного клиента. Метод Получить сотрудников вернёт несколько записей Employee для одного физического лица — по одной на каждое юрлицо.

Руководители в оргструктуре

Ниже описаны руководители в организационной структуре. Это не то же самое, что руководитель-подписант со стороны работодателя в кадровом ЭДОЭДО Электронный документооборот — обмен юридически значимыми документами в электронном виде. HRlink реализует кадровый ЭДО (КЭДО): подписание трудовых документов электронными подписями вместо бумажных оригиналов..

Различайте три сущности:

• headManager — руководитель отдела в оргструктуре
• functionalManager — управленческий руководитель конкретного сотрудника
• руководитель работодателя или другой уполномоченный подписант — юридически значимая сторона документооборота, которая подписывает документы от имени работодателя

Поля headManager и functionalManager описывают структуру подчинённости. Они не означают, что этот сотрудник автоматически подписывает документы.

Руководитель отдела (headManager)

Привязан к отделу. Один руководитель на отдел.

• Поле headManager — в объекте отдела
• Значение задаётся при создании или обновлении отдела
• Все сотрудники отдела видят этого руководителя в своих данных

Управленческий руководитель (functionalManager)

Привязан к конкретному сотруднику. Управленческим руководителем может быть любой другой сотрудник пространства клиента — независимо от иерархии отделов и даже из другого юрлица. Единственное ограничение: нельзя назначить руководителем самого себя.

• Поле functionalManager — в объекте сотрудника
• Значение задаётся отдельным методом обновления руководителей

Кто подписывает документы от имени работодателя

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

Это отдельная роль в сценарии подписания. Она не определяется автоматически по полям headManager или functionalManager.

Когда какой тип использовать

• Руководитель отдела — для иерархической структуры (начальник отдела, директор филиала)
• Управленческий руководитель — для матричной структуры (проектный руководитель, куратор)

Версионирование данных (optimistic locking)

Все сущности содержат поле version (int64) для оптимистической блокировки при параллельном редактировании:

1. Вы получаете данные с текущей версией (например, version: 3)
2. Обрабатываете данные на своей стороне
3. Отправляете обновление, указывая version: 3
4. Если кто-то изменил данные параллельно (версия уже 4) — получите ошибку конфликта

подсказка

Сохраняйте version из ответа на чтение и передавайте его в запросе на обновление. Не используйте старые значения version из предыдущих сессий — перед обновлением перечитайте объект и возьмите актуальный version из свежего ответа.