Введение

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

На кассовом сервере возможно создавать свои шаблоны запросов, используя команды, поддержанные тем или иным типом интерфейса. Для самостоятельной интеграции с 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.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 — он отвечает за отключение логирования указанных в параметре запросов. Укажите в поле нужные запросы. 

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

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

• 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.

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

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

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

2. В свойствах сервера справочников прописать порт (параметр 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" в свойствах сервера справочников.

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

4. Для этой роли добавить работника, задать ему пароль. Название и пароль данного работника будут использоваться для авторизации на сервере через 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 интерфейсе соответствующие страницы. 

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

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.