HELP CENTER SMART WAY LMS

Найдите ответы и полезные инструкции.

Популярные темы: API Настройки Пользователи

Просмотр по темам

Найдите нужную информацию по категориям.

📁

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

Как добавлять пользователей? Как удалять? Как редактировать? Как назначать права? Как добавлять и удалять администраторов?

Просмотреть

📁

Популярные статьи

Самые популярные материалы центра поддержки.

LMS

Чтобы скопировать урок из другого курса или текущего, нажмите кнопку "Скопировать урок". Кнопка "Скопировать урок", визуально объединенная с кнопкой "Добавить урок" и находится под названиями уроков. После того как вы нажмете кнопку "Скопировать урок": 1. Откроется новое окно, где нужно выбрать, из какого курса вы хотите скопировать урок. 2. После выбора курса появится еще одно поле, где нужно выбрать конкретный урок для копирования. 3. После этого нажмите кнопку "Создать", и урок будет скопирован. Каждая копия урока имеет предупреждение вверху редактора, которое говорит, что это копия. Если вы измените контент этой копии, изменения также отобразятся во всех остальных копиях. В предупреждении также указан список курсов, где находятся все копии этого урока. Обычно, когда мы изменяем копию, мы хотим, чтобы изменения автоматически применялись и к другим копиям. Но иногда нужно изменить только одну копию. В таком случае эту копию надо сделать самостоятельным уроком, нажав кнопку "Сделать самостоятельным" в окне предупреждения. Если вы удаляете копию и у нее осталась только одна другая копия, то та копия станет самостоятельным уроком. Если есть несколько копий, они останутся связанными между собой. Предупреждение, что урок является копией, показывается только в режиме редактирования для администраторов. Ученики, когда просматривают урок, этого сообщения не видят.

API

Как получить access token

Access token необходим для авторизации последующих API-запросов в LMS Smart Way. После получения токена вы передаёте его в заголовке Authorization с типом Bearer и используете для обращения к доступным endpoint’ам в соответствии со scope, которые вложены в токен. Эта статья показывает, как получить токен, что именно возвращает API в ответе и на что обратить внимание перед интеграцией. Если вы только начинаете настройку интеграции, сначала убедитесь, что у вас есть действительный company_api_key. Предпосылки - У вас должен быть действительный company_api_key вашей компании. - Запрос на получение токена необходимо выполнять на endpoint /api/v1/auth/token. - API key передаётся в заголовке X-API-Key. - Полученный access token используется только для последующих вызовов API и не заменяет собой API key. Запрос curl -X POST 'https://smartway.pro/api/v1/auth/token' \ -H 'X-API-Key: <company_api_key>' Успешный ответ { "access_token": "<short_lived_jwt>", "token_type": "Bearer", "expires_in": 900, "scope": "academy.read academy.write employees.read employees.write tests.read tests.write files.read" } Зафиксированные правила ответа - access_token — короткоживущий JWT для последующих вызовов public API - token_type — всегда Bearer - expires_in — TTL в секундах - scope — список scope-ов, разделённых пробелами, вложенных в токен Что внутри access token - JWT содержит claim companyId для tenant isolation. - JWT также содержит claim hrEmail — email HRADMIN, который создал или ротировал текущий активный API key компании. - Если API key сгенерирует или ротирует другой HRADMIN, то новые токены уже будут содержать другой hrEmail, и именно он будет использоваться для последующих employee write-операций. Как использовать access token в последующих запросах После успешного получения токена передавайте его в заголовке Authorization в формате Bearer <access_token>. Именно этот токен используется для авторизации последующих запросов к public API. Перед выполнением запроса проверяйте, что токен ещё не истёк. Если срок действия завершился, получите новый access token повторным вызовом endpoint’а авторизации.

API

Правила текущей реализации API LMS

Public API использует схему: company API key -> short-lived Bearer token Правила текущей реализации: - API key принадлежит компании, а не отдельному пользователю. - Для v1 разрешен один активный API key на компанию. - Управляет ключом только пользователь с ролью HRADMIN в cab > Settings > Company. - Полный секрет показывается только один раз — сразу после генерации или ротации. - После ротации предыдущий ключ становится невалидным сразу. - Интегратор получает access token через POST /v1/auth/token и далее использует Authorization: Bearer <token>. - Refresh token для интегратора в v1 не используется: после завершения TTL access token интегратор повторно вызывает POST /v1/auth/token. Base URL и общие правила вызова 1. Base URL Текущий base URL: - https://smartway.pro/api 2. Общие правила - Формат бизнес-ответов: application/json - Формат ошибок: application/problem+json - Версионирование: major-версия в URI (/v1/...) - Для корреляции запросов рекомендуется передавать traceparent

API

Как получить список сотрудников через API?

Как получить список сотрудников через API? GET /v1/employees возвращает страницу сотрудников. Если query-параметры не переданы, API применяет значения по умолчанию: page = 0 и size = 50. Endpoint | Параметр | Значение | | -------------- | ---------------------- | | Method | GET | | Path | /api/v1/employees | | Base URL | https://smartway.pro | | Auth | Bearer token | | Required scope | employees.read | Назначение Endpoint используется для получения постраничного списка сотрудников в рамках компании из Bearer token. Endpoint поддерживает пагинацию, поиск по ФИО и фильтры по департаменту и должности. Предусловия Клиент должен передать валидный Bearer token. Token должен содержать company context. Token должен содержать scope employees.read. idCompany не передаётся внешним клиентом. API определяет companyId только из Bearer token. Текстовые query-параметры поддерживают UTF-8 и должны передаваться как стандартный URL-encoded query string. Запрос Query parameters | Параметр | Тип | Обязательный | Описание | | ------------ | ------- | ---------------- | ----------------------------------------------------------------------- | | page | int32 | нет | Номер страницы. Значение по умолчанию: 0. | | size | int32 | нет | Размер страницы. Значение по умолчанию: 50. | | q | string | нет | Поиск по ФИО с частичным совпадением. Поиск по email не поддерживается. | | department | string | нет | Фильтр по департаменту. | | jobTitle | string | нет | Фильтр по должности. | curl пример Вызов без параметров curl -X GET 'https://smartway.pro/api/v1/employees' \ -H 'Authorization: Bearer <access_token>' \ -H 'Accept: application/json' Вызов с параметрами curl -X GET 'https://smartway.pro/api/v1/employees?page=0&size=20&q=Иван' \ -H 'Authorization: Bearer <access_token>' \ -H 'Accept: application/json' Вызов с несколькими UTF-8 параметрами curl -G 'https://smartway.pro/api/v1/employees' \ --data-urlencode 'page=0' \ --data-urlencode 'size=20' \ --data-urlencode 'q=Иван' \ --data-urlencode 'department=Управление' \ --data-urlencode 'jobTitle=Менеджер' \ -H 'Authorization: Bearer <access_token>' \ -H 'Accept: application/json' Ответ Успешный ответ: 200 OK. Возвращает EmployeeListResponse. { "data": [ { "employeeId": 4329, "candidateId": 10602, "email": "employee@example.com", "fullName": "Имя Фамилия", "name": "Имя", "surname": "Фамилия", "gender": "Female", "department": "КЛ", "departments": [ "КЛ" ], "jobTitle": "Менеджер", "jobTitles": [ "Менеджер" ], "phone": "+380000000000", "active": true, "manager": true } ], "meta": { "page": 0, "size": 50, "totalElements": 385, "totalPages": 8, "hasNext": true } } Поля ответа EmployeeListResponse | Поле | Тип | Описание | | -------- | ---------- | --------------------------------------- | | data | Employee[] | Список сотрудников на текущей странице. | | meta | object | Метаданные пагинации. | Employee | Поле | Тип | Описание | | ------------- | -------- | -------------------------------------------------------------------------------------------------------------- | | employeeId | int64 | ID сотрудника. | | candidateId | int64 | ID связанного кандидата. | | email | string | Email сотрудника. | | fullName | string | Полное имя, которое сервер формирует из name + surname. | | name | string | Имя. | | surname | string | Фамилия. | | gender | string | Пол. | | department | string | Основной департамент. | | departments | string[] | Набор департаментов. | | jobTitle | string | Основная должность. | | jobTitles | string[] | Набор должностей. | | phone | string | Телефон. | | active | boolean | Признак активности. | | manager | boolean | Признак роли руководителя подразделения. true означает, что сотрудник имеет эту роль на сервере авторизации. | Pagination meta | Поле | Тип | Описание | | --------------- | ------- | ------------------------------------------ | | page | int32 | Номер текущей страницы. Нумерация 0-based. | | size | int32 | Размер страницы. | | totalElements | int64 | Общее количество найденных элементов. | | totalPages | int32 | Общее количество страниц. | | hasNext | boolean | Признак наличия следующей страницы. | Бизнес-логика Все query-параметры необязательные. Если endpoint вызвать без параметров, API возвращает первую страницу сотрудников: page = 0, size = 50. Параметр page является 0-based: page = 0 - первая страница, page = 1 - вторая страница. API определяет companyId только из Bearer token. idCompany не передаётся внешним клиентом. Поиск q работает по ФИО с частичным совпадением. Поиск по email не поддерживается. Параметры q, department и jobTitle поддерживают UTF-8. Параметры можно комбинировать. Совокупность параметров применяется через логику AND. Для доступа нужен scope employees.read. Edge cases | Сценарий | Поведение API | | --------------------------------------------------------- | ------------------------------------------------------------- | | Query-параметры не переданы | API применяет page = 0 и size = 50. | | page = 0 | Возвращается первая страница. | | page = 1 | Возвращается вторая страница. | | Передан q | API ищет по ФИО с частичным совпадением. | | Передан email в q | Поиск по email не поддерживается. | | Переданы department и jobTitle | Фильтры комбинируются через AND. | | Передано UTF-8 значение, например department=Управление | Значение валидно, если передано как URL-encoded query string. | | Token без company context | API возвращает 403 Forbidden. | Ошибки Error responses | HTTP status | Когда возникает | | --------------------------- | ------------------------------------------------ | | 400 Bad Request | Некорректные query-параметры. | | 401 Unauthorized | Bearer token отсутствует или невалиден. | | 403 Forbidden | Недостаточно прав или token без company context. | | 500 Internal Server Error | Неожиданная ошибка API. | | 503 Service Unavailable | Сбой внутренней серверной интеграции. | Использование Без query-параметров. Получение следующей страницы через page. Изменение размера страницы через size. Поиск сотрудника по ФИО через q. Фильтрация сотрудников по department или jobTitle. Комбинирование поиска и фильтров для узкой выборки. Типичные ошибки Typical integration mistakes | Типичная ошибка | Как правильно | | ----------------------------------------- | ----------------------------------------------------------------------- | | Считать, что page = 1 - первая страница | Используйте page = 0 для первой страницы. | | Искать сотрудника по email через q | q поддерживает поиск по ФИО, а не по email. | | Передавать idCompany в query string | Не передавайте idCompany; API определяет companyId из Bearer token. | | Не кодировать UTF-8 значения в URL | Передавайте текстовые параметры как URL-encoded query string. | | Использовать token без employees.read | Для endpoint-а нужен scope employees.read. | FAQ Можно ли вызвать endpoint без query-параметров? Да. API применит page = 0 и size = 50. С какой страницы начинается пагинация? С page = 0. Поддерживается ли поиск по email? Нет. Параметр q ищет по ФИО с частичным совпадением. Можно ли комбинировать фильтры? Да. Параметры комбинируются через логику AND. Нужно ли передавать idCompany? Нет. API определяет companyId из Bearer token.

API

Как добавить сотрудника через API?

POST /v1/employees создаёт сотрудника. Обязательные поля body: email, name, surname, gender и active. Для доступа нужен scope employees.write. Endpoint | Параметр | Значение | | -------------- | ---------------------- | | Method | POST | | Path | /api/v1/employees | | Base URL | https://smartway.pro | | Auth | Bearer token | | Required scope | employees.write | Назначение Endpoint используется для создания нового сотрудника в рамках компании из Bearer token. Значение active управляет не только бизнес-флагом, но и созданием или отсутствием связанного пользователя на сервере авторизации. Предусловия Клиент должен передать валидный Bearer token. Token должен содержать company context. Token должен содержать scope employees.write. idCompany не передаётся в body или query string. Запрос Body parameters | Поле | Тип | Обязательное | Описание | | ------------- | -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | email | string | да | Email сотрудника. | | name | string | да | Имя сотрудника. Это источник данных для формирования fullName при создании. | | surname | string | да | Фамилия сотрудника. Это источник данных для формирования fullName при создании. | | gender | string | да | Допустимы только значения Male или Female. | | active | boolean | да | Допустимы только JSON-boolean значения true или false. true создаёт или синхронизирует доступ к личному кабинету через сервер авторизации; false создаёт сотрудника без такого доступа. | | manager | boolean | нет | Признак роли руководителя подразделения. Допустимы только JSON-boolean значения true или false; true создаёт или синхронизирует доступ с ролями сотрудника и руководителя подразделения, даже если active=false. | | department | string | нет | Основной департамент. Если не передать, сохраняется null. | | departments | string[] | нет | Набор департаментов. Если не передать, коллекция остаётся пустой. | | jobTitle | string | нет | Основная должность. Если не передать, сохраняется null. | | jobTitles | string[] | нет | Набор должностей. Если не передать, коллекция остаётся пустой. | | phone | string | нет | Телефон. Если не передать, сохраняется null. | | notes | string | нет | Примечания. Если не передать, сохраняется null. | curl пример Создать сотрудника с primary-полями и массивами curl -X POST 'https://smartway.pro/api/v1/employees' \ -H 'Authorization: Bearer <access_token>' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ --data-binary @- <<'JSON' { "email": "employee@example.com", "name": "Иван", "surname": "Петренко", "gender": "Female", "active": false, "manager": false, "department": "Управление", "departments": ["КЛ"], "jobTitle": "Менеджер", "jobTitles": ["Координатор"], "phone": "+380000000000", "notes": "Новый сотрудник public API" } JSON Создать сотрудника только с массивами departments/jobTitles curl -X POST 'https://smartway.pro/api/v1/employees' \ -H 'Authorization: Bearer <access_token>' \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ --data-binary @- <<'JSON' { "email": "employee@example.com", "name": "Иван", "surname": "Петренко", "gender": "Male", "active": true, "manager": true, "departments": ["Управление", "КЛ"], "jobTitles": ["Менеджер", "Координатор"], "phone": "+380000000000", "notes": "Новый сотрудник public API" } JSON Ответ Успешный ответ: 201 Created. Возвращает созданный Employee. { "employeeId": 4432, "candidateId": 10748, "email": "employee@example.com", "fullName": "Иван Петренко", "name": "Иван", "surname": "Петренко", "gender": "Female", "department": "Управление", "departments": [ "КЛ", "Управление" ], "jobTitle": "Менеджер", "jobTitles": [ "Координатор", "Менеджер" ], "phone": "+380000000000", "active": false, "manager": false } Поля ответа Employee | Поле | Тип | Описание | | ------------- | -------- | --------------------------------------------------------------------------------------- | | employeeId | int64 | ID сотрудника. | | candidateId | int64 | ID связанного кандидата. | | email | string | Email сотрудника. | | fullName | string | Полное имя, которое сервер формирует из name + surname. | | name | string | Имя. | | surname | string | Фамилия. | | gender | string | Пол. | | department | string | Основной департамент. | | departments | string[] | Набор департаментов. | | jobTitle | string | Основная должность. | | jobTitles | string[] | Набор должностей. | | phone | string | Телефон. | | active | boolean | Признак активности. | | manager | boolean | Признак роли руководителя подразделения. true означает, что сотрудник имеет эту роль. | Бизнес-логика API определяет companyId только из Bearer token. API определяет hrEmail из Bearer token. hrEmail равен email пользователя с ролью HRADMIN, который создал или ротировал активный API key компании. Если активный API key будет ротирован другим HRADMIN, следующие create-операции автоматически начнут использовать его hrEmail. Повторный одинаковый POST не создаёт дубль, если уже существует employee с таким же email; API возвращает 409 Conflict. gender принимает только Male или Female. active принимает только JSON-boolean true или false. active = true создаёт или синхронизирует связанный пользовательский аккаунт на сервере авторизации и открывает доступ к личному кабинету. active = false создаёт сотрудника без доступа к личному кабинету, то есть без пользовательского аккаунта на сервере авторизации. manager = true создаёт или синхронизирует доступ с ролями сотрудника и руководителя подразделения. Если одновременно передать active = false, manager-доступ имеет приоритет и сотрудник будет создан как активный пользователь кабинета. manager = false или отсутствие поля manager не назначает роль руководителя подразделения. manager возвращается в Employee response; после создания эту роль можно изменить через PATCH /v1/employees/{employeeId}. fullName в ответе формируется сервером из name + surname. Если передан только departments или jobTitles, первый элемент массива становится primary-значением в department или jobTitle. Если передано и одиночное поле, и массив, одиночное поле имеет приоритет как primary, а массив дополняется уникальными значениями. Если department, jobTitle, phone или notes не переданы, в соответствующих одиночных полях сохраняется null. Если departments или jobTitles не переданы, соответствующие коллекции остаются пустыми. В ответе departments и jobTitles возвращаются в стабильно отсортированном виде. Edge cases | Сценарий | Поведение API | | ----------------------------------------------- | ---------------------------------------------------------------------------------- | | Отсутствует required-поле | API возвращает 400 Bad Request. | | gender имеет значение не Male и не Female | API возвращает 400 Bad Request с пояснением. | | active передан строкой или числом | API возвращает 400 Bad Request, потому что active должен быть JSON-boolean. | | manager передан строкой или числом | API возвращает 400 Bad Request, потому что manager должен быть JSON-boolean. | | active=false и manager=true | Manager-доступ имеет приоритет; сотрудник создаётся активным. | | email уже существует | API возвращает 409 Conflict. | | Передан только departments | Первый элемент массива становится department. | | Переданы department и departments | department остаётся primary, а departments дополняется уникальными значениями. | | Не передан department или jobTitle | В соответствующем одиночном поле сохраняется null. | | Не передан departments или jobTitles | Соответствующая коллекция остаётся пустой. | Ошибки Error responses | HTTP status | Когда возникает | | --------------------------- | --------------------------------------------------------------------------------------------- | | 400 Bad Request | Отсутствует хотя бы один required-параметр email, name, surname, gender или active. | | 400 Bad Request | gender не равен Male или Female. | | 400 Bad Request | active не является JSON-boolean значением true или false. | | 400 Bad Request | manager не является JSON-boolean значением true или false. | | 401 Unauthorized | Bearer token отсутствует или невалиден. | | 403 Forbidden | Недостаточно прав или token без company context. | | 409 Conflict | Employee с таким email уже существует. | | 500 Internal Server Error | Неожиданная ошибка API. | | 503 Service Unavailable | Сбой внутренней серверной интеграции. | Использование Создать активного сотрудника с доступом к личному кабинету: active = true. Создать сотрудника без доступа к личному кабинету: active = false. Создать сотрудника с ролью руководителя подразделения: manager = true. Синхронизировать сотрудников из внешней HR-системы. Типичные ошибки Typical integration mistakes | Типичная ошибка | Как правильно | | ----------------------------------------------------------- | --------------------------------------------------------------- | | Передавать active как строку "true" или "false" | Передавайте true или false как JSON-boolean. | | Передавать manager как строку "true" или "false" | Передавайте true или false как JSON-boolean. | | Передавать gender в значении, отличном от Male/Female | Используйте только Male или Female. | | Передавать idCompany или hrEmail | Не передавайте эти значения; API определяет их из Bearer token. | | Ожидать идемпотентность через Idempotency-Key | В текущей реализации Idempotency-Key не используется. | | Передавать fullName вместо name и surname | Передавайте name и surname; fullName формирует сервер. | FAQ Какие поля обязательны для создания сотрудника? email, name, surname, gender и active. Что делает active = true? Сервер создаёт или синхронизирует связанный пользовательский аккаунт на сервере авторизации и открывает доступ к личному кабинету. Что делает active = false? Сотрудник создаётся без доступа к личному кабинету, то есть без пользовательского аккаунта на сервере авторизации. Что делает manager = true? Сервер создаёт или синхронизирует доступ с ролями сотрудника и руководителя подразделения. Если одновременно передать active = false, сотрудник всё равно будет создан как активный пользователь кабинета. Что будет, если email уже существует? API вернёт 409 Conflict. Нужно ли передавать hrEmail? Нет. API определяет hrEmail из Bearer token.

Настройки

Первая настройка академии

При создании аккаунта Компании академия автоматически создается со стандартными значениями названия и слоганов. Вам нужно изменить их на свои значения. Для того чтобы их изменить: 1. нажмите на карандаш справа от текста; 2. впишите свои значения; 3. нажмите на зеленую галочку, чтобы сохранить изменения. Если вы не хотите сохранять изменения, щелкните красный крестик. Важно! Изменения нужно производить во всех языковых интерфейсах. Например, сначала внесите изменения на русском языке, когда у вас язык системы - русский. Далее переключитесь на другой язык и внесите изменения снова на выбранный язык. Если не внести изменения во всех языковых интерфейсах, то там, где вы их не сделаете, будет отображаться стандартное значение.