Two or more anchor identifiers match each others. One of them will be modified. This error happens when some anchor identifiers are generated automatically and others are predefined. Or both are predefined and the operator made a mistake (maybe a copy & paste?)

Введение

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.