Публичный API Брусники.ЛМС — интеграция LMS с HR, CRM и BI

Публичный API Брусника.ЛМС — программный интерфейс для интеграции LMS с внешними системами: HR-системами, CRM, сайтами и BI. Через API можно работать с пользователями, учебным контентом, назначениями, базой знаний, получать результаты обучения и настраивать автоматическую передачу событий из Брусника.ЛМС во внешние системы.

API находится в статусе бета. Доступ к настройкам публичного API осуществляется в разделе «Управление системой → Публичный API» и доступен администратору портала.

Публичный API предназначен прежде всего для разработчиков интеграций клиента и партнёров. Администратор выпускает ключи доступа и определяет, какие разделы API доступны каждому ключу.

Что позволяет делать публичный API Брусника.ЛМС

Через публичный API можно:

• получать список и данные пользователей;
• создавать внешних пользователей и их учётные записи;
• изменять данные внешних пользователей;
• работать с подразделениями и дополнительными полями профиля;
• создавать, изменять, получать и удалять уроки, курсы, программы и тесты;
• создавать и управлять назначениями контента и программ;
• работать с субаккаунтами;
• загружать и получать файлы;
• работать с папками и материалами базы знаний;
• управлять подписками на материалы базы знаний;
• получать результаты обучения и другие отчёты;
• получать результаты тестов, оценки 360, выданные сертификаты и ответы на опросы;
• подписываться на исходящие вебхуки;
• получать уведомления об изменениях в LMS;
• проверять работоспособность сервиса.

API позволяет не только забирать данные из LMS, но и передавать в неё данные и выполнять операции над поддерживаемыми объектами.

Как устроен доступ к API

Доступ к публичному API осуществляется с помощью ключей.

Администратор портала может создать ключ и задать для него:

• имя;
• права доступа по разделам API;
• отдельно права на чтение и запись;
• срок действия.

Для ключа доступны следующие варианты срока действия:

• бессрочно;
• 30 дней;
• 90 дней;
• 365 дней.

Созданный ключ показывается только один раз. Список ключей доступен администратору и содержит их текущий статус:

• активен;
• истёк;
• отозван.

При необходимости ключ можно отозвать.

Каждый ключ работает только в том портале, в котором он был создан. Ключ одного портала не предназначен для доступа к другому порталу.

Документация API доступна по адресу самого портала.

Права доступа

Права настраиваются для отдельных разделов API. Чтение и запись контролируются отдельно.

Это позволяет, например, создать ключ только для получения отчётов без предоставления ему возможности изменять данные.

Конкретный набор доступных операций зависит от соответствующего раздела API.

Какие объекты доступны через API

Уроки

API поддерживает:

• список уроков;
• просмотр;
• создание;
• изменение;
• удаление.

Курсы

С курсами можно:

• получать список;
• просматривать курс;
• создавать;
• изменять;
• удалять.

Программы

Для программ обучения доступны:

• список;
• просмотр;
• создание;
• изменение;
• удаление.

Тесты

API позволяет:

• получать список тестов;
• просматривать тесты;
• создавать;
• изменять;
• удалять.

Назначения

Через API можно управлять назначениями контента и программ:

• получать список;
• просматривать назначения;
• создавать;
• изменять;
• удалять.

Пользователи

API поддерживает работу с внешними пользователями:

• список и поиск;
• просмотр;
• создание карточки пользователя;
• создание учётной записи с логином;
• получение ссылки-приглашения;
• изменение данных;
• смена подразделений.

При этом важно различать внешних пользователей Брусника.ЛМС и пользователей внешней бизнес-системы.

Через публичный API не создаются настоящие пользователи Битрикс24 и места в CRM. API создаёт внешних пользователей и учётные записи внутри соответствующего портала LMS.

Изменять через API можно только пользователей, которые были заведены как внешние.

Пользователя через API нельзя удалить. Его можно деактивировать, при этом история обучения сохраняется.

При создании пользователей может учитываться лимит мест, предусмотренный тарифом.

Субаккаунты

API поддерживает:

• список субаккаунтов;
• просмотр;
• создание;
• изменение;
• удаление.

Подразделения

Через API можно получать список подразделений.

Дополнительные поля профиля

API позволяет:

• получать список дополнительных полей;
• просматривать их;
• создавать;
• изменять;
• удалять.

Справочники

Через API доступны справочники, включая:

• шаблоны сертификатов;
• категории.

Файлы

API поддерживает:

• получение списка файлов;
• загрузку;
• получение файлов;
• удаление.

Работа с базой знаний

Публичный API позволяет интегрировать с внешними системами и базу знаний Брусника.ЛМС.

Папки базы знаний

Для папок доступны:

• список;
• дерево папок;
• просмотр;
• получение материалов папки;
• информация о том, где используется папка;
• создание;
• изменение;
• удаление.

Материалы базы знаний

Для материалов доступны:

• список;
• просмотр;
• статистика просмотров;
• информация о том, где используется материал;
• создание;
• изменение;
• перенос;
• удаление.

Подписки на материалы

API позволяет:

• получать список подписок;
• просматривать подписки;
• подписывать пользователей;
• отписывать пользователей.

Таким образом, внешняя система может не только получать информацию из базы знаний, но и выполнять поддерживаемые операции с её структурой, материалами и подписками.

Отчёты через API

Публичный API предоставляет пять основных групп отчётов:

1. прогресс обучения;
2. результаты тестов;
3. результаты оценки 360;
4. выданные сертификаты;
5. ответы на опросы.

Для отчётов предусмотрены фильтры по:

• сотруднику;
• объекту;
• статусу;
• датам;
• параметру «изменено с».

Большие выборки возвращаются постранично.

Постраничная выдача позволяет получать большие объёмы данных отдельными порциями, например при регулярной синхронизации результатов с BI-системой.

При работе с анонимными опросами необходимо учитывать отдельное правило: в отчётах нет данных о респондентах, если опрос был анонимным.

Исходящие вебхуки

Публичный API поддерживает исходящие вебхуки — механизм, при котором Брусника.ЛМС сама отправляет уведомление на адрес внешней системы после определённого события.

Можно подписаться на события:

• изменился статус прохождения;
• выдан сертификат;
• записан результат теста;
• получен ответ на опрос;
• изменился статус в оценке 360.

Для вебхуков доступны:

• создание подписки на событие;
• тестовая доставка;
• смена секрета.

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

Если доставка не удалась, система повторяет попытку.

При этом вебхуки не обязательно доставляются непосредственно в момент изменения данных. Они включаются на стороне сервера инсталляции, а события формируются с задержкой, равной интервалу опроса изменений. Если за один такой интервал произошло несколько изменений статуса, они могут прийти как одно уведомление.

Проверка работоспособности

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

Через соответствующий раздел можно получить статус сервиса.

Это может использоваться внешней системой для контроля доступности интеграционного интерфейса.

Автоматический онбординг из HR-системы

Один из сценариев использования API — автоматическая передача данных о новых сотрудниках из HR-системы в LMS.

Например:

1. HR-система фиксирует приём нового сотрудника.
2. Внешняя система создаёт пользователя в Брусника.ЛМС через API.
3. Через API сотруднику назначается программа адаптации.
4. Брусника.ЛМС отправляет во внешнюю систему уведомление о выдаче сертификата через вебхук.
5. HR-система может использовать это событие для фиксации завершения соответствующего этапа.

Такой сценарий строится на конкретных возможностях API: создании внешнего пользователя, назначении программы и исходящих уведомлениях.

Выгрузка результатов в BI

Другой сценарий — регулярная передача данных об обучении в BI-систему.

Например:

1. Администратор выпускает ключ с правом «отчёты: чтение».
2. Для ключа устанавливается срок действия 365 дней.
3. BI-система периодически обращается к API.
4. Прогресс обучения и результаты тестов забираются постранично.
5. Полученные данные используются внешней системой для собственной аналитики.

При этом API не создаёт саму BI-аналитику. Он предоставляет внешней системе данные из поддерживаемых отчётов.

Связь с другими возможностями Брусника.ЛМС

Публичный API связан с несколькими функциональными блоками LMS.

Через него можно работать с:

• пользователями;
• субаккаунтами;
• подразделениями;
• уроками;
• курсами;
• программами;
• тестами;
• назначениями;
• базой знаний;
• сертификатами;
• опросами;
• оценкой 360;
• отчётами.

Это позволяет использовать API как интеграционный слой между Брусника.ЛМС и внешними системами, если конкретная операция поддерживается соответствующим разделом API.

Работа Брусника.ЛМС внутри бизнес-систем

Брусника.ЛМС предназначена для работы в том числе вместе с бизнес-системами, в которых уже работают сотрудники. Публичный API позволяет соединять LMS с внешними HR-системами, CRM, сайтами и BI.

Однако наличие интеграции с определённой системой не означает автоматически, что каждый функциональный блок API доступен внутри неё. Возможность конкретного сценария зависит от соответствующей интеграции и её реализации.

Отдельно следует различать публичный API Брусника.ЛМС и другие механизмы интеграции.

Смежные способы интеграции

Помимо публичного API существуют другие способы подключения и передачи данных.

«Ключи»

В системе есть раздел «Управление системой → Ключи», связанный с идентификаторами портала. Эти ключи используются для передачи данных в интеграцию или поддержку.

Это не следует автоматически отождествлять с ключами публичного API, которые выпускаются в разделе «Управление системой → Публичный API».

Входящие вебхуки Битрикс24

Входящие вебхуки Битрикс24 позволяют подключать отдельную LMS к Битрикс24 без установки приложения из Маркетплейса.

Это отдельный механизм интеграции, а не дополнительный раздел публичного API Брусника.ЛМС.

Albato и Apify

В соответствующих редакциях доступны коннекторы Albato и Apify. Они относятся к смежным способам интеграции и не входят в коробочную поставку как часть публичного API.

Ограничения и особенности

При проектировании интеграции необходимо учитывать несколько правил.

API находится в статусе бета.

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

API работает с внешними пользователями. Он не создаёт настоящих пользователей Битрикс24 и места в CRM.

Удаление пользователя через API не поддерживается. Пользователя можно деактивировать, сохранив его историю обучения.

Изменять через API можно только пользователей, созданных как внешние.

Создание пользователей может быть ограничено количеством мест по тарифу.

Анонимные опросы не содержат данных о респондентах в отчётах.

Вебхуки зависят от серверного механизма опроса изменений. Поэтому события могут поступать с задержкой, а несколько изменений статуса за один интервал могут быть объединены в одно уведомление.

Ссылка-приглашение недоступна в отдельной LMS. В этом варианте используется вход по логину и паролю.

Настройки API

Основные настройки находятся в двух разделах:

• «Управление системой → Публичный API» — выпуск и управление ключами публичного API;
• «Управление системой → Ключи» — идентификаторы портала, используемые для интеграций или поддержки.

Документация публичного API доступна по адресу конкретного портала.

Частые вопросы

Что такое публичный API в Брусника.ЛМС?

Это программный интерфейс для связи Брусника.ЛМС с внешними HR-системами, CRM, сайтами и BI, через который можно передавать данные, управлять поддерживаемыми объектами и получать результаты обучения.

Кто может выпускать ключи API?

Ключи выпускает администратор портала в разделе «Управление системой → Публичный API».

Можно ли ограничить права API-ключа?

Да. Для ключа можно отдельно настроить права чтения и записи по разделам API.

Можно ли через API создавать пользователей?

Да, API позволяет создавать внешних пользователей и учётные записи с логином. При этом API не создаёт настоящих пользователей Битрикс24 и места в CRM.

Можно ли удалить пользователя через API?

Нет. Пользователя через API можно деактивировать, при этом история его обучения сохраняется.

Можно ли получать результаты обучения через API?

Да. API предоставляет отчёты по прогрессу обучения, результатам тестов, оценке 360, сертификатам и ответам на опросы.

Можно ли передавать результаты в BI?

Да. Поддерживаемые отчёты можно получать через API, в том числе постранично, что подходит для регулярной выгрузки больших выборок во внешнюю систему.

Можно ли получать уведомления об изменениях в LMS?

Да. Для этого используются исходящие вебхуки. Они поддерживают события изменения статуса прохождения, выдачи сертификата, записи результата теста, получения ответа на опрос и изменения статуса оценки 360.

Можно ли использовать API с Bitrix24?

Брусника.ЛМС поддерживает работу с бизнес-системами, включая Bitrix24, но конкретная возможность использования отдельного API-раздела зависит от соответствующей интеграции. Сам публичный API не создаёт пользователей Битрикс24 или места в CRM.

Можно ли использовать API для базы знаний?

Да. Через API доступны папки, материалы базы знаний и подписки на материалы с набором операций, предусмотренных соответствующими разделами API.

Как долго действует API-ключ?

Ключ может быть бессрочным либо иметь срок действия 30, 90 или 365 дней.

Что происходит с ключом после его создания?

Значение ключа показывается один раз при создании. В дальнейшем администратор видит ключ в списке вместе с его статусом, но повторного показа самого значения не предусмотрено.

Коротко

Публичный API Брусника.ЛМС — это бета-интерфейс для интеграции LMS с HR-системами, CRM, сайтами и BI. Через него можно управлять поддерживаемыми пользователями, контентом, назначениями и базой знаний, а также получать результаты обучения и отчёты. Исходящие вебхуки позволяют передавать во внешние системы уведомления об изменениях в обучении, тестах, сертификатах, опросах и оценке 360.