Введение

Модуль ExternalDeliveryInterface (далее EDI) предназначен для обмена информацией между внешней (сторонней) системой  доставки и кассовой системой R-Keeper 7.

Взаимодействие между системами осуществляется посредством обмена файлами в формате CSV. Файлы посредством размещения подготовленных файлов на специальном сетевом ресурсе (директории) на сервере в центральном офисе Компании, а также в сетевых ресурсах (директориях) серверов, установленных в подразделениях (ресторанах) Компании. Указанные сетевые ресурсы должны быть доступны клиентам и серверам систем доставки и R-Keeper 7 через ЛВС (центральный офис) и VPN каналы (подразделения (рестораны)), в том числе при подключении к указанным серверам в терминальном режиме (настройка подключения дисков).

Дистрибутив

Модуль состоит из трех файлов:

  • ExternalDeliveryInterface.exe
  • Settings.ini
  • RK7XML.dll

Дистрибутив модуля доступен на FTP ftp://ftp.ucs.ru/rk7/other/ExternalDeliveryInterface

Настройка

1. В менеджерской РК7 на нужный кассовый сервер добавить драйвер - XML interface for Windows. В его свойствах необходимо прописать порт, например 14441. Привязать данный XML-interface к логическому интерфейсу в справочнике Сервис-XML интерфейсы. Перезагрузить кассовый сервер.

2. Создать стол(-ы) (или использовать имеющийся), на который будут вешаться заказы, приходящие из внешней доставки. Запомнить код стола.

3. Создать директорию, в которой будет происходит обмен файлами, напрмер d:\UCS\EDI\Exchange\

4. Отредактировать файл Settings.ini

[Main]
Frequency=15 ;Частота сканирования рабочего каталога, в секундах
WorkPath=C:\UCS\Aventa\v.1.0.0.41\ ;Рабочий каталог, согласно п.3.4.
LogLevel=2 ; уровень логирования (максимальный = 4)

[RK]
Server=127.0.0.1 ; IP-адрес кассового сервера r_keeper_7
Port=14441 ; Порт для XML-интерфейса
PriceIdent=3 ; идентификатор типа цены в РК7 (справочник Меню -> Типы цен)
StationIdent=15015 ; идентификатор станции
GuestType=1  ; идентификатор типа гостей, необязательный параметр
UseXML=1
UsePrice=0
PayIdent=1043924 ; идентификатор валюты для предоплаты заказа
PrepayReasonIdent=1043926 ; идентификатор причины внесения денег для предоплаты
PayInterfaceIdent=1 ; идентификатор логического интерфейса для связи с системой лояльности (ПДС или СРМ). Необходим для привязки карты к заказу
StationIdent=1 ; идентификатор кассовой станции станции
OneTableMode = 1; включение (1) или отключение (0) режима создания заказов на одном столе (создание столов с "точкой"), с версии 1.0.0.47
                ; при отключении (0) интерфейс будет создавать только один заказ в случае разных заказов с одинаковым номером стола 
OneTableIdent = 12345; идентификатор стола для создания заказов в режиме OneTableMode = 1, с версии 1.0.0.47



[License]
Server=l.ucs.ru ; IP адрес сервера лицензий, не менять
Port=60606 ; Порт для сервера лицензий, не менять

; Необязательные параметры

[Main]
DebugMode=1 ; режим отладки

; Включение веб-интерфейса со статистикой
[Main]
RefServerPort=7251 ; порт сервера

Использование:

http://127.0.0.1:7251/stat - покажет статистику за текущий сеанс
http://127.0.0.1:7251/stat?days=3 - покажет статистику за последние 3 дня

5. Запустить файл ExternalDeliveryInterface.exe.

Важно: Запуск производить от имени администратора!

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

  • в разделе "Запрос Лицензии" нажать кнопку "Сгенерировать запрос" и скопировать код запроса лицензии (см.рис.1).
  • на сервер лицензий сайте l.ucs.ru создать запрос на новое ПО для своего объекта, выбрав для лицензирования модуль "R-Keeper модуль Интерфейс к системе доставки ПО"  (см.рис. 2). 
  • после подтверждения заявки сгенерировать лицензию

Примечание: Код лицензии не выдается - на сервере лицензирования хранится уникальный ключ экземпляра EDI.

Работа программы будет осуществляться при наличии связи с сервером лицензирования ЮСИЭС, т.е. наличие интернета обязательно на момент проверки лицензии! Время очередной проверки лицензии указанно в пункте "Следующая проверка". Если в ресторане нет связи (например возникли проблемы с интернетом) - достаточно подключить любой временный канал связи (USB модем) и нажать кнопку "обновить лицензию". 

Рис.1 Лицензирование

 

Рис.  Оформление заявка на лицензирование EDI в l.ucs.ru

В качестве теста можно подготовить файл, согласно шаблону (см.Приложение 1) и подкинуть его в папку из п.3 раздела Настройка. Этим процессом в дальнейшем будет заниматься внешняя программа Доставки.

В зависимости от таймаута в папке (п.3 раздела Настройки) увидем файл-ответ. (см Приложение 2).

Функциональные операции, предусматривающие обмен данными

Выгрузка меню

Выгрузка происходит автоматически в файл, посредством наведения мышкой на приложение ExternalDeliveryInterface.exe в трее и нажатии на кнопку "Сохранить меню". Далее выберите папку для сохранения и впишите имя файла, например menu.csv. Сохранение возможно только при наличии лицензии.

Если необходимо выгружать справочники для внешней программы доставки без остановки службы EDI, то необходимо сделать следующее:
 
Важно: поддержано начиная с версий 1.0.0.63.
  1. Заполнить 3 параметра в Settings.ini:
  • RefsDefaultPath=D:\UCS\EDI\Refs\                                                               ;; Полный путь к существующей папке для сохранения справочников

  • RefServerPort=7251                                                                                          ;; Свободный порт для http server (прописать в свойствах сервера)

  • RefServerAP={A11858BB-8C51-475A-A000-3E82AA1A56C8}            ;; точка входа в функционал (любое значение), например Уникальный GUID

  1. Открыть в браузере страницу: 127.0.0.1:7251/{A11858BB-8C51-475A-A000-3E82AA1A56C8};

  2. Увидеть сообщение об успешном сохранении справочников или ошибку.

Загрузка нового заказа

Формирование Заказов на доставку осуществляется пользователями в системе сторонней доставки.
 
Сторонний клиент системы доставки должен сформировать файл Order_New<Код_стола>.csv, где <Код_стола> - некоторый 4-х разрядный уникальный целочисленный идентификатор заказа, генерируемый во внешней доставке (например, Order_New9032.csv и OrderParts_New9032.csv), в которых находятся, соответственно, значения полей заказа и строк заказа. Суффикс New – признак первоначальной выгрузки заказа в R-Keeper 7. Формат файла приведен Приложении 1.
 
Файл выгружается в директорию, указанную в п.3.3. Программное приложение (ExternalDeliveryInterface.exe), реализующее интерфейс обмена данными между внешней системой доставки и R-Keeper 7 осуществляет автоматическое периодическое сканирование ресурса (папки, созданной в п.3.3) на предмет наличия в них файлов импорта Заказов. При обнаружении в папке выгруженных файлов Заказов, осуществляется процедура импорта данных в R-Keeper 7. После проведения процедуры импорта, обработанные файлы удаляются из адресной директории и создается файл-ответ.
 
При импорте Заказа в R-Keeper 7 открывается стол, при этом: 
  • код стола должен соответствовать параметру <Код_стола> указанному в наименовании и составе соответствующего файла импорта;
  • Дата и время открытия стола соответствуют дате и времени Заказа, указанным в БД системы доставки;
  • количество гостей, должно соответствовать количеству гостей в R-Keeper 7 и БД системы доставки;
  • шифр официанта - код работника из R-Keeper 7;
  • тип магнитной карты - тип магнитной карты в свойствах скидки из R-keeper 7, которую необходимо применить к заказу.
Заказ сохраняется в R-Keeper 7 в виде открытого (неоплаченного) стола с одновременной автоматической отправкой печати чеков на принтеры с распределением по цехам производства (сервис-печать) средствами системы R-Keeper 7 (аналог функции в R-Keeper ”сохранить заказ”).

Предупреждение: в справочнике R-Keeper 7 должно заведено столько столов с кодами, сколько столов используется во внешней доставке, т.к. если в файле указать номер несуществующего стола, то импорт не произойдет. Соответсвенно количество гостей в файле не должно превышать количество гостей в свойствах стола в менеджерской РК7. На открытый стол повторно повесить другой заказ тоже нельзя.

Одному новому заказу соответствует один файл .csv с определенным номером стола.
 
Через установленный промежуток времени, клиент системы доставки ищет файл State_New<Код_стола>.csv в директории адресного сетевого ресурса обмена данными на сервере в подразделении (ресторане) Компании, где <Код_стола> - некоторый 4-х разрядный уникальный целочисленный идентификатор заказа, ранее переданный в R-Keeper в наименовании и составе соответствующего файла экспорта Заказа Order_New<Код_стола>.csv. В этом файле может быть указан один из трех вариантов ответа от R_Keeper 7: 
1 - заказ успешно выгружен в стол <номер_стола>; 
0 – указанный стол <Номер_стол> уже открыт, заказ не выгружен; 
2 - заказ не выгружен <текст ошибки>, 
где <текст ошибки> - текст ошибки, генерируемой сервером приложений R-Keeper, по причине которой не был выгружен Заказ. 
Пример файла-ответа приведен в Приложении 2.
 
Примечание: Результат импорта-экспорта заказа в систему R-Keeper отмечается в специальном информационном поле бланка Заказа в системе системы доставки.
 
В случае отсутствия файла с уведомлением об импорте Заказа проставляется – Заказ не получен R-Keeper
В случае флага «0» - Заказ получен, но не импортирован в R-Keeper;
В случае флага «1» - Заказ получен и импортирован в R-Keeper;
В случае флага «2» - Заказ получен, но не импортирован в R-Keeper. Указанный стол открыт.
 

Загрузка изменений в заказ

Технология дальнейшей обработки Заказа в БД системы доставки в зависимости от результата процедуры выгрузки в БД R-Keeper 7 будет прорабатываться в отдельной постановке задачи. 
В случае повторной выгрузки измененного Заказа из системы доставки в R-Keeper 7, т.е. экспорта-импорта ранее уже выгруженного Заказа, измененный Заказ выгружается из системы доставки только в части изменения кол-ва гостей и данных о добавленных новых позициях состава Заказа (в том числе увеличения кол-ва ранее выгруженных позиций), в формате Order_Edit<Код_стола>.csv
 
Примечание: В случае увеличения кол-ва ранее выгруженных позиций состава Заказа в файле экспорта изменений в колонке «Количество» передается значение разности между старым и новым значением количества заказанной позиции.
 
Удаление позиций из состава Заказа, а также уменьшение количества ранее выгруженных позиций не выгружается из системы доставки и не обрабатывается системой R-Keeper 7. При этом программный интерфейс обмена данными системы R-Keeper 7 должен классифицировать и обработать данный Заказ, как уже ранее выгруженный, чтобы исключить дублирования заказов в БД R-Keeper 7, а именно: 
- произвести изменение кол-ва гостей для соответствующего открытого стола в БД R-Keeper 7;
- добавить позиции (или увеличить кол-во ранее выгруженных позиций) из состава Заказа в соответствующий открытый стол в БД R-Keeper.
 
По результатам импорта изменений Заказа программный интерфейс обмена данными R-Keeper 7 возвращает файл State_Edit<Код_стола>.csv. В этом файле может быть указан один из трех вариантов ответа от R_Keeper: 
1 – изменения заказа успешно выгружены в стол <номер_стола>; 
0 – указанный стол <Номер_стол> закрыт, изменения заказа не выгружены; 
2 – изменения заказа не выгружены <текст ошибки>.
 
Форматы файлов экспорта-импорта изменений Заказов, а также ответных результатов выгрузки этих изменений приведены в Приложениях 3 и 4. Правила маршрутизации и размещения файлов экспорта-импорта изменений аналогичны правилам первоначальной выгрузки Заказов, описанным выше.
 
Закрытие Заказа в системе доставки и стола в R-Keeper 7 осуществляется средствами стандартного функционала систем и не предусматривает необходимости обмена данными.

Привязка карты к заказу

Важно: доработка реализована с версии 1.0.0.40

Для указания карты добавляем к формату строки (CSV) 6-м параметром номер карты. Касса в таком случае будет вести себя так как же, как если бы мы прокатали карту на кассе физически.

В Settings.ini заполнить следующие параметры:
[RK]
;идентификатор логического интерфейса (справочник Сервис - Интерфейсы в менеджерской станции), используемого для связи с системой лояльности (ПДС или R-Keeper CRM).
PayInterfaceIdent=1
;идентификатор кассовой станции, на которой происходит обработка заказов из EDI
StationIdent=1

Форматы файлов обмена

Приложение 1 - Файл нового заказа

Формат файла импорта-экспорта нового Заказа. (WIN-кодировка).
 
1-я строка  \\  НОМЕР СТОЛА;ДАТА;КОЛ-ВО ГОСТЕЙ;КОД ОФИЦИАНТА;ТИП МАГНИТНОЙ КАРТЫ(=тип магнитной карты в свойствах скидки);КАРТА ЛОЯЛЬНОСТИ; НОМЕР БРОНИ; БАЛЛЫ; ВРЕМЯ ПОДАЧИ; ВРЕМЯ ПЕЧАТИ; КОММЕНТАРИЙ
 
2..N строки \\  ВНЕШНИЙ КОД ПРОДУКТА;ЦЕНА;КОЛИЧЕСТВО;ТИП ПРОДУКТА(БЛЮДО или МОДИФИКАТОР , Для Блюда=0, для модификатора=1)
 
Пример файла:
 
9032;06.03.2008 10:38:08;2;465;44
45;10,5;7;0
46;25,1;4;0
Файл примера приведен в Order_New9032.csv
 
Начиная с версии 1.0.0.41 в первом поле в скобках после номера стола будет добавляться номер заказа, например:

9945(273716537165);01.10.2014 19:28:02;1;275
191;355,5;1;0

Работа с комбо

Добавлены новые типы строк в csv:
2 - комбо элемент меню. 
3 - комбо элемент.
4 - элемент меню, связанный с комбо-элементом
5 - модификатор для элемента меню.
 
Пример создания комбо-обеда, которое состоит из:
салат цезарь
- с семгой (модификатор)
-каппучино
 
1;01.09.2015 17:49;5;5
13;0;1;2 - комбо элемент меню (Обед)
5;0;1;3 - комбо элемент (цезарь) 
6277;0;1;4 - блюдо цезарь, с которым связан комбо-элемент
1;0;1;5 - модификатор (с семгой)
7;0;1;3 - комбо элемент (каппучино)
3029;0;1;4 - блюдо каппучино
 
Важно: везде используются внешние коды элементов.
 
Пример 2
 
Рис. Пример файла с комбо-блюдами

Приложение 2

Формат файла результатов импорта-экспорта нового Заказа. (WIN-кодировка).
1 - заказ успешно выгружен в стол 9032
Файл примера приведен в State_New9032.csv

Приложение 3

Формат файла импорта-экспорта изменений существующего Заказа. (WIN-кодировка).
КОД СТОЛА;ДАТА;КОЛ-ВО ГОСТЕЙ
9032;06.03.2008 10:38;2
ВНЕШНИЙ КОД ПРОДУКТА;ЦЕНА;КОЛИЧЕСТВО
45;10,5;3
46;25,1;4
Файл примера приведен в Order_Edit9032.csv

Приложение 4

Формат файла результатов импорта-экспорта изменений существующего Заказа. (WIN-кодировка).
0 - указанный стол 9032 закрыт, изменения заказа не выгружены
Файл примера приведен в State_Edit9032.csv
ВложениеРазмер
order_new9032.txt100 байтов