Введение

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

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

Дистрибутив

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

  • 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
 
; Рабочий каталог, согласно п.3.4.
WorkPath=C:\UCS\Aventa\v.1.0.0.41\
 
; уровень логирования (максимальный = 4)
LogLevel=2
 
; режим отладки
; параметр не обязателен
DebugMode=1
 
; Включение веб-интерфейса со статистикой
; порт сервера
RefServerPort=7251
 
; константа - точка входа для api по сохранению справочников.
; Если нужен веб-интерфейс со статистикой, то обязательно для заполнения.
; Значение можно вписывать произвольное без пробелов и спецсимволов
RefServerAP={A11858BB-8C51-475A-A000-3E82AA1A56C8}
 
; место сохранения справочников при их сохранении через api команду
RefsDefaultPath=C:\UCS\Aventa\Refs
 
[RK]
; IP-адрес кассового сервера r_keeper_7
Server=127.0.0.1
 
; Порт для XML-интерфейса
Port=14441
 
; идентификатор типа цены в РК7 (справочник Меню -> Типы цен)
PriceIdent=3
 
; идентификатор станции
StationIdent=15015
 
; идентификатор типа гостей, необязательный параметр
GuestType=1
UseXML=1
UsePrice=0
 
; идентификатор валюты для предоплаты заказа
PayIdent=1043924
 
; идентификатор причины внесения денег для предоплаты
PrepayReasonIdent=1043926
 
; идентификатор логического интерфейса для связи с системой лояльности (ПДС или СРМ). Необходим для привязки карты к заказу
PayInterfaceIdent=1
 
; идентификатор кассовой станции станции
StationIdent=1
 
; включение (1) или отключение (0) режима создания заказов на одном столе (создание столов с "точкой"), с версии 1.0.0.47
; при отключении (0) интерфейс будет создавать только один заказ в случае разных заказов с одинаковым номером стола 
OneTableMode = 1
 
; идентификатор стола для создания заказов в режиме OneTableMode = 1, с версии 1.0.0.47
OneTableIdent = 12345
 
[License]
; IP адрес сервера лицензий, не менять
Server=l.ucs.ru
 
; Порт для сервера лицензий, не менять
Port=60606
CODE

Важно

Для включения сервера веб-статистики нужно указать порт в параметре RefServerPort и заполнить параметр RefServerAP

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

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

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

Важно!

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

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

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

Примечание

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

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

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

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

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

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

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

Важно!

Важно: поддержано начиная с версий 1.0.0.63.

  1. Заполнить 3 параметра в Settings.ini:

    Settings.ini: 
    ;; Полный путь к существующей папке для сохранения справочников
RefsDefaultPath=D:\UCS\EDI\Refs\                                                               

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

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

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

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

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


Формирование Заказов на доставку осуществляется пользователями в системе сторонней доставки.
 
Сторонний клиент системы доставки должен сформировать файл 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. Указанный стол открыт.

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

Технология дальнейшей обработки Заказа в БД системы доставки в зависимости от результата процедуры выгрузки в БД 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 осуществляется средствами стандартного функционала систем и не предусматривает необходимости обмена данными.

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

Важно!

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

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

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

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

Приложение 1 - Файл нового заказаLink to Приложение 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

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

Добавлены новые типы строк в 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
 

Приложение 2Link to Приложение 2

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

Приложение 3Link to Приложение 3

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

Приложение 4Link to Приложение 4

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

Вложение
Размер

order_new9032.txt

100 байтов