Использование XML-интерфейса по подписке

Введение

Для использования XML-интерфейса по подписке требуются следующие версии r_keeper:

• 7.6.2.286+
• 7.6.4.347+
• 7.6.5.40+

1. Для работы с XML-интерфейсом и выполнения команд SaveOrder, PayOrder, MakeRetunGoods необходимо дополнительно передавать информацию о лицензии LicenseInfo
2. Лицензия заводится и генерируется на сервере лицензирования (далее СЛ), при этом в локальной БД интеграции должны сохраняться в зашифрованном виде учетные данные, необходимые для выполнения запросов к СЛ: токен, id активной лицензии, порядковый номер запроса seqNumber
3. Для интеграции нужно использовать одну из следующих лицензий:

Авторизация

 Для настройки:

1. Под учетной записью с ролью дилер-менеджер в системе лицензирования создайте нового пользователя с ограниченными правами
2. Наделите нового пользователя правом доступа к карточке объекта, на котором планируется использовать XML-интерфейс.

Для отправки запросов для XML-интерфейсов по подписке укажите:

• userName — электронная почта, используемая как логин для входа в систему лицензирования l.ucs.ru созданного пользователя
• password — пароль для входа в систему лицензирования l.ucs.ru созданного пользователя

• token — уникальный идентификатор, выдается компании-разработчику бесплатно и является единым для всех ее интеграций.

Учетные данные, т.е. userName и password, предоставляет дилер объекта, на котором планируется использовать XML-интерфейс.

1. 
   Чтобы получить token, необходимо отправить письмо с запросом на электронный адрес integrations@rkeeper.ru. Используйте ту электронную почту, на которую будет зарегистрирована учетная запись и токен.
   Как было сказано ранее, токен выдается компании-разработчику или аналогичному лицу, для идентификации разработчика при выполнении запросов.  Выданный токен нужно использовать для всех интеграций компании-разработчика, т.е. не надо для каждого нового объекта или интеграции запрашивать новый токен.
   

Обратите внимание!

Токен выдается на ограниченное время, как правило, на 1 год, и может быть продлен владельцем токена неограниченное количество раз по запросу на электронную почту integrations@rkeeper.ru. На текущий момент автоматического продления токенов не производится, поэтому разработчик должен самостоятельно следить за тем, когда срок действия токена заканчивается и вовремя продлять его.

Пример:
Компания разрабатывает свой киоск самообслуживания, интегрируемый с r_keeper 7, и использует для этого любой тестовый или действующий объект с лицензиями на XML-интерфейс по подписке. Впоследствии планируется продавать эту интеграцию всем желающим заведениям.
Для этого компании необходимо:

1. Единовременно запросить у компании UCS токен, который будет использован для всех подключаемых объектов
2. У дилера, обслуживающего объект интеграции или тестовый объект, запросить:
   • Приобрести и сгенерировать в системе лицензирования лицензию на XML-интерфейс по подписке для этого объекта
   • Предоставить компании-разработчику учетную запись в системе лицензирования с доступом к объекту интеграции.

В заголовке запроса авторизации должен быть передан параметр usr, правило его формирования:

usr : Base64(userName + «;» + lowercase(md5(userName+password)) + «;» + lowercase(md5(token)))

Запрос ID лицензии

Для получения ID лицензии к API СЛ выполняется запрос GetLicenseIdByAnchor

GetLicenseIdByAnchor?anchor=6:<productGUID>#<restCode>/17

Где:

• productGUID — GUID продукта
• restCode — код ресторана

Пример заполнения якоря для продукта R-Keeper модуль XML-интерфейс для Приложения 12 мес ПО для объекта 199999993:

6:655cee55-7bcd-4826-b6e0-a8ccf2017ef3:199999993/17

Важно!

Cимволы ": #" в строке должны быть экранированы (: - %3A # - %23)

Запрос будет иметь вид:

https://l.ucs.ru/ls5api/api/License/GetLicenseIdByAnchor?anchor=6%3A655cee55-7bcd-4826-b6e0-a8ccf2017ef3%23199999993/17

Для положительного ответа на объекте должна быть подтверждена заявка на указанное ПО и сгенерирована активная лицензия.

В ответ получим информацию об активной лицензии:

{"id":"fe4e4c5a-3037-4f0c-8216-7b98be6d87bb","expirationDate":"2020-03-26T00:00:00","qty":1.0}

Полученный ID должен сохраняться в БД интегрируемого продукта и передаваться при заполнении LicenseInfo в атрибуте licenseToken.

Обновление ID нужно выполнять каждый раз при старте интеграции и при периодических проверках лицензии, например, каждые 30-90 минут, либо при ошибках выполнения запроса перед повтором.

Заполнение LicenseInfo

При отправке команд SaveOrder, PayOrder, MakeRetunGoods интегрируемый продукт проверяет наличие в БД информации о лицензии (ID лицензии). Если ID найден, в XML-запрос добавляется дополнительный элемент LicenseInfo.

<LicenseInfo anchor="6:655cee55-7bcd-4826-b6e0-a8ccf2017ef3#199999993/17" licenseToken="fe4e4c5a-3037-4f0c-8216-7b98be6d87bb">
<LicenseInstance guid="instance_guid" seqNumber="0"/>
</LicenseInfo>

• anchor — якорь лицензии
• licenseToken — ID лицензии
• guid — уникальный GUID экземпляра приложения. При первом старте интеграции должен быть сгенерирован автоматически, в дальнейшем хранится локально и передается в каждом запросе
• seqNumber — порядковый номер запроса. При первом вызове для нового guid должен быть 0, увеличивается при каждом запросе. В интеграции должно быть реализовано хранение текущего seqNumber в оперативной памяти или локальной БД. Для получения актуального значения на старте приложения можно использовать команду GetXMLLicenseInstanceSeqNumber, но эту команду нельзя выполнять слишком часто.

XSD схемы запросов: XML-Schemes.zip 
Актуальные схемы можно посмотреть на FTP: ftp://ftp.ucs.ru/rk7/ForDealers/XMLInterface/XML-Schemes

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

<?xml version="1.0" encoding="UTF-8"?>
<RK7Query>
<RK7CMD CMD="SaveOrder">
<LicenseInfo anchor="6:655cee55-9999-9999-9999-a8ccf2017ef3#99999999/99" licenseToken="d5027209-9999-9999-9999-232753289b34">
<LicenseInstance guid="ca456f569999d99997e9993b7c19994f" seqNumber="0"/>
</LicenseInfo>
  <Order visit="546368833" orderident="256"/>
  <Session>
    <Dish id="1025742" quantity="2000" price="150"/>
  </Session>
</RK7CMD>
</RK7Query>