Настройка XML-интерфейса

Введение

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

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

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

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

Вызов функции происходит через RK7XML.dll и интерфейсный модуль RK7XMLi.pas. XML-интерфейс работает через драйвер iTCPXML.dll

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

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

    • Закрытие общей смены
    • Печать отчета

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

На основе XML-интерфейса работают продукты:

  • Мобильный официант
  • Киоск самообслуживания, Kiosk PRO
  • KDS, VDU, KDS Pro
  • Доставка

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

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

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

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

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

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

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

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

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

На кассовом сервере возможно создавать свои шаблоны запросов, используя команды, поддержанные тем или иным типом интерфейса. Для самостоятельной интеграции с r_keeper_7 существует возможность использовать запросы SaveOrder и PayOrder для сохранения заказа. Использование этих запросов защищено лицензией.

Интеграция платная, можно купить бессрочную лицензию или по подписке. Лицензия называется R-keeper модуль XML сохранение заказов ПО и для её приобретения обращайтесь в UCS.

Лицензии бывают ограниченные — по подписке и бессрочные.

Настройки в менеджерской станции

Для работы с кассовым сервером или кассовой станцией необходимо на вкладку "Устройства" добавить “XML Interface For Windows” и прописать порт в параметре Port.

В случае, когда загружаем интерфейс на кассовый сервер, обязательно его привязать к логическому интерфейсу в справочнике "Сервис-Интерфейсы". По-умолчанию это предустановленный XML интерфейс с кодом 104. Однако для каждого внешнего приложения можно сделать копию данного интерфейса и связать его с драйвером на кассовом сервере.

После привязки интерфейса перезагрузите кассовый сервер. Проверьте что интерфейс загружен в свойствах кассового сервера.
Для этого запустите сервер с параметром desktop и откройте его интерфейс. Загруженный интерфейс должен быть виден на вкладке Интерфейсы.

В случае, если необходимо настроить связь с сервером справочников(отчетов), то настраиваем секцию XML интерфейс. 

Работа с внешними запросами

Утилита XMLtest.exe используется для отправки и получения запросов.

Скачать можно с FTP-сервера ftp://ftp.ucs.ru/rk7/ForDealers/XMLInterface/

В системе должен быть установлен msxml.msi.
Формат команды следующий: 

XMLTest <addr>[:<port>] <XMLRequest> [<XMLResult>] [/PASS:XXXXXX] [/CONN:YYYYYY] [/SCHEME:SchemeFileName].
xmltest.exe 127.0.0.1:1122 xmlquery.xml response.xml /pass:password
Описание параметров:
127.0.0.1:1122    ;  IP-адрес и порт, на который настроен XML интерфейс в R-Keeper 7
xmlquery.xml      ;  Имя файла с XML запросом
response.xml      ;  Имя файла, в который следует записать ответ
/pass:password    ;  Пароль, заданный в XML интерфейсе в R-Keeper 7
После выполнения утилита сохранит в файл response.xml ответ от XML интерфейса R-Keeper 7.
Для проверки работоспособности и корректности настроек можно использовать следующий запрос (его следует сохранить в файл xmlquery.xml):
<?xml version="1.0" encoding="UTF-8"?>
<RK7Query>
    <RK7CMD CMD="GetSystemInfo"/>
</RK7Query>

Примечание: для выполнения запроса "SaveOrder" необходима лицензия для ресторана.

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

Для включения логирования запросов необходимо заполнить параметр OutputDir в свойствах вашего XML интерфейса на кассовом сервере или кассовой станции (производится аналогично).

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

Запросы будут парные  - INxxxxx.XML и OUTxxxxx.XML.

Дополнительно можно включить параметр NoLogginQueries — он отвечает за отключение логирования указанных в параметре запросов. Укажите в поле нужные запросы. 

Запросы и функции

Список запросов

# CMD Доступность на
1 GetWaiterMessages CS, ST
2 WaiterMessage CS
3 GetOrderList CS
4 CreateOrder CS
5 GetOrderMenu CS
6 GetWaiterList CS
7 GetRefData CS
8 LoginOnStation CS
9 PayOrder CS
10 PrintBill CS
11 SaveOrder CS
12 DelWaiterMessages CS
13 GetItemBlob CS
14 GetDocByLayout CS
15 DeleteReceipt CS
  • CS - кассовый сервер
  • ST- кассовая станция

Вы можете получить список поддерживаемых запросов на интерфейсе, используя универсальную команду CMD=GetFunctions.

Схемы для запросов (структура и возможные аргументы для каждого запроса) можно найти здесь: ftp://ftp.ucs.ru/rk7/ForDealers/XMLInterface/XML-Schemes/.

Функции

Функция CallRK7XMLRPC - это основная функция 

Параметры данной функции:
AddressName - адрес:порт
Request - XML запрос
RequestSize - размер XML запроса
ResultFile - имя файла, куда будет записан результат выполнения запроса
ErrorBuf - место куда пишутся ошибки соединения
ErrorBufSize - размер ErrorBuf

Функция CallRK7XMLRPCToStream -  аналогична функции выше, но ее результат пишется в поток:

Параметры:
AddressName - адрес:порт
Request - XML запрос
RequestSize - размер XML запроса
ResultStream - IStream - поток, куда передается результат
ErrorBuf - место куда пишутся ошибки соединения
ErrorBufSize - размер ErrorBuf

Функция SetUseTempFileLimit - устанавливает лимит размера файла, если время возвращения результата превышает порог. По-умолчанию = 1000000 ms.

Функция GetDLLVersion - возвращает версию DLL

Функция SetCryptKey - установить ключ шифрования (может быть различным для различных кассовых серверов, прописывается в свойствах XML интерфейса)

Пример запроса файла с сервера

Для получения некоего файла (в формате base64), хранящегося внутри базы справочников, но не импортируемого во внешнюю БД, можно использовать запрос "GetItemBlob".

Запрос в примере, приведенном ниже, вернет макет для отчета с ID=1001 в формате fr3 (filename.fr3).

<?xml version="1.0" encoding="utf-8"?><RK7Query><RK7CMD CMD="GetItemBlob" RefName="OLAPReports" RefItemIdent="1001" RefBlobName="LAYOUT" UnpackedBlob="0"/></RK7Query>

Выполнение XML запросов через HTTPS 7.5.3+

Настройка HTTPS сервера

В менеджерской станции необходимо настроить доступ к серверу справочников через HTTPS.

Для этого необходимо сделать следующее:

  1. В справочнике "Сервис - Менеджерская станция - Привилегии на объекты" добавить новую привилегию, например HTTP_порт.

Рис. Создание привилегии

  1. В свойствах сервера справочников прописать порт (параметр HTTP Data Port) в секции HTTP Server. Флаг Use Free Listen Port необходим, чтобы программа выбрала другой порт в случае, когда заданный в свойстве HTTP Data Port порт занят. Поэтому проверьте сразу свободен ли порт, который вы задаете. В блоке HTTP Ограничения выбрать ограничение, созданное в п 1. После сохранение изменений необходимо перезагрузить сервер. 

Примечание: не только порт, прописанный в свойствах сервера справочников в менеджерской станции (HTTP Data Port) можно использовать для доступа к web-интерфейсу данного сервера, но и порт, прописанный в rk7srv.ini в секции [TSPSOC], параметр port.

Рис. Задание порта "HTTP Data Port" в свойствах сервера справочников.

  1. Создать роль с правами на привилегию из п.1.

Рис. Создание новой роли
  1. Для этой роли добавить работника, задать ему пароль. Название и пароль данного работника будут использоваться для авторизации на сервере через HTTPS.

Аутентификация / авторизация

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

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

На каждый из этих пунктов существует право доступа, задаваемое в свойствах сервера.

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

Вбейте в адресной строке один из вариантов ниже, появится окно авторизации - введите название работника и пароль (рис. выше).

http://ip:port/webgui/

http://ip:port/rk7api/v1

http://ip:port/rk7api/v0

Примеры выполнения запроса

Тестовая страница XML-интерфейса

Для проверки XML интерфейса через HTTPs интерфейс необходимо зайти по адресу https://ip:port/webgui/iservxmltest.htm (например, https://127.0.0.1:13665/webgui/iservxmltest.htm) ввести свои имя пользователя и пароль и текст XML запроса для выполнения. Затем следует нажать кнопку Execute. Результат должен быть такой как на рисунке ниже.

Утилита командной строки 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

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

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