Роли и права доступа

Роли и права определяют, какие методы API доступны пользователю и какие данные сервер вернёт в ответе.

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

Используйте эту страницу, когда интеграция получает 403, нужно выбрать пользователя для master-token impersonationImpersonation Выполнение API-запросов от имени другого пользователя при использовании мастер-токена. Пользователь указывается через заголовки Impersonated-User-Id и Impersonated-User-Id-Type. или настроить доступ кадровика к юрлицам, отделам, сотрудникам и документам.

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

Что нужно	Где получить
clientId	Текущий пользователь
Пользователь, от имени которого работает интеграция	Мастер-токен или User-Api-Token
Юрлица и отделы	Модель данных
Список нужных операций	Гайды по сценарию интеграции

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

Назначить роли сотрудника

1. Найдите пользователя и юрлица, где ему нужны права.
2. Вызовите Создать или обновить роли сотрудника.
3. Проверьте результат через Получить роли сотрудника по юрлицам.

Ограничить доступ по отделам

1. Определите отделы, которые должен видеть кадровик.
2. Вызовите Обновить список доступных отделов.
3. Проверьте результат через Получить список доступных отделов.

Проверить выборку с permissionContext

1. Выберите операцию, для которой нужны данные, например DOCUMENTS_CREATE.
2. Вызовите Получить сотрудников с permissionContext.
3. Используйте только сотрудников, которых сервер вернул в ответе.

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

• Один сотрудник не может одновременно быть кадровиком и делопроизводителем в одном юрлице.
• При master-token результат запроса зависит от прав пользователя из impersonationImpersonation Выполнение API-запросов от имени другого пользователя при использовании мастер-токена. Пользователь указывается через заголовки Impersonated-User-Id и Impersonated-User-Id-Type.-заголовков.
• Ошибка 13.5353 означает, что метод требует permissionContext, но клиент его не передал.
• Если у пользователя нет роли в нужном юрлице, методы управления сотрудниками и документами вернут 403.

Два уровня ролей

Права в HRlink назначаются на двух уровнях: пользователь клиента и сотрудник. Роль пользователя клиента действует на всё пространство клиента, роль сотрудника — только в рамках конкретного юрлица.

Уровень	Роль	Ключ	Описание
Пользователь клиента	Администратор пространства	OWNER	Полный доступ к клиенту, управление пользователями и ролями
Пользователь клиента	Настройщик	CONFIGURATOR	Настройка справочников, типов документов, шаблонов
Пользователь клиента	Редактор новостей	NEWS_EDITOR	Управление новостями
Сотрудник юрлица	Кадровик	HR	Управление сотрудниками, документами, справочниками юрлица
Сотрудник юрлица	Делопроизводитель	CLERK	Работа с документами, ограниченный набор прав
Сотрудник юрлица	Руководитель	HEAD_MANAGER	Подписание документов от имени работодателя

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

Ограничение совмещения

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

Права доступа (Permissions)

При назначении роли HRlink автоматически выдаёт набор прав по умолчанию. Администратор пространства может изменить этот набор: добавить или отозвать отдельные permissions.

Права пользователя клиента (ClientUserPermission) действуют на всё пространство. Права сотрудника (EmployeePermission) — в рамках конкретного юрлица. Ключи совпадают, но области действия различаются: один пользователь может иметь разные наборы прав в разных юрлицах.

Права по умолчанию для ролей

В таблице — права, которые система назначает при создании роли. Администратор пространства (OWNER) по умолчанию имеет все права и в таблице не показан.

Н — Настройщик, РН — Редактор новостей, К — Кадровик, Д — Делопроизводитель, Р — Руководитель.

Группа	Право	Н	РН	К	Д	Р
Пользователи	CLIENT_USERS, CLIENT_USERS_CREATE, CLIENT_USERS_UPDATE, CLIENT_USERS_INVITE			+
	USERS_CREATE, USERS_UPDATE			+
Сотрудники	EMPLOYEES	+		+	+
	EMPLOYEES_CREATE, EMPLOYEES_UPDATE, EMPLOYEES_RESTORE			+
	EMPLOYEES_UPLOAD_CERTIFICATE, EMPLOYEES_CREATE_QES_ISSUE, EMPLOYEES_CREATE_NQES_ISSUE			+
	VIEW_EMPLOYEE_NUMBER			+	+
	MULTI_FACTORS, MULTI_FACTORS_RESET			+
Документы	DOCUMENTS, DOCUMENTS_CREATE, DOCUMENTS_UPDATE, DOCUMENTS_DELETE			+	+
	DOCUMENTS_SEND_TO_SIGNING			+	+
	DOCUMENTS_MULTIPLE_SEND_AND_SIGN			+	+	+
	DOCUMENTS_SIGN_AS_HEAD_MANAGER, DOCUMENTS_CREATE_FOR_SOMEONE_ELSE			+
	DOCUMENTS_ANNUL			+	+
	DOCUMENTS_FILE			+
Типы документов	DOCUMENT_TYPES	+		+
	DOCUMENT_TYPES_CREATE, DOCUMENT_TYPES_UPDATE	+
Юрлица	LEGAL_ENTITIES	+	+	+	+
	LEGAL_ENTITIES_CREATE	+
	LEGAL_ENTITIES_UPDATE	+		+
	LEGAL_ENTITIES_DELETE			+
Отделы	DEPARTMENTS	+	+	+	+
	DEPARTMENTS_CREATE, DEPARTMENTS_UPDATE, DEPARTMENTS_DELETE	+		+
Должности	EMPLOYEE_POSITIONS	+	+	+	+
	EMPLOYEE_POSITIONS_CREATE, EMPLOYEE_POSITIONS_UPDATE, EMPLOYEE_POSITIONS_DELETE	+		+
Заявления	APPLICATION_GROUPS, APPLICATIONS, APPLICATIONS_PROCESSING			+
	APPLICATION_GROUPS_CREATE_FOR_SOMEONE_ELSE			+
	APPLICATION_TYPES	+		+
	APPLICATION_TYPES_CREATE, APPLICATION_TYPES_CHANGE_ORDER, APPLICATION_TYPES_GET_TEMPLATE	+
	APPLICATION_TYPES_UPDATE	+		+
ЛНАЛНА Локальный нормативный акт — внутренний документ организации, с которым сотрудники знакомятся через HRlink. Управляется через отдельный набор API-методов.	NORMATIVE_ACTS, NORMATIVE_ACTS_CREATE, NORMATIVE_ACTS_UPDATE			+
	NORMATIVE_ACTS_SEND_TO_SIGNING, NORMATIVE_ACTS_DELETE			+
МЧДМЧД Машиночитаемая доверенность (Attorney) — электронный документ, подтверждающий полномочия представителя юридического лица.	ATTORNEYS, ATTORNEYS_CREATE, ATTORNEYS_UPDATE, ATTORNEYS_IMPORT			+
	ATTORNEYS_DELETE, ATTORNEYS_SEND_TO_SIGNING			+
Синхронизация	BULK_DATA_SYNC_TASKS, BULK_DATA_SYNC_TASKS_CREATE	+		+
Маршруты	ROUTE_TEMPLATES_CREATE, ROUTE_TEMPLATES_EDIT	+
Связи сущностей	ENTITY_RELATION, ENTITY_RELATION_CREATE, ENTITY_RELATION_DELETE			+	+
Новости	NEWS, NEWS_CREATE, NEWS_UPDATE, NEWS_DELETE		+
Справочники структур	CUSTOM_STRUCTURES	+		+	+
	CUSTOM_STRUCTURES_CREATE, CUSTOM_STRUCTURES_UPDATE, CUSTOM_STRUCTURES_DELETE	+
Настройки	SETTINGS_GENERAL	+		+
	SETTINGS_LICENSE_VIEW	+
	TENANTS	+			+
	TENANTS_INFO	+
Отпуска	VACATIONS, VACATIONS_CREATE_AND_UPDATE			+
	VACATION_TYPE, VACATION_TYPE_UPDATE	+		+
Контакты HR	HR_CONTACTS, HR_CONTACTS_CREATE, HR_CONTACTS_UPDATE, HR_CONTACTS_DELETE	+
Витрина и профиль	SHOWCASE_EDIT	+
	REPEAT_NOTIFICATION_SETTINGS, REPEAT_NOTIFICATION_SETTINGS_UPDATE	+
	USER_PROFILE_MODULES, USER_PROFILE_MODULES_UPDATE	+		+
UI	UI_VIEW_EMPLOYEES_REGISTRY			+
	ENABLE_SIGNING_THROUGH_GOV_KEY			+
API-токены	USER_API_TOKEN, USER_API_TOKEN_CREATE, USER_API_TOKEN_UPDATE, USER_API_TOKEN_DELETE			+	+

Назначение ролей сотрудника в юрлицах

Кадровику и руководителю можно назначить роль сотрудника в юрлицах, где они не числятся как сотрудники. Например, кадровик из юрлица А сможет управлять документами в юрлице Б.

API-методы:

• Создать или обновить роли сотрудника — назначение ролей по юрлицам
• Получить роли сотрудника по юрлицам — текущие роли пользователя
• Получить сотрудников и роли — сотрудники и роли-связки

Ограничение доступа по отделам

По умолчанию кадровик видит всех сотрудников в доступных ему юрлицах. Доступные отделы (permitted departmentsDepartment Подразделение юрлица. Отделы образуют дерево: у каждого отдела есть parentDepartmentId. Корневой отдел создаётся автоматически при создании клиента.) ограничивают этот доступ конкретными отделами. Ограничение влияет на фильтрацию сотрудников, документов, заявлений и нормативных актов.

Типы доступа к отделу

Тип	Описание
INCLUDE_INHERITED	Доступ к отделу и всем дочерним. При создании нового дочернего отдела доступ появится автоматически
ONLY_FOR_THIS	Доступ только к этому отделу, без дочерних
ONLY_INHERITED	Доступ только к дочерним отделам, без родительского

API-методы:

• Обновить список доступных отделов — назначение отделов с типами доступа
• Получить список доступных отделов — все отделы юрлица с флагом permitted

Если доступные отделы не заданы

Если для сотрудника не назначены ограничения по отделам, ему доступны все отделы юрлица.

Контекстные права (permissionContext)

Методы получения справочных данных (юрлица, сотрудники, отделы) принимают query-параметр permissionContext. Он указывает, для какой операции нужны данные. API возвращает только те записи, к которым текущий пользователь имеет доступ в контексте указанной операции.

Пример: при создании документа интеграция вызывает Получить сотрудников с ?permissionContext=DOCUMENTS_CREATE. API вернёт только тех сотрудников, которым текущий пользователь может отправить документ — с учётом его юрлиц и отделов.

Где используется

Метод	permissionContext	Без параметра
Получить юрлица	опционален	Применяется право LEGAL_ENTITIES
Получить сотрудников	опционален	Возвращает всех доступных сотрудников
Получить пользователей	опционален	Возвращает всех доступных пользователей
Получить шаблоны маршрутов	опционален	Возвращает все доступные шаблоны
Получить справочники	опционален	Применяется право CUSTOM_STRUCTURES
Получить справочник	опционален	Применяется право CUSTOM_STRUCTURES
Получить справочник по внешнему ID	опционален	Применяется право CUSTOM_STRUCTURES
Получить доступные отделы	обязателен	Ошибка 13.5353
Получить элементы структур	обязателен	Ошибка 13.5353

Ошибки

errorCode	Причина
13.5350	Переданное значение не существует
13.5351	Значение не допустимо для этого метода
13.5353	Параметр обязателен, но не передан

Когда передавать permissionContext

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

Влияние ролей на API-запросы

Права определяют доступные данные

Когда интеграция использует мастер-токен от имени пользователя, результат запроса зависит от прав этого пользователя. Если у него нет роли кадровика, методы управления сотрудниками вернут ошибку 403.

Для синхронизации сотрудников и отправки документов пользователь, от имени которого работает интеграция, должен иметь роль HR с правами EMPLOYEES_CREATE, EMPLOYEES_UPDATE, DOCUMENTS_CREATE, DOCUMENTS_SEND_TO_SIGNING. Если интеграция только отправляет документы, достаточно роли CLERK с правами DOCUMENTS_CREATE, DOCUMENTS_SEND_TO_SIGNING.