Авторизация запросов по протоколу 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.

  1. Первый раз когда вы отправите запрос, вам придет код.
  2. Далее отправьте запрос еще раз, добавив заголовок 2fa_confirmation.
  3. Теперь отправьте запрос еще раз, без 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"]
}'

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

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

{
    "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' \

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

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

{
    "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)

  1. Получите 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}'
    
  2. В ответе придёт массив scope — список текущих прав и id вашего токена.
    {
    "items": [
      {
     "scope": [
     "push-notification:write",
     "event:read",
     "installations:read"
     ],
      "id": "42b7ec031a1d40d969f3487ee9dcae63"
      }
    ],
    "paging": {}
    }
    
  3. Используйте 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"
      ]
    }'
    
  4. В ответ вернётся сообщение о перезаписи прав доступа токена:
    {
      "scope": [
     "push-notification:write",
     "event:read",
     "installations:read"
      ],
      "id": "{id}",
      "access_token": "{access_token}"
    }
    

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

  1. Создайте кнопку с ссылкой следующего вида:
    https://oauth.evotor.ru/oauth/authorize?client_id={client_id}&response_type=code&redirect_uri={redirect_url}
    

    {client_id} и {redirect_url} замените на значения из настроек на шаге 2.

  2. После нажатия на кнопку пользователь перейдёт к странице авторизации на market.evotor.ru. После ввода логина и пароля пользователь соглашается предоставить разрешения для приложения.

  3. Нажатие на кнопку Войти перенаправляет пользователя на указанный 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"
}

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

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