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

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

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

В панели администрирования публичный ключ API отображается в разделе Настройки → Лицензия.

При отсутствии публичного ключа API, либо если он указан неверно, в запросах возвращается ошибка 401 Authorization Required

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

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

Отчеты

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

Чтобы получить список всех доступных отчётов, нужно сделать 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 — адрес, на который нужно делать запрос для получения списка значений и поиска по нему);

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

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

Чтобы сгенерировать и получить отчёт, нужно отправить 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, в котором будут поля, ключами которых будут Системные имена фильтров, полученных на этапе Получения метаданных, а значениями непосредственно значения фильтров (цифра, строка, массив и тд)

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

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

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

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

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

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

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

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

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

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

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

Бейджи

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

Чтобы получить информацию об имеющихся на платформе бейджах, нужно сделать 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

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

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

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

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

Пример:

В случае успешного запроса (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, при успешном начислении бейджа

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

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

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

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

Пример:

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

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

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

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

  • success

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

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

  • error

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

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

План развития

Получение информации о текущем состоянии целей пользователя

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

• GET /public/api/v1/goals/user/{userId}(?type=active|completed|all)
  в адресе метода должны быть указаны следующие параметры:

  • userId – уникальный идентификатор пользователя, должен совпадать c выбранным уникальным идентификатором на платформе, STRING. Обязательный параметр

  • type – тип цели, информацию по которой надо вернуть. Необязательный параметр, при отсутствии возвращаются все цели пользователя. Возможные значения:

    • active – все незавершённые цели пользователя (значения completedAt и completedBy в базе данных Null)

    • completed – все завершённые цели пользователя

    • all – все цели пользователя (кроме удалённых)

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

• result – должно вернуться значение true

• items – массив всех целей пользователя указанного типа. Может вернуться пустой массив, если у пользователя нет неудалённых целей

  • id – уникальный идентификатор цели, по которому можно обратиться к ней для изменения, STRING

  • title – название цели, STRING

  • value – целевое значение цели, INT

  • progress – текущее значение цели, INT

  • priority – приоритет, установленный для цели, возможные значения - high, medium, low, STRING

  • deadlineAt – дедлайн цели с указанием даты наступления дела в формате ISO 8601 с указанием таймзоны, DATETIME

  • valueUnit – единица измерения значений цели, возможные значения – percents, numbers, roubles, dollars, euros, hours, STRING

  • inRisk – находится ли цель в зоне риска, возможные значение – true или false, boolean. Для ключевых результатов – наследуется из родительской цели

  • approvedAt:

    • Дата и время подтверждения цели в формате ISO 8601 с указанием таймзоны, если руководитель или HR-сотрудник подтвердил цель, DATETIME

    • null – если цель не была подтверждена руководителем или HR-сотрудником

    • Для ключевых результатов – наследуется из родительской цели

  • approvedById:

    • Идентификатор сотрудника, который подтвердил цель, если она подтверждена, STRING

    • null – если цель не была подтверждена руководителем или HR-сотрудником

    • Для ключевых результатов – наследуется из родительской цели

  • completedAt:

    • Дата и время завершения цели в формате ISO 8601 с указанием таймзоны, если цель завершена, DATETIME

    • null – если цель не завершена

    • Для ключевых результатов – наследуется из родительской цели

  • completedById:

    • Идентификатор сотрудника, который завершил цель, если она завершена, STRING

    • null – если цель не была завершена

    • Для ключевых результатов – наследуется из родительской цели

  • keyResults:

    • Массив всех ключевых результатов, если они заданы. Структура каждого элемента массива результатов повторяет структуру элемента массива цели

    • null – если для цели не заданы ключевые результаты или цель сама является ключевым результатом

• limit – максимальное количество активных целей, которое может быть создано для одного пользователя

• countActive – количество текущих активных целей пользователя. Значение должно возвращаться даже если в запросе запрашивается информация только по завершённым целям пользователя.

Cоздания новых целей для пользователей

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

• post /public/api/v1/goals/user/{userId}
  в адресе метода должен быть указан параметр userId – уникальный идентификатор пользователя, должен совпадать c выбранным уникальным идентификатором на платформе, STRING. Обязательный параметр

В body запроса нужно отправить обязательный JSON, каждый элемент которого должен содержать следующие параметры:

• authorId – уникальный идентификатор пользователя, от имени которого должна быть создана цель, STRING. Обязательный параметр. Возможные значения:

  • Совпадает с userId, если цель должна быть создана от имени пользователя

  • Совпадает с id руководителя пользователя или пользователя с разрешением План развития \ Управление целями и планами. Если цель создаётся от руководителя или пользователя с указанным разрешением, она сразу должна создаваться подтверждённой

• title – название цели, STRING, до 3000 символов. Обязательный параметр

• value – целевое значение цели, целое положительное число больше 0, до 10 символов, INTEGER

  • Обязательное, если для цели нет ключевых значений

  • null, если для цели есть ключевые значения

  • Другие значения value для цели будут игнорироваться, для цели устанавливается значение 100

• valueUnit – единица измерения значений цели, возможные значения – percents, numbers, roubles, dollars, euros, hours, STRING

  • Обязательное, если для цели нет ключевых значений.

  • null, если для цели есть ключевые значения

  • Другие значения valueUnit для цели будут игнорируется, для цели устанавливается значение percents

• priority – приоритет цели, возможные значения - high, medium, low, STRING. Обязательный параметр

• deadlineAt – дедлайн цели в формате ISO 8601 с указанием таймзоны, должен быть больше текущего дня, DATETIME. Обязательный параметр. Время учитывается только для выставление корректной даты в соответствии с таймзонами, все уведомления о дедлайнах будут отправляться пользователю относительно 00:00 указанной даты.

• keyResults – массив объектов для указания ключевых результатов цели. Обязательный:

  • null, если для цели не должны быть заданы ключевые параметры

  • Если передаётся массив, то для каждого элемента массива должны быть указаны следующие параметры (требования к ним см. выше):

    • title

    • value

    • valueUnit

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

• result – должно вернуться значение true

• userId – идентификатор пользователя, для которого производились изменения

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

  • success:

    • true, если цель была успешно создана

    • false, если цель не удалось создать

  • goal – null, если цель не была создана, иначе массив всех созданных целей пользователя:

    • id – уникальный идентификатор цели, по которому можно обратиться к ней для изменения, STRING

    • title – название цели, STRING

    • value – целевое значение цели, INT

    • progress – текущее значение цели, INT

    • priority – приоритет, установленный для цели, возможные значения - high, medium, low, STRING

    • deadlineAt – дедлайн цели с указанием даты наступления дела в формате ISO 8601 с указанием таймзоны, DATETIME

    • valueUnit – единица измерения значений цели, возможные значения – percents, numbers, roubles, dollars, euros, hours, STRING

    • inRisk – находится ли цель в зоне риска, возможные значение – true или false, boolean. Для ключевых результатов – наследуется из родительской цели

    • approvedAt:

      • Дата и время подтверждения цели в формате ISO 8601 с указанием таймзоны, если руководитель или HR-сотрудник подтвердил цель, DATETIME

      • null – если цель не была подтверждена руководителем или HR-сотрудником

      • Для ключевых результатов – наследуется из родительской цели

    • approvedById:

      • Идентификатор сотрудника, который подтвердил цель, если она подтверждена, STRING

      • null – если цель не была подтверждена руководителем или HR-сотрудником

      • Для ключевых результатов – наследуется из родительской цели

    • completedAt:

      • Дата и время завершения цели в формате ISO 8601 с указанием таймзоны, если цель завершена, DATETIME

      • null – если цель не завершена

      • Для ключевых результатов – наследуется из родительской цели

    • completedById:

      • Идентификатор сотрудника, который завершил цель, если она завершена, STRING

      • null – если цель не была завершена

      • Для ключевых результатов – наследуется из родительской цели

    • keyResults:

      • Массив всех ключевых результатов, если они заданы. Структура каждого элемента массива результатов повторяет структуру элемента массива цели

      • null – если для цели не заданы ключевые результаты или цель сама является ключевым результатом

  • errors – null, если цель была создана успешно, массив ошибок, если цель создать не удалось. Возможные ошибки:

    • Обязательный параметр не заполнен или заполнен некорректно (если таких параметров несколько, по каждому должна вернуться своя ошибка. Для ошибки параметра внутри ключевого результата должен возвращаться путь до параметра внутри структуры в JSON в формате keyResults.0.title)

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

      • "cause" : "идентификатор_параметра"
        Например:

        • Если в поле deadlineAt некорректные данные (не тот формат, дата в прошлом)

          • "message": "Invalid date. You can only specify the current and future date"

          • "cause": "deadlineAt"

        • Если в поле priority некорректные данные

          • "message": "Invalid value. Allowed values: high, medium, low"

          • "cause": "priority"

        • Если в поле value = 0

          • "message": "Invalid value. Value should be greater than 0"

          • "cause": "keyResults[0].value"

        • Если в поле value или keyResults[0].value больше 10 символов

          • "message": "Value is too long. Allowed length 10 characters"

          • "cause": "value"

    • Пользователь (userId или authorId) деактивирован, не существует или удалён:

      • "message": "User not found",

      • "cause" : "userId или authorId"

    • Лимит целей для пользователя достигнут, новые цели создать нельзя:

      • "message": "Goal limit reached",

      • "cause" : "значение_limit"

    • В качестве автора указан пользователь, который не может создавать цели данному сотруднику:

      • "message": "Author has no rights to create goals",

      • "cause" : "authorId"

Изменение созданной цели пользователя

Чтобы изменить созданную цель пользователя, нужно сделать PUT запрос на адрес:

• pUt /public/api/v1/goals/{goalId}
  в адресе метода должен быть указан параметр goalId – уникальный идентификатор цели, должен совпадать c выбранным уникальным идентификатором на платформе, STRING. Обязательный параметр

В body запроса нужно отправить обязательный JSON, каждый элемент которого должен содержать следующие параметры:

• authorId – уникальный идентификатор пользователя, от имени которого должна быть изменена цель, STRING. Обязательный параметр. Возможные значения:

  • Совпадает с id пользователя, цель которого редактируется. Изменения будут применены только для неподтверждённых целей

  • Совпадает с id руководителя пользователя или пользователя с разрешением План развития \ Управление целями и планами

• title – название цели, STRING, до 3000 символов:

  • Новое значение, если title необходимо изменить

  • null, если title менять не нужно

• value – целевое значение цели, целое положительное число больше 0, до 10 символов, INTEGER

  • Новое значение, если value необходимо изменить

  • null, если value менять не нужно или для цели есть ключевые значения

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

• progress – текущее значение цели, которое необходимо установить. Целое положительное число больше 0, INTEGER

  • Новое значение, если progress необходимо изменить

  • null, если progress менять не нужно или для цели есть ключевые значения

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

• valueUnit – единица измерения значений цели, возможные значения – percents, numbers, roubles, dollars, euros, hours, STRING

  • Новое значение, если valueUnit необходимо изменить

  • null, если valueUnit менять не нужно или для цели есть ключевые значения

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

• priority – приоритет цели, возможные значения – high, medium, low, STRING

  • Новое значение, если priority необходимо изменить

  • null, если priority менять не нужно или для цели, которая является ключевым значением

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

• deadlineAt – дедлайн цели в формате ISO 8601 с указанием таймзоны, должен быть больше текущего дня, DATETIME

  • Новое значение, если deadlineAt необходимо изменить

  • null, если deadlineAt менять не нужно или для цели является ключевым значением

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

• keyResults – массив объектов для указания ключевых результатов цели. Необходим если нужно добавить в цель новые ключевые результаты. Если необходимо отредактировать созданные ключевые результаты, необходимо обращаться к ним по goalId. Игнорируется для ключевых результатов цели

  • null, если в цель не надо добавлять ключевые значения

  • Если заполнен, то для каждого элемента массива должны быть указаны следующие параметры (требования к ним см. выше):

    • title

    • value

    • valueUnit

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

• result – должно вернуться значение true

• goal :

  • id – уникальный идентификатор цели, STRING

  • title – название цели, STRING

  • value – целевое значение цели, INT

  • progress – текущее значение цели, INT

  • priority – приоритет, установленный для цели, возможные значения - high, medium, low, STRING

  • deadlineAt – дедлайн цели с указанием даты наступления дела в формате ISO 8601 с указанием таймзоны, DATETIME

  • valueUnit – единица измерения значений цели, возможные значения – percents, numbers, roubles, dollars, euros, hours, STRING

  • inRisk – находится ли цель в зоне риска, возможные значение – true или false, boolean. Для ключевых результатов – наследуется из родительской цели

  • approvedAt:

    • Дата и время подтверждения цели в формате ISO 8601 с указанием таймзоны, если руководитель или HR-сотрудник подтвердил цель, DATETIME

    • null – если цель не была подтверждена руководителем или HR-сотрудником

    • Для ключевых результатов – наследуется из родительской цели

  • approvedById:

    • Идентификатор сотрудника, который подтвердил цель, если она подтверждена, STRING

    • null – если цель не была подтверждена руководителем или HR-сотрудником

    • Для ключевых результатов – наследуется из родительской цели

  • completedAt:

    • Дата и время завершения цели в формате ISO 8601 с указанием таймзоны, если цель завершена, DATETIME

    • null – если цель не завершена

    • Для ключевых результатов – наследуется из родительской цели

  • completedById:

    • Идентификатор сотрудника, который завершил цель, если она завершена, STRING

    • null – если цель не была завершена

    • Для ключевых результатов – наследуется из родительской цели

  • keyResults:

    • Массив всех ключевых результатов, если они заданы. Структура каждого элемента массива результатов повторяет структуру элемента массива цели

    • null – если для цели не заданы ключевые результаты или цель сама является ключевым результатом

Подтверждение цели пользователя

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

• post /public/api/v1/goals/{goalId}/approve
  в адресе метода должен быть указан параметр goalId – уникальный идентификатор цели, должен совпадать c выбранным уникальным идентификатором на платформе, STRING. Обязательный параметр

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

• authorId – уникальный идентификатор пользователя, от имени которого должна быть подтверждена цель, STRING. Обязательный параметр. Должен совпадать с id руководителя пользователя или пользователя с разрешением План развития \ Управление целями и планами.

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

• result – должно вернуться значение true

• goal :

  • id – уникальный идентификатор цели, STRING

  • title – название цели, STRING

  • value – целевое значение цели, INT

  • progress – текущее значение цели, INT

  • priority – приоритет, установленный для цели, возможные значения - high, medium, low, STRING

  • deadlineAt – дедлайн цели с указанием даты наступления дела в формате ISO 8601 с указанием таймзоны, DATETIME

  • valueUnit – единица измерения значений цели, возможные значения – percents, numbers, roubles, dollars, euros, hours, STRING

  • inRisk – находится ли цель в зоне риска, возможные значение – true или false, boolean. Для ключевых результатов – наследуется из родительской цели

  • approvedAt:

    • Дата и время подтверждения цели в формате ISO 8601 с указанием таймзоны, если руководитель или HR-сотрудник подтвердил цель, DATETIME

    • null – если цель не была подтверждена руководителем или HR-сотрудником

    • Для ключевых результатов – наследуется из родительской цели

  • approvedById:

    • Идентификатор сотрудника, который подтвердил цель, если она подтверждена, STRING

    • null – если цель не была подтверждена руководителем или HR-сотрудником

    • Для ключевых результатов – наследуется из родительской цели

  • completedAt:

    • Дата и время завершения цели в формате ISO 8601 с указанием таймзоны, если цель завершена, DATETIME

    • null – если цель не завершена

    • Для ключевых результатов – наследуется из родительской цели

  • completedById:

    • Идентификатор сотрудника, который завершил цель, если она завершена, STRING

    • null – если цель не была завершена

    • Для ключевых результатов – наследуется из родительской цели

  • keyResults:

    • Массив всех ключевых результатов, если они заданы. Структура каждого элемента массива результатов повторяет структуру элемента массива цели

    • null – если для цели не заданы ключевые результаты или цель сама является ключевым результатом

Завершение цели пользователя

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

• post /public/api/v1/goals/{goalId}/complete
  в адресе метода должен быть указан параметр goalId – уникальный идентификатор цели, должен совпадать c выбранным уникальным идентификатором на платформе, STRING. Обязательный параметр

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

• authorId – уникальный идентификатор пользователя, от имени которого должна быть завершена цель, STRING. Обязательный параметр. Должен совпадать с id руководителя пользователя или пользователя с разрешением План развития \ Управление целями и планами.

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

• result – должно вернуться значение true

• goal :

  • id – уникальный идентификатор цели, STRING

  • title – название цели, STRING

  • value – целевое значение цели, INT

  • progress – текущее значение цели, INT

  • priority – приоритет, установленный для цели, возможные значения - high, medium, low, STRING

  • deadlineAt – дедлайн цели с указанием даты наступления дела в формате ISO 8601 с указанием таймзоны, DATETIME

  • valueUnit – единица измерения значений цели, возможные значения – percents, numbers, roubles, dollars, euros, hours, STRING

  • inRisk – находится ли цель в зоне риска, возможные значение – true или false, boolean. Для ключевых результатов – наследуется из родительской цели

  • approvedAt:

    • Дата и время подтверждения цели в формате ISO 8601 с указанием таймзоны, если руководитель или HR-сотрудник подтвердил цель, DATETIME

    • null – если цель не была подтверждена руководителем или HR-сотрудником

    • Для ключевых результатов – наследуется из родительской цели

  • approvedById:

    • Идентификатор сотрудника, который подтвердил цель, если она подтверждена, STRING

    • null – если цель не была подтверждена руководителем или HR-сотрудником

    • Для ключевых результатов – наследуется из родительской цели

  • completedAt:

    • Дата и время завершения цели в формате ISO 8601 с указанием таймзоны, если цель завершена, DATETIME

    • null – если цель не завершена

    • Для ключевых результатов – наследуется из родительской цели

  • completedById:

    • Идентификатор сотрудника, который завершил цель, если она завершена, STRING

    • null – если цель не была завершена

    • Для ключевых результатов – наследуется из родительской цели

  • keyResults:

    • Массив всех ключевых результатов, если они заданы. Структура каждого элемента массива результатов повторяет структуру элемента массива цели

    • null – если для цели не заданы ключевые результаты или цель сама является ключевым результатом

Удаление созданной цели пользователя

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

• post /public/api/v1/goals/{goalId}/delete
  в адресе метода должен быть указан параметр goalId – уникальный идентификатор цели, должен совпадать c выбранным уникальным идентификатором на платформе, STRING. Обязательный параметр

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

• authorId – уникальный идентификатор пользователя, от имени которого должна быть удалена цель, STRING. Обязательный параметр. Должен совпадать с id руководителя пользователя или пользователя с разрешением План развития \ Управление целями и планами.

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

• result – должно вернуться значение true

• message – сообщение об успешном удалении цели

Баллы

Изменение баланса баллов пользователя

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

• POST /public/api/v1/points/
  в заголовках запроса можно передать параметр Locale, который будет использоваться для выбора языка при подстановке формулировки начисления баллов по умолчанию, если в теле запроса не был передан параметр message

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

• userId – уникальный идентификатор пользователя, должен совпадать c выбранным уникальным идентификатором на платформе, STRING. Обязательный параметр.

• balanceType – тип баланса, который необходимо изменить. Допустимые значения: score, karma, payment, STRING. Обязательный параметр.

• amount – значение, на которое необходимо изменить баланс, целое число, отрицательное или положительное, INT. Обязательный параметр.

• message – формулировка для отображения в личном кабинете, до 80 символов, STRING. Необязательный параметр. Если параметр не передаётся, используется формулировка по умолчанию на языке, переданном в заголовке или установленном для платформы как язык по умолчанию.

Пример:

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

• result – со значением true

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

  • userId – идентификатор пользователя, для которого производились изменения

  • balanceType – тип баланса, с которым производились изменения

  • success:

    • true если баланс баллов был изменён успешно

    • false если баланс баллов изменить не удалось

  • balance:

    • Значение баланса после изменения, если он был изменён успешно, или его текущее значение, если баланс баллов изменить не удалось

    • null, если пользователь не найден или был указан некорректный balanceType

  • errors – null, если баланс баллов был изменён успешно, массив ошибок, если баланс баллов изменить не удалось. Возможные ошибки:

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

      • "message": "User not found",

      • "cause" : "userId"

    • Обязательный параметр не заполнен или заполнен некорректно (если таких параметров несколько, по каждому должна вернуться своя ошибка):

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

      • "cause" : "идентификатор_параметра"

    • Значение баланса не является целым числом

      • "message": "The "amount" field must contain an integer value",

      • "cause" : "amount"

    • При попытке вычесть из баланса больше баллов, чем есть у пользователя

      • "message": "Attempting to deduct more than the available points",

      • "cause" : "amount"

    • Тип баланса не совпадает с возможными значениями или в методе указан баланс каталога призов payment при неподключенном модуле Каталог призов

      • "message": "Balance not found",

      • "cause" : "balanceType"

    • Длина формулировки превышает 80 символов

      • "message": "The length of the "message" field cannot exceed 80 characters",

      • "cause" : "message"

Файлы

Скачивание файла по его уникальному идентификатору

Для скачивания файла по его идентификатору, нужно сделать POST запрос на адрес:

• post /public/api/v1/file/{fileId}
  в адресе метода должен быть указан следующий параметр:

  • fileId – внутренний идентификатор файла, используемого на платформе Мотивити (прикреплённые к заданию, комментарию, записи в пульсе, элементу в библиотеке и пр.), INT

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

• result – со значением true

• fileId – идентификатор файла из запроса, INT

• file – данные файла, STRING

Загрузка файла и получение его уникального идентификатора

Для загрузки файла и получения его идентификатора, нужно сделать POST запрос на адрес:

• post /public/api/v1/file/upload
  В header запроса требуется указать заголовки, где file_name – название файла, file_type – формат файла, например, file=@new.jpg;type=image\jpg:

  Content-Type: multipart/form-data file=@file_name;type=file_type

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

• result – со значением true

• file – ключ структуры информации о файле со следующими элементами:

  • id – уникальный идентификатор файла, INT

  • name – полное название файла с расширением, STRING

  • size – размер файла в байтах, INT

Квесты

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

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

GET /public/api/v1/quest/{questId}/task

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

  • questId – уникальный идентификатор неудалённого активного квеста, доступного в публичной части по датам видимости, INT. Обязательный параметр

• дополнительно в query-параметрах могут быть указаны следующие фильтры:

  • studentId – уникальный идентификатор пользователя, задания которого необходимо вернуть, STRING. Необязательный параметр, при отсутствии возвращаются задания для всех неудалённых активных студентов указанного квеста

  • taskId – уникальный идентификатор задания, информацию по которому необходимо вернуть, INT. Необязательный параметр, при отсутствии возвращаются все задания

  • status – статус задания, информацию по которому надо вернуть. Необязательный параметр, можно передавать массив статусов, при отсутствии должны быть возвращены все задания, назначенные в рамках квеста на неудалённых активных пользователей. Возможные значения:

    • in_progress – работа по заданию не проводилась или задание было переназначено

    • checking – задание отправлено на проверку наставнику

    • redo – задание было возвращено на доработку

    • complete – задание было успешно завершено

    • fail – задание было провалено

  • page – номер страницы с результатами, которую необходимо вернуть. Необязательный параметр, при отсутствии возвращается первая страница, INT

  • pageSize – количество результатов на одной странице, целое значение от 1 до 100, INT. Необязательный параметр, при отсутствии возвращается 20 результатов на странице

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

• result – со значением true

• quest – ключ структуры информации по квесту со следующими элементами:

  • id – уникальный идентификатор квеста, INT

  • title – заголовок квеста, STRING

  • textForMentor – текст для наставника, STRING

  • urlForMentor – ссылка для наставника, может быть null, STRING

  • textForStudent – текст для студента, может быть null, STRING

  • previewImage – ключ структуры информации о файле со следующими элементами:

    • id – уникальный идентификатор файла, INT

    • name – полное название файла с расширением, STRING

    • size – размер файла в байтах, INT

  • mentors – массив уникальных идентификатор пользователей, ответственных за квест, может быть null, каждый элемент STRING

  • open – дата начала доступности квеста, может быть null, DATETIME

  • close – дата окончания доступности квеста, может быть null, DATETIME

  • deadlineType – тип дедлайна, возможные значения: 'date' (до определённой даты), 'delay' (спустя установленное количество дней после назначения), 'none' (не установлен)

  • deadlineDelay – количество дней, за которые надо пройти квест после назначения, для delay, иначе null, INT

  • deadlineDate – дата, до которой надо пройти квест, для date, иначе null, DATETIME

  • threshold – порог, за прохождение которого студент получит баллы, может быть null, INT

  • scoreThreshold – количество баллов, которые студент получает при прохождении квеста на пороговом значении, может быть null, INT

  • score – баллы за прохождение квеста на 100 процентов, может быть null, INT

  • certificate – уникальный идентификатор сертификата за прохождение квеста на указанное количество процентов, может быть null, INT

  • certificateCompleted – уникальный идентификатор сертификата за прохождение квеста на 100 процентов, может быть null, INT

  • mentorScore – баллы для наставника за прохождение его студентом квеста на 100 процентов, может быть null, INT

  • scoreInTime – баллы за прохождение квеста в дедлайн, может быть null, INT

  • certificateDeadline – уникальный идентификатор сертификата за прохождение квеста в дедлайн, может быть null, INT

  • quizId – идентификатор прикреплённого опроса, может быть null, INT

• items – массив всех заданий, которые назначены пользователям в рамках указанного квеста

  • task – ключ структуры информации по заданию со следующими элементами:

    • id – уникальный идентификатор задания, INT

    • title – заголовок задания, STRING

    • summary – краткое описание задания, может быть null, STRING

    • text – полное описание задания, STRING

    • mentorTip – заметки для наставника, может быть null, STRING

    • score – количество баллов за успешное прохождение задания, может быть null, INT

    • previewImage – ключ структуры информации о файле со следующими элементами:

      • id – уникальный идентификатор файла, INT

      • name – полное название файла с расширением, STRING

      • size – размер файла в байтах, INT

    • quizId – идентификатор прикреплённого опроса, может быть null, INT

  • studentId – пользователь, которому было назначено задание в рамках указанного квеста, STRING

  • taskStatus – статус, в котором в настоящий момент находится задание у указанного пользователя. Возможные значения:

    • in_progress – работа по заданию не проводилась или задание было переназначено

    • checking – задание отправлено на проверку наставнику

    • redo – задание было возвращено на доработку

    • complete – задание было успешно завершено

    • fail – задание было провалено

• pagination – стандартный элемент с данными следующей структуры:

  • currentPage – номер текущей страницы с данными, возвращённой в запросе

  • recordsPerPage – количество записей на странице

  • totalRecords – общее количество записей по запросу с выбранными фильтрами

  • totalPages – общее количество страниц с записями по запросу с выбранными фильтрами

Получение информации об ответе пользователя на задание

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

• GET /public/api/v1/quest/{questId}/task/{taskId}/student/{studentId}
  в адресе метода должны быть указаны следующие параметры:

  • questId – идентификатор неудалённого активного квеста, доступного в публичной части по датам видимости, в котором находится необходимое задание, INT,

  • studentId – уникальный идентификатор неудалённого активного пользователя, которому назначен квест, STRING,

  • taskId – идентификатор задания, для которого запрашивается информация, INT

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

• result – со значением true

• quest – ключ структуры информации по квесту со следующими элементами:

  • id – уникальный идентификатор квеста, INT

  • title – заголовок квеста, STRING

  • textForMentor – текст для наставника, STRING

  • urlForMentor – ссылка для наставника, может быть null, STRING

  • textForStudent – текст для студента, может быть null, STRING

  • previewImage – ключ структуры информации о файле со следующими элементами:

    • id – уникальный идентификатор файла, INT

    • name – полное название файла с расширением, STRING

    • size – размер файла в байтах, INT

  • mentors – массив уникальных идентификатор пользователей, ответственных за квест, может быть null, каждый элемент STRING

  • open – дата начала доступности квеста, может быть null, DATETIME

  • close – дата окончания доступности квеста, может быть null, DATETIME

  • deadlineType – тип дедлайна, возможные значения: 'date' (до определённой даты), 'delay' (спустя установленное количество дней после назначения), 'none' (не установлен)

  • deadlineDelay – количество дней, за которые надо пройти квест после назначения, для delay, иначе null, INT

  • deadlineDate – дата, до которой надо пройти квест, для date, иначе null, DATETIME

  • threshold – порог, за прохождение которого студент получит баллы, может быть null, INT

  • scoreThreshold – количество баллов, которые студент получает при прохождении квеста на пороговом значении, может быть null, INT

  • score – баллы за прохождение квеста на 100 процентов, может быть null, INT

  • certificate – уникальный идентификатор сертификата за прохождение квеста на указанное количество процентов, может быть null, INT

  • certificateCompleted – уникальный идентификатор сертификата за прохождение квеста на 100 процентов, может быть null, INT

  • mentorScore – баллы для наставника за прохождение его студентом квеста на 100 процентов, может быть null, INT

  • scoreInTime – баллы за прохождение квеста в дедлайн, может быть null, INT

  • certificateDeadline – уникальный идентификатор сертификата за прохождение квеста в дедлайн, может быть null, INT

  • quizId – идентификатор прикреплённого опроса, может быть null, INT

• data:

  • messages – массив ответов на задание (как со стороны студента, так и со стороны его наставника). Если на задание ещё не было дано ни одного ответа, вместо массива возвращается null. Каждый элемент массива должен содержать следующие поля:

    • authorId – уникальный идентификатор пользователя, который оставил сообщение для задания, STRING

    • date – дата и время оставления сообщения, DATETIME

    • text – текст оставленного сообщения, STRING

    • status – статус, в который было переведено задание после отправки сообщения

    • files – массив данных по файлам, прикреплённых к сообщению, или null, если файлы не были прикреплены. Для каждого элемента массива должна быть передана следующая информация:

      • id – идентификатор файла, который можно использовать для его скачивания в отдельном методе, INT

      • name – полное название файла с расширением, STRING

      • size – размер файла в байтах, INT

  • studentId – идентификатор студента из запроса, STRING

  • task – ключ структуры информации по заданию со следующими элементами:

    • id – уникальный идентификатор задания, INT

    • title – заголовок задания, STRING

    • summary – краткое описание задания, может быть null, STRING

    • text – полное описание задания, STRING

    • mentorTip – заметки для наставника, может быть null, STRING

    • score – количество баллов за успешное прохождение задания, может быть null, INT

    • previewImage – ключ структуры информации о файле со следующими элементами:

      • id – уникальный идентификатор файла, INT

      • name – полное название файла с расширением, STRING

      • size – размер файла в байтах, INT

    • quizId – идентификатор прикреплённого опроса, может быть null, INT

  • taskStatus – текущий статус выполнения задания, возможные значения - in_progress, checking, redo, complete, fail

Отправка ответа на задание пользователя

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

• post /public/api/v1/quest/{questId}/task/{taskId}/student/{studentId}
  в адресе метода должны быть указаны следующие параметры:

  • questId – идентификатор неудалённого активного квеста, доступного в публичной части по датам видимости, в котором находится необходимое задание, INT,

  • studentId – уникальный идентификатор неудалённого активного пользователя, которому назначен квест, STRING,

  • taskId – идентификатор задания, для которого запрашивается информация, INT

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

• mentorId – уникальный идентификатор пользователя, от имени которого должен быть оставлен ответ на задание, обязательное, STRING

• text – текст ответа, который необходимо оставить пользователю, до 6000 символов, необязательное, STRING

• files – массив идентификаторов файлов, которые необходимо прикрепить к ответу, необязательное

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

  • redo – задание необходимо доработать

  • complete – задание пройдено успешно

  • fail – задание не пройдено

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

• result – со значением true

• quest – ключ структуры информации по квесту со следующими элементами:

  • id – уникальный идентификатор квеста, INT

  • title – заголовок квеста, STRING

  • textForMentor – текст для наставника, STRING

  • urlForMentor – ссылка для наставника, может быть null, STRING

  • textForStudent – текст для студента, может быть null, STRING

  • previewImage – ключ структуры информации о файле со следующими элементами:

    • id – уникальный идентификатор файла, INT

    • name – полное название файла с расширением, STRING

    • size – размер файла в байтах, INT

  • mentors – массив уникальных идентификатор пользователей, ответственных за квест, может быть null, каждый элемент STRING

  • open – дата начала доступности квеста, может быть null, DATETIME

  • close – дата окончания доступности квеста, может быть null, DATETIME

  • deadlineType – тип дедлайна, возможные значения: 'date' (до определённой даты), 'delay' (спустя установленное количество дней после назначения), 'none' (не установлен)

  • deadlineDelay – количество дней, за которые надо пройти квест после назначения, для delay, иначе null, INT

  • deadlineDate – дата, до которой надо пройти квест, для date, иначе null, DATETIME

  • threshold – порог, за прохождение которого студент получит баллы, может быть null, INT

  • scoreThreshold – количество баллов, которые студент получает при прохождении квеста на пороговом значении, может быть null, INT

  • score – баллы за прохождение квеста на 100 процентов, может быть null, INT

  • certificate – уникальный идентификатор сертификата за прохождение квеста на указанное количество процентов, может быть null, INT

  • certificateCompleted – уникальный идентификатор сертификата за прохождение квеста на 100 процентов, может быть null, INT

  • mentorScore – баллы для наставника за прохождение его студентом квеста на 100 процентов, может быть null, INT

  • scoreInTime – баллы за прохождение квеста в дедлайн, может быть null, INT

  • certificateDeadline – уникальный идентификатор сертификата за прохождение квеста в дедлайн, может быть null, INT

  • quizId – идентификатор прикреплённого опроса, может быть null, INT

• data:

  • messages – массив ответов на задание (как со стороны студента, так и со стороны его наставника). Если на задание ещё не было дано ни одного ответа, вместо массива возвращается null. Каждый элемент массива должен содержать следующие поля:

    • authorId – уникальный идентификатор пользователя, который оставил сообщение для задания, STRING

    • date – дата и время оставления сообщения, DATETIME

    • text – текст оставленного сообщения, STRING

    • status – статус, в который было переведено задание после отправки сообщения

    • files – массив данных по файлам, прикреплённых к сообщению, или null, если файлы не были прикреплены. Для каждого элемента массива должна быть передана следующая информация:

      • id – идентификатор файла, который можно использовать для его скачивания в отдельном методе, INT

      • name – полное название файла с расширением, STRING

      • size – размер файла в байтах, INT

  • studentId – идентификатор студента из запроса, STRING

  • task – ключ структуры информации по заданию со следующими элементами:

    • id – уникальный идентификатор задания, INT

    • title – заголовок задания, STRING

    • summary – краткое описание задания, может быть null, STRING

    • text – полное описание задания, STRING

    • mentorTip – заметки для наставника, может быть null, STRING

    • score – количество баллов за успешное прохождение задания, может быть null, INT

    • previewImage – ключ структуры информации о файле со следующими элементами:

      • id – уникальный идентификатор файла, INT

      • name – полное название файла с расширением, STRING

      • size – размер файла в байтах, INT

    • quizId – идентификатор прикреплённого опроса, может быть null, INT

  • taskStatus – текущий статус выполнения задания, возможные значения - in_progress, checking, redo, complete, fail