Авторизация запросов по протоколу OAuth

Редактировать

Шаг 1. Создайте ключ доступа издателя

Чтобы получить ключ доступа (access_token), отправьте запрос на авторизацию по логину и паролю от личного кабинета разработчика:

curl --request POST \
  --url https://dev.evotor.ru/oauth/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data type=LOGIN \
  --data grant_type=password \
  --data client_id=Evo-UI \
  --data username={developer_username}\  # логин от личного кабинета разработчика
  --data password={developer_password}  # пароль от личного кабинета разработчика
  --data 2fa_confirmation={2fa_confirmation_code} # код двухфакторной авторизации

Из полученного ответа вам понадобится access_token. Пример ответа:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJYLUZpbmdlcnByaW50IjoiMjk3OThiNzg1NDI3N2M1M2YzZmJhYjRlZmU4YWZiZGYiLCJ1c2VyX25hbWUiOiJlLnpha2hhcm92QGV2b3Rvci5ydSIsInhfdXNlcl9pZCI6ImYwYjQwZGFiLTI4YTMtNDQ5Yy04OTZkLTFjOGI1OTRhNTY2MiIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSIsInB1cmNoYXNlIl0sImV4cCI6MTU5NzMyMjU0NiwiaWF0IjoxNTk3MzIwNzQ2MTI2LCJhdXRob3JpdGllcyI6WyJST0xFX1BVQkxJU0hFUiJdLCJqdGkiOiI5MmEwYWE0ZS0zNmIzLTQ4YmQtYWRmYy00ZDkxMzk1MTlhM2YiLCJ4X3VpZCI6bnVsbCwiY2xpZW50X2lkIjoiRXZvLVVJIiwieF9sb25nbGl2ZWQiOmZhbHNlfQ.RTi53lsvlLbCTvb4xjZ_DxlgASHHPTbwvd_Fm5XTkzE",
  "token_type": "bearer",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJYLUZpbmdlcnByaW50IjoiNWIzYTdiZDljYTQ3YmRmNmQ5NGQ3ODJlYjZjYzJhZjIiLCJ1c2VyX25hbWUiOiJlLnpha2hhcm92QGV2b3Rvci5ydSIsInhfdXNlcl9pZCI6ImYwYjQwZGFiLTI4YTMtNDQ5Yy04OTZkLTFjOGI1OTRhNTY2MiIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSIsInB1cmNoYXNlIl0sImF0aSI6IjkyYTBhYTRlLTM2YjMtNDhiZC1hZGZjLTRkOTEzOTUxOWEzZiIsImV4cCI6MTU5NzM2Mzk0NiwiaWF0IjoxNTk3MzIwNzQ2MTI2LCJhdXRob3JpdGllcyI6WyJST0xFX1BVQkxJU0hFUiJdLCJqdGkiOiJhMTczNGY2YS01NDk1LTQyOTctOWU1NS0yZDI4ZDJmYThjNDAiLCJ4X3VpZCI6bnVsbCwiY2xpZW50X2lkIjoiRXZvLVVJIiwieF9sb25nbGl2ZWQiOmZhbHNlfQ.B3ztipg3UHuBmdySEnex5f25AIidyiJ9cQVlWnd-W94",
  "expires_in": 1799,
  "scope": "read write purchase",
  "X-Fingerprint": "29798b7854277c53f3fbab4efe8afbdf",
  "x_user_id": "f0b40dab-28a3-449c-896d-1c8b594a5662",
  "x_uid": null,
  "iat": 1597320746126,
  "x_longlived": false,
  "jti": "92a0aa4e-36b3-48bd-adfc-4d9139519a3f"
}

Как работать с двухфакторной авторизацией

2fa_confirmation — это код двухфакторной авторизации, отправляемый на электронную почту, переданную в username. При авторизации с нового IP-адреса. Эвотор запоминает 10 IP-адресов и не запрашивает код при повторной авторизации с известного IP-адреса.

Код для двухфакторной авторизации запрашивается только при первой авторизации с IP. Далее код не будет запрашиваться для последних 10 IP, с которых проходили авторизацию. Код передается в заголовке 2fa_confirmation.

Первый раз когда вы отправите запрос, вам придет код.
Далее отправьте запрос еще раз, добавив заголовок 2fa_confirmation.
Теперь отправьте запрос еще раз, без 2fa_confirmation.

Если отправляете с одного и того же IP, то повторно код запрашиваться не будет.

Шаг 2. Создайте настройки авторизации через OAuth

POST https://dev.evotor.ru/api/v1/publisher/app/oauth/public/apps/{app-id}/versions/{version-id}/oauth-apps

Создаёт клиента приложения с определённым набором прав доступа к ресурсам пользователя. Параметр version-id содержит идентификатор версии приложения.

Идентификатор версии приложения отображается в адресной строке браузера при выборе версии приложения на портале разработчиков.

Пример запроса:

curl -X POST \
  'https://dev.evotor.ru/api/v1/publisher/app/oauth/public/apps/537f5c5d-a173-466b-863a-dac5eb9d5bd0/versions/537f5c5d-a173-466b-863a-dac5eb9d5bd1/oauth-apps?type=web' \
  -H 'Authorization: Bearer 9179d710-56a4-49ea-b042-435e3257eaf6' \
  -H 'Content-Type: application/json' \
  -H 'Origin: https://dev.evotor.ru' \
  -H 'User-Agent: ' \
  -d '{
  "registered_redirect_uri": ["https://example.html/"],
  "scope": ["device:read"]
}'

Параметры запроса:

Заголовок Authorization содержит bearer-токен доступа.

Токен доступа вы можете получить в личном кабинете разработчика следующим образом:
1. Перейдите на вкладку Мои приложения.
2. Откройте инструменты разработчика по сочетанию клавиш Ctrl+Shift+I.
3. На вкладке Сеть, выберите тип содержимого XHR.
4. Обновите страницу, чтобы выполнить запрос к серверу.
5. В полученном списке выберите файл token и перейдите к ответу.
  
  Токен содержится в поле access_token.
Заголовок User-Agent — браузер, в котором был получен токен.
Query-параметр type указывает тип клиента. Типы клиентов различаются доступными сценариями авторизации. Возможные значения:
- web — выбирайте этот тип, если у вашего приложения есть серверная часть, которая будет участвовать в обмене кода авторизации на токен доступа. В этом случае идентификатор и секрет клиента может храниться на сервере приложения. Доступные сценарии авторизации: authorization_code, refresh_token, implicit.
- standalone — выбирайте этот тип, если у вашего приложения нет серверной части. В этом случае идентификатор и секрет клиента может быть указан в исходном коде приложения, которое пользователь устанавливает на своё устройство. Доступные сценарии авторизации: authorization_code, implicit.
Рекомендуемым сценарием авторизации является использование authorization_code.
registered_redirect_uri — адрес страницы на вашем сервере, куда будет перенаправлен пользователь после подтверждения доступа к ресурсам.
scope — массив строк, указывающих права доступа к ресурсам, которые клиент будет запрашивать у пользователя.

Пример ответа:

{
    "client_id": "89856c66-c9d1-4fad-996e-71fa368179ee",
    "client_secret": "44c8fa46-af2d-47c3-b440-e2b82963ea0e",
    "scope": [
        "device:read"
    ],
    "authorized_grant_types": [
        "authorization_code",
        "implicit",
        "refresh_token"
    ],
    "registered_redirect_uri": [
        "https://example.html/"
    ],
    "access_token_validity": 604800,
    "publisher_id": "2d0c2b00-b843-45f1-97d2-2276e52fe469",
    "app_id": "537f5c5d-a173-466b-863a-dac5eb9d5bd0",
    "version_id": "0.1"
}

Список прав доступа к ресурсам (`scope`)

Права доступа к ресурсам задаются в массиве scope при создании настроек авторизации. Например:

"scope": [
    "device:read",
    "product:read",
    "product.quantity:read",
    "product.quantity:write"
]

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

Имя ресурса	Описание	Права доступа
store	Получение информации о магазинах пользователя.	read
employee	Получение информации о сотрудниках пользователя.	read
device	Получение информации о смарт-терминалах пользователя.	read
device.imei	Получение информации об IMEI смарт-терминала.	read
device.location	Получение информации о местоположении смарт-терминала.	read
device.firmware	Получение информации о версии прошивки смарт-терминала.	read
product	Предоставляет доступ к номенклатуре. Вы можете как получать номенклатуру (read), так и изменять её (write).	read write
product.quantity	Предоставляет доступ к остаткам товаров. Вы можете как получать остатки (read), так и изменять их (write).	read write
document	Получение списка документов.	read
product-group	Предоставляет доступ к группам товаров. Вы можете как получать группы товаров (read), так и изменять их (write).	read write
product-image	Предоставляет доступ к изображениям товаров. Вы можете как получать изборажения товаров (read), так и изменять их (write).	read write

Получить информацию о клиентах приложения

GET https://dev.evotor.ru/api/v1/publisher/app/oauth/public/apps/{app-id}/versions/{version-id}/oauth-apps

Возвращает список с данными всех клиентов приложения. Параметр version-id содержит версию приложения, заданную на сайте разработчиков.

Пример запроса:

curl -X GET \
  https://dev.evotor.ru/api/v1/publisher/app/oauth/public/apps/fabd6e93-9dcd-46d7-a4ca-3f9d8fc0a441/versions/0.1/oauth-app \
  -H 'Authorization: e0704952-b8de-467f-bfc4-8a6b919f8757' \
  -H 'Accept: Application/vnd.evotor.v2+json' \
  -H 'Origin: https://dev.evotor.ru' \

Параметры запроса:

Заголовок Authorization содержит токен полученный одним из способов описанных в разделе “Авторизация запросов к Облаку Эвотор”.
Заголовок Accept содержит тип данных. Указывайте Application/vnd.evotor.v2+json.

Пример ответа:

{
    "items": [
        {
            "client_id": "89856c66-c9d1-4fad-996e-71fa368179ee",
            "client_secret": "44c8fa46-af2d-47c3-b440-e2b82963ea0e",
            "scope": [
                "device:read"
            ],
            "authorized_grant_types": [
                "implicit",
                "authorization_code"
            ],
            "registered_redirect_uri": [
                "<redirect_url>"
],
            "access_token_validity": 604800,
            "publisher_id": "2d0c2b00-b843-45f1-97d2-2276e52fe469",
            "app_id": "fabd6e93-9dcd-46d7-a4ca-3f9d8fc0a441",
            "version_id": "0.1"
        }
    ],
    "paging": {}
}

Изменить права доступа (`scope`)

Получите id вашего токена:

curl --request GET \
--url https://dev.evotor.ru/api/v1/publisher/app/oauth/public/personal-tokens \
--header 'accept: application/json, text/plain, */*' \
--header 'content-type: application/json' \
--header 'x-authorization: Bearer {access_token}'

В ответе придёт массив scope — список текущих прав и id вашего токена.

{
"items": [
  {
 "scope": [
 "push-notification:write",
 "event:read",
 "installations:read"
 ],
  "id": "42b7ec031a1d40d969f3487ee9dcae63"
  }
],
"paging": {}
}

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

curl --request PUT \
--url https://dev.evotor.ru/api/v1/publisher/app/oauth/public/personal-tokens/42b7ec031a1d40d969f3487ee9dcae62 \
--header 'accept: application/json, text/plain, */*' \
--header 'content-type: application/json' \
--header 'x-authorization: Bearer {access_token}'
--data '{
  "scope": [
 "push-notification:write",
 "event:read",
 "installations:read"
  ]
}'

В ответ вернётся сообщение о перезаписи прав доступа токена:

{
  "scope": [
 "push-notification:write",
 "event:read",
 "installations:read"
  ],
  "id": "{id}",
  "access_token": "{access_token}"
}

Шаг 3. Создайте механизм авторизации пользователей

Создайте кнопку с ссылкой следующего вида:
```
https://oauth.evotor.ru/oauth/authorize?client_id={client_id}&response_type=code&redirect_uri={redirect_url}
```
{client_id} и {redirect_url} замените на значения из настроек на шаге 2.
После нажатия на кнопку пользователь перейдёт к странице авторизации на market.evotor.ru. После ввода логина и пароля пользователь соглашается предоставить разрешения для приложения.
Нажатие на кнопку Войти перенаправляет пользователя на указанный redirect_uri с параметром запроса code. Пример:
```
https://webhook.site/88ac1a25-1bdb-45a6-953e-10eac2cf6742?code=1VjYdDPDT0qf
```

Шаг 4. Авторизуйте пользователя

Используя параметр code с шага 3, создайте access_token для пользователя:

curl --request POST \
  --url https://oauth.evotor.ru/oauth/token \
  --header 'authorization: Basic <base64 clientId:clientSecret>'\
  --header 'content-type: application/x-www-form-urlencoded' \
  --data code={code} \
  --data grant_type=authorization_code \
  --data redirect_uri=https://webhook.site/88ac1a25-1bdb-45a6-953e-10eac2cf6742

Пример ответа:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbWUiOiIwMS0wMDAwMDAwMDE4OTA4MzMiLCJzY29wZSI6WyJwcm9maWxlOnJlYWQiXSwiZXhwIjoxNTk3NDA3NjE5LCJhcHBfaWQiOiJmNmUwZDZjOC03YWY2LTQ2NmYtYjM3OS1kMzkwOWUwN2JjNTQiLCJhdXRob3JpdGllcyI6WyJST0xFX0NVU1RPTUVSIl0sImp0aSI6IjIzYjM4ZDUzLTYzMTEtNDIxNy1hY2U4LWQ2NzNhN2E3YzUxNiIsImNsaWVudF9pZCI6ImM3ZDA3N2IxMmVjMWIwMzgzMzFkNDI4M2U4MTIyMTllIn0.fYkgLKCfH1Xib699pv6C93dvdnnk2mCEV_hDpo_GlKM",
  "token_type": "bearer",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbWUiOiIwMS0wMDAwMDAwMDE4OTA4MzMiLCJzY29wZSI6WyJwcm9maWxlOnJlYWQiXSwiYXRpIjoiMjNiMzhkNTMtNjMxMS00MjE3LWFjZTgtZDY3M2E3YTdjNTE2IiwiZXhwIjoxNTk5OTEzMjE5LCJhcHBfaWQiOiJmNmUwZDZjOC03YWY2LTQ2NmYtYjM3OS1kMzkwOWUwN2JjNTQiLCJhdXRob3JpdGllcyI6WyJST0xFX0NVU1RPTUVSIl0sImp0aSI6ImE0ZTg1MzRjLWQ4ODEtNDNhZC05MDI4LTZiNjM5ZjRiNzNhYiIsImNsaWVudF9pZCI6ImM3ZDA3N2IxMmVjMWIwMzgzMzFkNDI4M2U4MTIyMTllIn0.59YLkWqdSQ7-Go58NcNIo_j5NSQZRoFocUymuhv9ebM",
  "expires_in": 86399,   
  "scope": "profile:read",
  "jti": "23b38d53-6311-4217-ace8-d673a7a7c516"
}

Параметры ответа:

expires_in — время жизни в секундах;
scope — установленные права доступа;
jti — идентификатор токена.

С полученным access_token будут выполняться все запросы к api.evotor.ru в соответствии с правами доступа.

Авторизация запросов по протоколу OAuth

Шаг 1. Создайте ключ доступа издателя

Как работать с двухфакторной авторизацией

Шаг 2. Создайте настройки авторизации через OAuth

Список прав доступа к ресурсам (scope)

Получить информацию о клиентах приложения

Изменить права доступа (scope)

Шаг 3. Создайте механизм авторизации пользователей

Шаг 4. Авторизуйте пользователя

Список прав доступа к ресурсам (`scope`)

Изменить права доступа (`scope`)