Версии скоупа user

Скоуп user существует в трех версиях. Это три самостоятельных кода: user_brief, user_basic и user. Версия определяет, какие поля профиля сотрудников вернут методы. От нее же зависит, может ли приложение приглашать сотрудников и менять их профили. Версии позволяют выдать приложению только те персональные данные, которые нужны его сценарию.

В облачном Битрикс24 доступны все три версии. В коробочном Битрикс24 они появились с версии модуля Rest 21.600.0. До нее доступен только скоуп user.

Скоупы выбирают в настройках приложения или вебхука — порядок описан в статье Доступные скоупы Битрикс24. Значения полей профиля и формат ответа смотрите на страницах методов user.get и user.fields.

Чем версии отличаютсяЧем версии отличаются

Версии вложены друг в друга: user_basic включает все поля user_brief, а user — все поля user_basic.

Минимальная версия скрывает не все персональные данные. В user_brief закрыты в первую очередь контактные данные: e-mail, личный и рабочий телефоны, улица и индекс, ссылки на внешние профили. При этом пол, дата рождения и фото сотрудника доступны во всех трех версиях. Полный состав каждой версии — в таблицах ниже.

Версия user добавляет к user_basic три поля: LAST_LOGIN, PERSONAL_WWW и PERSONAL_ICQ. Главное ее отличие не в полях, а в операциях записи.

Как выбрать версиюКак выбрать версию

Запрашивайте самую узкую версию, которой хватит для сценария: приложение получит меньше персональных данных, а администратор Битрикс24 увидит в списке прав более низкий уровень доступа.

Как работает ограничение по версииКак работает ограничение по версии

Ограничение действует при каждом вызове методов, которые читают или меняют профиль: user.fields, user.current, user.get, user.search, user.add и user.update.

• Каждый из этих методов возвращает и принимает только разрешенные версией поля.
• Методы user.online и user.counters доступны во всех трех версиях: они не возвращают поля профиля.
• Битрикс24 пропускает поле, которого нет в разрешенном списке. В параметрах select и filter оно не учитывается, в ответе его нет, метод не возвращает ошибку.
• Методы user.add и user.update работают только в версии user. В версиях user_brief и user_basic вызов вернет ошибку insufficient_scope с описанием The request requires higher privileges than provided by the access token. Ответ одинаков для приложения и вебхука.
• Скоуп не отменяет проверку прав сотрудника. Приглашать новых сотрудников методом user.add может администратор, а в облачном Битрикс24 — еще и сотрудник, которому выдано право приглашать. Метод user.update без прав администратора меняет только профиль самого сотрудника — поля ACTIVE и UF_DEPARTMENT в этом случае не записываются.
• Приложение получает событие onUserAdd во всех трех версиях. В данных нового сотрудника остаются только разрешенные версией поля.
• Самая широкая из выданных версий определяет доступ. Например, если выданы user_brief и user_basic, работает user_basic.
• Выбранная версия не влияет на методы user.userfield.*: они управляют настройками пользовательских полей и работают в отдельном скоупе user.userfield.

Чтобы увидеть фактический список полей для выданной версии, вызовите метод user.fields.

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/user.fields

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{}' \
https://**put_your_bitrix24_address**/rest/user.fields

Метод вернет коды полей и их названия — только те, что разрешены выданной версией. По составу ответа видно версию:

• нет поля EMAIL — user_brief
• есть EMAIL, но нет LAST_LOGIN — user_basic
• есть LAST_LOGIN — user

Пользовательские поля профиляПользовательские поля профиля

Поля с префиксом UF_USR_ не входят в списки версий.

• В версии user они доступны для чтения и записи без дополнительных условий.
• В версиях user_brief и user_basic их можно только читать, если приложению выдан скоуп user.userfield. Записать значение в такое поле нельзя: для этого нужен метод user.update, а он работает только в версии user.

Создать и настроить такие поля можно методами user.userfield.*.

Какие поля доступныКакие поля доступны

В таблицах перечислены стандартные поля профиля, включая поля с префиксом UF_, которые есть в Битрикс24 по умолчанию. «Да» — поле доступно для чтения в этой версии, «Нет» — недоступно. Записывают поля только методы user.add и user.update, поэтому в версиях user_brief и user_basic любое поле доступно лишь для чтения.

Поля LAST_LOGIN, DATE_REGISTER и IS_ONLINE доступны только для чтения. Методы user.add и user.update не записывают их даже в версии user.

Идентификация и статусИдентификация и статус

Имя, должность, подразделениеИмя, должность, подразделение

КонтактыКонтакты

*Принадлежит компании Meta Platforms, Inc., которая признана экстремистской и запрещена на территории Российской Федерации.

АдресаАдреса

Личные и профессиональные данныеЛичные и профессиональные данные

Продолжите изучениеПродолжите изучение

• Доступные скоупы Битрикс24
• Получить поля пользователя user.fields
• Получить список пользователей по фильтру user.get
• Пользователи: обзор методов