Обмен сообщениями приложения и стороннего сервиса

Все запросы приложений к стороннему сервису проходят через Облако Эвотор:

Для отправки запросов приложения могут использовать только 80 и 443 порт.

Смарт-терминал не поддерживает протокол WebSocket.

Установленные на смарт-терминале приложения могут обращаться только к сторонним сервисам по протоколам HTTP и HTTPS. При этом, если сторонние сервисы находятся в одной локальной сети со смарт-терминалом, облако не проксирует запросы. Обращаться к REST API Облака Эвотор нельзя.

Добавьте корневой SSL-сертификат Минцифры

В марте 2022 года истекает срок действия текущего SSL-сертификата облака Эвотор. Для подготовки к миграции на отечественные сертификаты заранее добавьте в свои сервисы корневой сертификат Минцифры:

в приложение, если оно использует SSL-pining;
на свой сервер, если используете выделенный сервер для взаимодействия с облаком.

Подготовка к отправке запросов

Для отправки запросов требуется:

На портале dev.evotor.ru, указать список разрешённых URL, к которым может обращаться приложение.
Поддержать возможность обращения к сторонним сервисам в приложении.
Установить приложение в Магазине приложений.

В данном случае установка подразумевает активацию приложения в Личном кабинете и необходима, чтобы применились URL, которые вы указали на сайте разработчиков.

Настройка списка разрешённых URL

Чтобы настроить список разрешённых URL:

На портале dev.evotor.ru выберите приложение, для которого требуется указать список разрешённых URL.
На вкладке Интеграция, установите флажок Проксирование запросов из приложения с терминала на ваш сервер (ver. 2) и укажите список URL, к которым может обращаться приложение.

Примеры:

http://example\.com/document.*\.jsp\?wildcard=\*&param=value.*;
https://another\.host\.com/document.*\.jsp;
https://another\.host\.com/.*.

Чтобы задавать маски веб-сайтов используйте регулярные выражения. При этом, хорошей практикой будет указывать в масках адреса своих серверов.

После создания списка и установки приложения в Магазине приложений, обмен сообщениями происходит по описанному ниже процессу.

Шаг 1. Приложение отправляет HTTP-сообщение в сторонний сервис

Приложение создаёт HTTP-сообщение и отправляет его в сторонний сервис. Вы можете воспользоваться любым удобным способом отправки сообщения.

Например, для отправки HTTP-сообщения из Java-приложения вы можете, использовать библиотеку OkHttp или способ, описанный на сайте developer.android.com.

Независимо от версии проксирования, SDK смарт-терминала и Облако Эвотор поддерживают следующие HTTP-методы:

GET;
POST;
PUT;
DELETE.

Эвотор гарантирует поддержку следующих MIME-типов:

application/x-www-form-urlencoded
application/json
application/xml
text/*
image/*
multipart/form-data

Поддержка других MIME-типов не гарантируется.

Время ожидания соединения – пять секунд.

Шаг 2. Смарт-терминал передаёт сообщение в облако

Терминал перехватывает сообщение и передаёт его в облако Эвотор.

Заголовки, которые терминал добавляет к запросу вашего приложения:

X-Device-ID
X-Device-IMEI
X-User-ID
X-Signed-Url
X-Shop-UUID
X-Device-Salt
X-Device-Algorithm
X-Device-Date
X-Secret-Device-ID
X-OAuth-Client-ID
X-Device-UUID
X-Evotor-*
Expect
Host
Transfer-Encoding

Убедитесь, что ваше приложение не использует перечисленные заголовки. В противном случае, смарт-терминал перезапишет их содержимое.

Шаг 3. Облако передаёт сообщение адресату

Облако удаляет служебные заголовки, добавляет свои заголовки и передаёт сообщение адресату.

Заголовки, которые добавляет облако:

X-Evotor-Store-Uuid – содержит идентификатор магазина в формате uuid4, к которому привязан терминал.
X-Evotor-Device-UUID – содержит идентификатор устройства в формате uuid4, полученный по запросу к /api/v1/inventories/devices.
X-Evotor-User-Id – содержит идентификатор пользователя в Облаке Эвотор.
Authorization – содержит токен пользователя приложения стороннего сервиса. Токен необходим для bearer-авторизации.

Сторонний сервер получает сообщение от облака Эвотор и определяет отправителя с помощью заголовка Authorization.

Шаг 4. Ответ стороннего сервиса

Ответ стороннего сервиса передаётся приложению в обратном порядке.

Требования к содержимому ответа отсутствуют. Время ожидания данных – 10 секунд.

За проксирование отвечает параметр Проксирование запросов из приложения с терминала на ваш сервер на вкладке Интеграция вашего приложения, на сайте dev.evotor.ru.