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

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

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

Используйте эту страницу, когда проектируете синхронизацию оргструктуры, сопоставляете пользователей 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 из свежего ответа.