Введение
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
<?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.
Для этого необходимо сделать следующее:
- В справочнике "Сервис - Менеджерская станция - Привилегии на объекты" добавить новую привилегию, например HTTP_порт.
Рис. Создание привилегии
- В свойствах сервера справочников прописать порт (параметр 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.
- Для этой роли добавить работника, задать ему пароль. Название и пароль данного работника будут использоваться для авторизации на сервере через HTTPS.

Аутентификация / авторизация
Для аутентификация и авторизации используется имя (название) и пароль работника RK7.
WEB интерфейс на момент написания статьи имеет ограничения:
- Новый WEB интерфейс: http://ip:port/webgui/, например: http://ip:port/webgui/index.htm;
- API версии 0 (xml интерфейс и внутренние процедуры RK7): http://ip:port/rk7api/v0, например: http://ip:port/rk7api/v0/xmlinterface.xml;
- API версии 1 (новые функции для взаимодействия с RK7) http://ip:port/rk7api/v1, например: https://127.0.0.1:13665/rk7api/v1/serverstatus.xml;
На каждый из этих пунктов существует право доступа, задаваемое в свойствах сервера.
После указания права и его назначения соответствующей роли можно проверить корректность настроек, открыв в WEB интерфейсе соответствующие страницы.
Вбейте в адресной строке один из вариантов ниже, появится окно авторизации - введите название работника и пароль (рис. выше).
Примеры выполнения запроса
Тестовая страница 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.