Если в системе включена авторизация, то для начала работы с API необходимо пройти авторизацию в системе.
Реализованы несколько вариантов авторизации:
- BASIC авторизация.
- Авторизация методом GET по адресу /api/session с получением token.
- Авторизация методом POST по адресу /api/session с получением token.
REST API работает только если при работе с ТСД используется сервер Mobile SMARTS. При прямом подключении ТСД к компьютеру через кабель/крэдл или при обмене с учетной системой через папку использовать REST API не получится.
В базе Mobile SMARTS должна быть включена авторизация, тогда для выполнения HTTP-запросов необходимо будет каждый раз авторизовываться, есть 2 варианта авторизации:
-
BASIC авторизация — в этом случае при каждом HTTP-запросе нужно будет отправлять логин и пароль;
-
авторизация с использованием токена — при первом HTTP-запросе передаются логин и пароль, а сервер MS возвращается токен — уникальный идентификатор сессии (access token), который при последующих HTTP-запросах можно будет использовать вместо передачи логина и пароля. Срок действия токена (т.е. сессии) ограничен, поэтому для обновления токена при первом запросе сервер Mobile SMARTS дополнительно возвращает «токен обновления» (refresh token) — он нужен для получения нового токена после истечения срока действия текущего токена.
Обратите внимание. Для защиты передаваемых данных рекомендуется использовать режим с включенной аутентификацией и доступом по https.
Для работы через протокол https необходимо указать это в настройках базы данных, для этого зайдите в менеджер базы, справа кнопки «Добавить» нажмите на выпадающий список и выберите пункт «Настройки», далее в окне «Редактирование настроек» поставьте галочку «Использовать http» и нажмите «ОК».
Для работы в режиме с включенной аутентификацией необходимо завести пользователей, задать им логины и пароли. В панели управления Mobile SMARTS узел «Пользователи и группы» содержит данные о пользователях и группах, в которых они состоят.
Инструкция по конфигурации настроек пользователей и групп пользователей, как определить роль пользователей и список типов документов, доступных для обработки пользователям такой группы описана в одноименной статье на сайте.
Пример запроса на авторизацию приложения методом POST
-
Для начала в настройках базы Mobile SMARTS включите авторизацию/аутентификацию по пользователю и нажмите на кнопку «ОК»
-
Пример запроса на авторизацию
http://localhost:51434/api/v1/session?username={username}&password={password}
в ответ приходит Access_token
-
В последующих запросах в заголовке указываем
{Authorization: Bearer {Access_token}
Если не указать Authorization, в ответ приходит статус ошибки
401 — Unauthorized
- При успешной авторизации приходит ответ и статус 202 — OK
BASIC авторизация
Данный вид авторизации чаще всего используется браузером для доступа к функциям API.
При использовании данного метода необходимо в заголовке каждого запроса указывать:
Authorization: Basic {login}:{password}
Допускается base64 при формировании строки {login}:{password}
Авторизация методом GET
Еще один способ авторизации — отправить GET запрос по адресу /api/v1/session, при этом в url запросе указать параметры login и password:
https://localhost:9000/api/v1/session?username=${Username}&password=${Password}
Ответ сервера:
{
Access_token:"123123123",
Token_type:"bearer",
Expires_in:86400,
Refresh_token:"321321321",
}
Авторизация методом POST
Авторизация по логину и паролю происходит путем отправки POST запроса на сервер, в результате которого возвращается access_token и refresh token в формате JSON.
Пример запроса:
POST /oauth/token HTTP/1.1
Host: mobilesmarts.ru/api/session
Content-Type: application/x-www-form-urlencoded
grant_type=password&client_id=123&client_secret=user&username=user@domain.ru&password=123456
Ответ сервера:
{
Access_token:"123123123",
Token_type:"bearer",
Expires_in:86400,
Refresh_token:"321321321",
}
Восстановление после окончания срока действия сессии
Восстановление после окончания срока действия сессии происходит путем отправки refresh_token на сервер, в результате приходит новый access_token и refresh_token
Пример:
POST /oauth/token HTTP/1.1
Host: mobilesmarts.ru/api/session
Content-Type: application/x-www-form-urlencoded
grant_type:refresh_token&client_id=123&client_secret=user&refresh_token=321321321
Ответ:
HTTP/1.1 200 OK
Content-Type: application/json
{
Access_token:"99999",
Token_type:"bearer",
Expires_in:86400,
Refresh_token:"789789789",
}
Вызов функций с использованием token
Для того чтобы обратиться к функциям (если не используется Basic авторизация), для которых необходима авторизация, необходимо в заголовке Authorization передавать токен:
Authorization: Bearer <token>
Иначе сервер вернет ошибку авторизации 401.
