XML-интерфейс r_keeper 7

Введение

XML​-интерфейс предоставляет наиболее удобный способ получения информации о системе r_keeper 7 и сохранения данных в базах данных r_keeper 7, а также выполнения различных операций.

Существует 3 вида интерфейсов в r_keeper 7:

• Для кассовых станций
• Для кассовых серверов
• Для серверов справочников (отчетов).

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

XML-интерфейс позволяет:

• Читать данные из справочников и коллекций — справедливо для всех видов интерфейсов
• Создавать новые и изменять свойства существующих элементов справочников — только для серверов справочников
• Получать информацию о текущих заказах, создавать новые и оперировать имеющимися заказами, выполнять любые кассовые операции — только для кассового сервера
  Примеры операций:
  • Закрытие общей смены
  • Печать отчета

Общая схема взаимодействия представлена ниже:

На основе XML-интерфейса работают такие продукты, как Мобильный официант, Киоск самообслуживания, Kiosk PRO, и т.д.

Возможности интерфейсов сервера справочников

• Чтение элементов справочников
• Изменения свойств существующих элементов справочников
• Создания новых элементов справочников.

Применяется обычно для:

• Интеграции с сайтом ресторана – выгрузка меню
• Выгрузки меню, цен и прочего во внешнюю доставку
• Выгрузки ассортимента во внешние системы учета, например, 1С
• Загрузка меню, цен и других параметров на сервер справочников.

Возможности интерфейса кассового сервера

• Чтение справочников
• Чтение информации по текущим заказам
• Создание и редактирование заказов
• Выполнение кассовых операций.

Применяется обычно для:

• Интеграций с сайтом доставки ресторана – полный цикл от создания заказа до оплаты
• Интеграций мобильных приложений, систем самообслуживания, доставки и других систем
• Мониторинг текущего состояния продаж и прочего
• Интеграций с системами лояльности
• Интеграций с системами видеонаблюдения.

Особенности XML-интерфейса кассовой станции

• Можно добавить блюдо прямо в открытый заказ
• Чтение содержимого открытого заказа на кассе
• Выполнение кассовых операций — прокатка карты, запрос инфо о карте
• Оплата текущего заказа.

Лицензирование

Существует два варианта лицензирования XML-интерфейса:

• LifeTime — R-Keeper модуль XML сохранение заказов ПО — лицензия приобретается на конкретный объект в системе лицензирования единовременно, не предполагает никаких ограничений по запросам в рамках этого объекта.
  После приобретения лицензии необходимо сгенерировать лицензионный ключ и добавить его в свойства ресторана в менеджерской станции. Подробнее читайте в статье Интерфейс XML сохранения заказов

• По подписке — лицензия для интеграции внешних приложений на 1 или 12 месяцев. Запросы SaveOrder, PayOrder, MakeRetunGoods должны подписываться и проверяться системой лицензирования. Подробнее читайте в статье Использование XML-интерфейса по подписке.

Способы обмена данными с XML-интерфейсом

Существует два способа обмена данными с XML-интерфейсом:

• С использованием протокола HTTPS — доступен с версии r_keeper 7.05.03 и выше
• С использованием rk7xml.dll — в этом случае требуется добавить XML-интерфейс на кассовый сервер, обмен данными будет идти через прописанный в его свойствах порт. Проверку можно осуществить через через тестовую специальную утилиту XMLTEST.exe. Подробнее о настройках читайте ниже в разделе Настройка работы XML-интерфейса с использованием rk7xml.dll.

Настройка работы XML-запросов через HTTPS

Выполнение XML запросов через HTTPS возможно только для версии r_keeper 7.05.03 и выше.

В менеджерской станции необходимо настроить доступ к кассовому серверу через HTTPS. Для этого требуется создать работника с соответствующей привилегией. В актуальных версиях r_keeper есть предустановленное право HTTPS Access, созданное специально для этих целей и мы рекомендуем использовать его.

Если роль и сотрудник с привилегией на доступ HTTPS у вас уже есть, остается только дать доступ к кассовому серверу. Для этого:

1. Перейдите в меню Сервис > Станции и устройства
2. Выберите ресторан и перейдите на кассовый сервер
3. В свойствах сервера:
   • В поле HTTP Data Port пропишите свободный порт. По желанию, включите настройку Use Free Listen Port, чтобы сервер выбрал другой порт в случае, когда заданный в свойстве HTTP Data Port порт занят.
   • В разделе HTTP Ограничения выберите во всех полях привилегию HTTP_Access
     
4. Сохраните изменения
5. Перезагрузите кассовый сервер.

Если требуется создать отдельную привилегию и роль с правом доступа по HTTPS, нажмите ниже.

Отправка запросов к кассовому серверу должна осуществляться по следующему URL:

https://*IP:HTTPDataPort*/rk7api/v0/xmlinterface.xml

IP:HTTPDataPort необходимо указать свои.

Для доступа к интерфейсу необходимо передавать логин и пароль — название и пароль работника по типу Basic Authorization при отправке каждого запроса.
Обмен данными с кассовым сервером должен происходить в кодировке UTF-8.

Проверка XML-интерфейса через встроенную утилиту

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

• Зайдите по адресу https://ip:port/webgui/iservxmltest.htm. Например, https://127.0.0.1:13665/webgui/iservxmltest.htm
• Введите данные созданного сотрудника: имя пользователя и пароль 
• Введите текст XML-запроса для выполнения
• Нажмите кнопку Execute
  Результат должен быть такой, как на рисунке ниже:
  

Аутентификация и выполнение запросов

Для аутентификация и авторизации используется имя название и пароль работника из r_keeper 7.

WEB-интерфейс на момент написания статьи имеет ограничения:

• Новый WEB интерфейс: https://ip:port/webgui/, например: https://ip:port/webgui/index.htm
• API версии 0 — XML интерфейс и внутренние процедуры r_keeper 7: https://ip:port/rk7api/v0, например: https://ip:port/rk7api/v0/xmlinterface.xml
• API версии 1 — новые функции для взаимодействия с r_keeper 7: https://ip:port/rk7api/v1, например: https://127.0.0.1:13665/rk7api/v1/serverstatus.xml

После указания права и его назначения, соответствующей роли можно проверить корректность настроек, открыв в WEB интерфейсе соответствующие страницы. 

Введите в адресной строке один из вариантов, появится окно авторизации — введите название работника и пароль. Обратите внимание, что вам необходимо ввести свой IP и порт.

• Веб-интерфейс доступен по адресу: https://ip:port/webgui/
  
• https://ip:port/rk7api/v1
  
• https://ip:port/rk7api/v0
  

Выполнение запроса через wget 

Пример выполнения запроса с использованием утилиты wget:

wget.exe --secure-protocol=TLSv1 --no-check-certificate --header="Content-Type: text/xml" --http-user=9006 --http-password=9006 --post-file=requestData.xml https://127.0.0.1:20001/rk7api/v0/xmlinterface.xml

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

• Пользователь: --http-user=9006
• Пароль: --http-password=9006
• Файл с запросом: --post-file=requestData.xml

После выполнения такого запроса его результат будет сохранен в файл xmlinterface.xml.

Настройка работы XML-интерфейса с использованием rk7xml.dll

Внимание!

Данный способ взаимодействия с XML-интерфейсом не рекомендуется из-за отсутствия авторизации.

function CallRK7XMLRPC2(AddressName: PChar; ConnectName:PChar;
  Request: PChar; RequestSize: integer;
  var RequestNum: DWord; //в обе стороны. Если 0, то генерируется сервером.
  ResultFile: PChar;
  ErrorBuf: PChar; ErrorBufSize: integer):BOOL;stdcall;
function CallRK7XMLRPCToStream2(AddressName: PChar; ConnectName,
  Request: PChar; RequestSize: integer;
  var RequestNum: DWord; //в обе стороны. Если 0, то генерируется сервером.
  ResultStream: IStream;
  ErrorBuf: PChar; ErrorBufSize: integer):BOOL;stdcall;
function GetLastXMLResult(AddressName: PChar; ConnectName:PChar;
  out RequestNum: DWord; //всегда возвращается номер последнего выполненного запроса
  ResultFile: PChar; //результат заполнен, если была ошибка передачи данных результата, после успешной передачи стирается
  ErrorBuf: PChar; ErrorBufSize: integer):BOOL;stdcall;
function GetLastXMLResultToStream(AddressName: PChar; ConnectName: PChar;
  out RequestNum: DWord; //всегда возвращается номер последнего выполненного запроса
  ResultStream: IStream; //результат заполнен, если была ошибка передачи данных результата, после успешной передачи стирается
  ErrorBuf: PChar; ErrorBufSize: integer):BOOL;stdcall;

Проверка XML-запросов через TESTXML.exe

Для проверки запроса при использовании rk7xml.dll воспользуйтесь утилитой XMLTEST.exe, которую можно скачать по ссылке или с FTP-сервера по адресу: ftp://FTP.ucs.ru/rk7/ForDealers/XMLInterface/. 

xmltest.exe 127.0.0.1:1122 xmlquery.xml response.xml /pass:password

<?xml version="1.0" encoding="UTF-8"?>
<RK7Query>
<RK7CMD CMD="GetSystemInfo"/>
</RK7Query>

Для удобства существует утилита с графическим интерфейсом TestXML.zip.

Логирование запросов