/
Публичный API

Публичный API

Какова схема авторизации

Для публичных методов API реализована авторизация через публичный ключ API: при отправке запросов по урлам вида api/public/* идёт проверка на наличие заголовка (Header) X-Auth-Token. Если заголовок присутствует и соответствует указанному в конфиге, то авторизация проходит успешно.

Публичный ключ API хранится в .env под названием PUBLIC_API_TOKEN. На платформе он отображается в Панели управления → Настройки → Лицензия. Если публичный ключ API отсутствует или указан неверно, в запросах возвращается ошибка 401 Authorization Required.

Чтобы ввести ограничение входящих запросов к публичному API платформы, перейдите в Панель управления → Настройки → Лицензия, заполните поле Разрешённые IP-адреса, CIDR и сохраните изменения. Если поступит запрос с неразрешённого адреса, вернётся ошибка HTTP 403 — это можно отследить в разделе Логи → Лог сервисов. Подробнее — https://motivityy.atlassian.net/wiki/spaces/Documentation/pages/5734464#%D0%9B%D0%BE%D0%B3-%D1%81%D0%B5%D1%80%D0%B2%D0%B8%D1%81%D0%BE%D0%B2

Заголовки запросов

Header

Описание

Механика

Header

Описание

Механика

X-Auth-Token

Заголовок авторизации

  • Обязательный заголовок

  • При каждом обращении, не важно, POST или GET, в заголовках запроса нужно указывать параметр X-Auth-Token с предоставленным публичным ключом API в качестве значения

Locale

Язык запроса, на котором должен быть возвращён контент

  • Необязательный заголовок

  • Язык запроса передается с помощью заголовка Locale: <language> (одно значение)

  • Допустимые значения – en, ru, uz, ky. При добавлении на платформу новых языков появляется возможность указывать и их в заголовке.

  • Ответ возвращается на запрашиваемом языке, если:

    • В заголовке передано допустимое значение
      И

    • Для запрашиваемого элемента есть контент на запрашиваемом языке

  • Ответ возвращается на языке, установленном на платформе по умолчанию, если:

    • Заголовок запрашиваемого языка отсутствует
      ИЛИ

    • Значение заголовка не соответствует допустимым (опечатка, множественное значение, несуществующее значение)
      ИЛИ

    • Отсутствует контент на запрашиваемом языке

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

Какие запросы можно использовать

Отчеты

Получение списка всех доступных отчётов

Чтобы получить список всех доступных отчётов, нужно сделать GET запрос на адрес:

  • GET /public/api/v1/reports/list

В ответ придёт JSON массив объектов, каждый из которых будет содержать Название (title) и Системное имя (type).

Получение метаданных

Чтобы получить метаданные о конкретном отчёте, нужно сделать GET запрос на адрес:

  • GET /public/api/v1/reports/metadata/{type}
    заменив в адресе type на нужное Системное имя, полученное на предыдущем этапе.

В ответ придёт JSON объект с двумя полями:

  • headersList — объект, содержащий предполагаемые заголовки отчёта;
    Количество полей может быть любое, зависит от отчёта, т.к каждый отчёт содержит различные поля;
    Ключами являются Системные имена полей, а значениями являются Названия полей (например, "email": "Почта");
    В сформированном отчёте может быть другое количество полей или их названия (например, в отчёте по тестированию могут быть поля, отвечающие за вопросы выбранного тестирования, но мы не можем знать эти вопросы (поля) до выбора самого тестирования, поэтому в метаданных этих полей заранее быть не может).

  • filtersList — объект, содержащий фильтры данного отчёта;
    Ключами являются Системные имена, а значениями объекты, с информацией о фильтре (пример полей: type — тип, label — название, values — значения, url — адрес, на который нужно делать запрос для получения списка значений и поиска по нему);

Генерация и получение отчёта

Если данные по фильтру Статус пользователя (user_status) не были переданы в body при запросе, отчёт будет сформирован только по активным сотрудникам. При этом в массиве объектов data, который придёт в ответ, будет отсутствовать параметр user_status

Если при запросе отчётов Учебные планы. Сводный отчёт по всем учебным планам и Квесты. Сводный отчёт по всем квестам через публичный API значение для фильтра Назначения не передано, отчёты сформируются по всем назначениям. Подробно — https://motivityy.atlassian.net/wiki/spaces/Documentation/pages/5735229#%D0%A3%D1%87%D0%B5%D0%B1%D0%BD%D1%8B%D0%B5-%D0%BF%D0%BB%D0%B0%D0%BD%D1%8B.-%D0%A1%D0%B2%D0%BE%D0%B4%D0%BD%D1%8B%D0%B9-%D0%BE%D1%82%D1%87%D1%91%D1%82-%D0%BF%D0%BE-%D0%B2%D1%81%D0%B5%D0%BC-%D1%83%D1%87%D0%B5%D0%B1%D0%BD%D1%8B%D0%BC-%D0%BF%D0%BB%D0%B0%D0%BD%D0%B0%D0%BC и https://motivityy.atlassian.net/wiki/spaces/Documentation/pages/5735618#%D0%9A%D0%B2%D0%B5%D1%81%D1%82%D1%8B.-%D0%A1%D0%B2%D0%BE%D0%B4%D0%BD%D1%8B%D0%B9-%D0%BE%D1%82%D1%87%D1%91%D1%82-%D0%BF%D0%BE-%D0%B2%D1%81%D0%B5%D0%BC-%D0%BA%D0%B2%D0%B5%D1%81%D1%82%D0%B0%D0%BC

Обычный режим

Чтобы сгенерировать и получить отчёт, нужно отправить POST запрос на адрес:

  • post /public/api/v1/reports/generate/{type}
    заменив в адресе type на нужное Системное имя, полученное на этапе Получения списка всех доступных отчётов.

В body запроса нужно отправить JSON объект с полем filters, в котором будут поля, ключами которых будут Системные имена фильтров, полученных на этапе Получения метаданных, а значениями непосредственно значения фильтров (цифра, строка, массив и тд)

В ответ придёт JSON объект со следующими полями:

  • title — строка с названием отчёта;
    Может не совпадать со значением, полученным на первом этапе, т.к может содержать дополнительные данные вроде даты и других значений.

  • isMultiple — булево значение;
    Если значение true, то в полях headers и data будет не объект, а массив объектов — каждый объект это отдельная страница отчёта.

  • headers — объект, содержащий заголовки таблицы отчёта, где ключи это Системные имена полей, а значения это Названия полей.

  • data — массив объектов, содержащий данные отчёта;
    Каждый объект в массиве — это одна строка;
    Каждый объект содержет поля, ключами которого являются Системные имена полей, а значениями являются данные (например, "status": "Активен").

  • metadata — объект, содержащий дополнительные данные об отчёте, например, выбранные фильтры;
    Ключами объекта являются Системные имена полей, а значениями сами данные (например, "metadataFieldName": "Тестовый пользователь").

  • hasErrors — булево значение;
    Были ли ошибки при попытке сформировать отчёт;
    Если значение true, значит отчёт не сформирован и нужно смотреть ошибки в поле errors.

  • errors — объект, содержащий ошибки;
    Ключами являются Системные имена полей, а значениями Текст ошибки.

Режим потокового скачивания

Чтобы сгенерировать отчёт, для дальнейшего его скачивания в потоковом режиме, нужно отправить POST запрос на адрес:

  • post /public/api/v1/reports/create/{type}
    заменив в адресе type на нужное Системное имя, полученное на этапе Получения списка всех доступных отчётов.

В body запроса нужно отправить JSON объект с полем filters, в котором будут поля, ключами которых будут Системные имена фильтров, полученных на этапе Получения метаданных, а значениями непосредственно значения фильтров (цифра, строка, массив и тд)

Если данные по фильтру Статус пользователя (user_status) не были переданы в body при запросе, тогда отчёт будет сформирован только по активным сотрудникам, при этом в массиве объектов data, который придет в ответ, будет отсутствовать параметр user_status

В ответ придёт JSON объект с полем id, он же Идентификатор сгенерированного отчета.

Чтобы получить JSON данные отчёта, сгенерированного в предыдущем шаге, нужно отправить GET запрос на адрес:

  • GET /public/api/v1/reports/data/{id}
    заменив в адресе id на нужный Идентификатор, полученный в предыдущем шаге

Администратору платформы для обработки json необходимо включить на своей стороне поддержку потокового скачивания в принимаемом ПО

Описание режима потоковой передачи данных приведено на сайте Handle Large Messages with Chunking - Azure Logic Apps

Важно:

  1. В потоковом режиме данные передаются дольше

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

В ответ придёт JSON объект со следующими полями:

  • title — строка с названием отчёта;
    Может не совпадать со значением, полученным на первом этапе, т.к может содержать дополнительные данные вроде даты и других значений.

  • isMultiple — булево значение;
    Если значение true, то в полях headers и data будет не объект, а массив объектов — каждый объект это отдельная страница отчёта.

  • headers — объект, содержащий заголовки таблицы отчёта, где ключи это Системные имена полей, а значения это Названия полей.

  • data — массив объектов, содержащий данные отчёта;
    Каждый объект в массиве — это одна строка;
    Каждый объект содержит поля, ключами которого являются Системные имена полей, а значениями являются данные (например, "status": "Активен").

  • metadata — объект, содержащий дополнительные данные об отчёте, например, выбранные фильтры;
    Ключами объекта являются Системные имена полей, а значениями сами данные (например, "metadataFieldName": "Тестовый пользователь").

  • hasErrors — булево значение;
    Были ли ошибки при попытке сформировать отчёт;
    Если значение true, значит отчёт не сформирован и нужно смотреть ошибки в поле errors.

  • errors — объект, содержащий ошибки;
    Ключами являются Системные имена полей, а значениями Текст ошибки.

Структура отделов

Удаление отдела

Чтобы удалить отдел, нужно сделать POST запрос на адрес:

  • post /public/api/v1/department/delete

В body запроса нужно отправить обязательный JSON объект id, в котором указан уникальный идентификатор отдела

Пример:

{ "id": "test" }

В случае успешного запроса (200) в ответ придёт JSON объект со следующими полями:

  • result – значение true

  • status: "deleted" – текущий статус удаленного отдела

  • message – заполнен только если произошло удаление отдела, содержащего дочерние отделы. В остальных случаях значение пусто
    Пример: “message”: “After deleting the %идентификатор-отдела% department, the following departments were left without a parent: %идентификаторы-дочерних-отделов-через-запятую%”

    • В идентификаторах выводятся идентификаторы, задаваемые администраторами при импорте, а не внутренние идентификаторы отделов

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

Возвращается, если отдел был удален

{ "result": true, "status": "deleted", "message": "After deleting the %идентификатор-отдела% department, the following departments were left without a parent: %идентификаторы-дочерних-отделов-через-запятую%" }

В случае неудачного запроса (400), т.е. при попытке удалить отдел, которого нет в базе данных или если идентификатор отдела не заполнен или заполнен некорректно, возвращается ответ, в котором указана ошибка

В зависимости от конкретной ошибки, message может отличаться

Возможные ошибки:

  • Указанный отдел не найден

    • "result": false,

    • "message": "Unknown department identifier \"string\""

  • Идентификатор отдела не заполнен или заполнен некорректно

    • "result": false,

    • "message": "Department identifier not specified"

{ "result": false, "message": "Department identifier not specified" }

Возвращается в случае отсутствия или некорректного публичного ключа API при запросе

{ "result": false, "message": "Invalid public API token" }

Бейджи

Получение информации об имеющихся на платформе бейджах

Информация передается по всем неудаленным бейджам

Чтобы получить информацию об имеющихся на платформе бейджах, нужно сделать GET запрос на адрес:

  • GET /public/api/v1/badge
    Если требуется получить ответ на определенном языке, в заголовках запроса можно передать параметр Locale

В случае успешного запроса (200) в ответ придёт JSON объект со следующими полями:

  • id – идентификатор бейджа, INT

  • title – название бейджа (на запрашиваемом или языке, установленном по умолчанию), varchar

  • image – ссылка на загруженное изображение для бейджа, string

  • description – описание бейджа или NULL в случае его отсутствия, string

  • popupDescription – сообщение при получении бейджа, string

  • color – значение цвета для бейджа или NULL, если цвет не установлен, varchar

  • active – статус активности бейджа, 0 или 1, boolean

  • system – 1 если бейдж системный, 0 если бейдж пользовательский, boolean

  • children – массив с уровнями бейджей, если бейдж содержит уровни, или пустой массив:

    • Для каждого дочернего бейджа отображаются все значения выше (кроме children) и дополнительное значение grade

    • grade – грейд бейджа, INT

[ { “id“: 93, “title“: “Спортивные достижения“, “image“: “https://support.motivationportal.ru/api/file/download/1386/28px-01.svg“, “description“: NULL, “popupDescription“: “Поздравляем!“, “color”: NULL, “active“: “1“, “system“: “0“, “children“: [ { “id“: 98, “title“: “Спортивные достижения 1 уровень“, “image“: “https://support.motivationportal.ru/api/file/download/1386/30px-01.svg“, “description“: “Поздравляем с первым уровнем!“, “popupDescription“: “Поздравляем с первым уровнем!“, “color”: NULL, “active“: “0“, “system“: “0“, “grade“: “1“ }, { “id“: 100, “title“: “Спортивные достижения 2 уровень“, “image“: “https://support.motivationportal.ru/api/file/download/1386/50px-01.svg“, “description“: “Поздравляем со вторым уровнем!“, “popupDescription“: “Поздравляем со вторым уровнем!“, “color”: NULL, “active“: “0“, “system“: “0“, “grade“: “2“ } ] } ]

Возвращается в случае отсутствия или некорректного публичного ключа API при запросе

{ "result": false, "message": "Invalid public API token" }

Начисление бейджа пользователю

Бейдж начисляется пользователю, если:

  • Пользователь существует и не удалён, статус активности не важен

  • Бейдж существует, активен, не удалён

  • Бейдж не является системным

  • Бейдж не является родительским для многоуровнего бейджа

  • Бейдж не является более низким грейдом уже назначенного грейда многоуровневого бейджа

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

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

Чтобы начислить бейдж пользователю, нужно сделать POST запрос на адрес:

  • post /public/api/v1/badge/{badgeId}/assign
    в {badgeId} должен передаваться ID бейджа, который необходимо назначить пользователю или пользователям

В body запроса нужно отправить обязательный JSON объект userId, в котором перечислены уникальные идентификаторы пользователей (массив, должны совпадать c выбранным уникальным идентификатором на платформе)

Пример:

{ "userId": [ "example@example.ru", "example2@example.ru" ] }

В случае успешного запроса (200) в ответ придёт JSON объект со следующими полями:

  • result – значение true

  • data – массив данных по каждому пользователю, который был передан в запросе:

    • id – идентификатор пользователя

    • success

      • false – если пользователь не существует или удалён, и ему не был начислен бейдж

      • true – если пользователь существует, не удалён, ему был начислен бейдж (или он уже был начислен ранее)

    • error

      • "User not found" – если пользователь не существует или удалён

      • "User already has a higher grade badge, remove it first" – если у пользователю пытаются назначить многоуровневый бейдж более низкого уровня при наличии у него более высокого

      • null – для статуса true, при успешном начислении бейджа

Возвращается, если бейдж существует и может быть назначен пользователям

{ "result" : true, "data" : [ { "id" : "example@mail.com", "success" : true, "error" : null }, { "id" : "example1@mail.com", "success" : false, "error" : "User not found" } ] }

В случае неудачного запроса (400), т.е. при попытке назначить пользователям бейдж, который нельзя назначить, или при отсутствии обязательного параметра (идентификаторов пользователей), возвращается ответ, в котором перечисляются все ошибки в виде объектов в массиве errors с сообщением об ошибке и указанием на элемент, в котором возникла ошибка.

В зависимости от конкретной ошибки, message может отличаться.

Возможные ошибки:

  • Обязательный параметр не заполнен или заполнен некорректно

    • "message": "Required parameters are not filled in",

    • "cause" : "userId"

  • Бейдж не существует или удалён

    • "message": "Badge not found",

    • "cause" : "badgeId"

  • Бейдж неактивен

    • "message": "An inactive badge cannot be assigned",

    • "cause" : "badgeId"

  • Бейдж является системным

    • "message": "A system badge cannot be assigned",

    • "cause" : "badgeId"

  • Бейдж является родительским для многоуровневого бейджа

    • "message": "Select the badge grade for the assignment",

    • "cause" : "badgeId"

{ "errors": [ { “message”: “Required parameters are not filled in“, “cause” : “User ID is required“ }, { “message”: “An inactive badge cannot be assigned“, “cause” : “98“ } ] }

Возвращается в случае отсутствия или некорректного публичного ключа API при запросе

{ "result": false, "message": "Invalid public API token" }

Снятие бейджа с пользователя

Бейдж снимается с пользователя, если:

  • Пользователь существует и не удален, статус активности пользователя не важен

  • Бейдж не является системным

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

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

Чтобы снять бейдж пользователю, нужно сделать POST запрос на адрес:

  • post /public/api/v1/badge/{badgeId}/remove
    в {badgeId} должен передаваться ID бейджа, который необходимо снять с пользователя или с пользователей

В body запроса нужно отправить обязательный JSON объект userId, в котором перечислены уникальные идентификаторы пользователей (массив, должны совпадать c выбранным уникальным идентификатором на платформе)

Пример:

{ "userId": [ "example@example.ru", "example2@example.ru", "example3@example.ru" ] }

В случае успешного запроса (200) в ответ придёт JSON объект со следующими полями:

  • result – значение true

  • data – массив данных по каждому пользователю, который был передан в запросе:

    • id – идентификатор пользователя

    • success

      • false – если пользователь не существует или удалён, и с него не был снят бейдж

      • true – если пользователь существует, не удалён, бейдж был с него снят (или этого бейджа у него и не было)

    • error

      • "User not found" – если пользователь не существует или удалён

      • null – для статуса true, при успешном снятии бейджа

Возвращается, если бейдж существует и может быть снят у пользователей администратором.

{ "result" : true, "data" : [ { "id" : "example@mail.com", "success" : true, "error" : null }, { "id" : "example1@mail.com", "success" : false, "error" : "User not found" } ] }

В случае неудачного запроса (400), т.е. при попытке снять с пользователей бейдж, который нельзя снять, или при отсутствии обязательного параметра (идентификаторов пользователей), возвращается ответ, в котором перечисляются все ошибки в виде объектов в массиве errors с сообщением об ошибке и указанием на элемент, в котором возникла ошибка.

В зависимости от конкретной ошибки, message может отличаться.

Возможные ошибки: