Инструкция по настройке (v 2.7.2 Beta)

Установка и настройка состоит из двух этапов:

• Настройка в менеджерской части
• Настройка и запуск Farcards

Конфигурация со стороны RK7

Добавление интерфейсов кассового сервера

Добавить на кассовом сервере драйвер PDS Interface с настройками как на скрине:

Название сервера (PDS Server Name) произвольное, главное, чтобы оно совпадало с названием в farcards.ini

Отдельно стоит обратить внимание на настройку "Pass ALL Receipts XML data", если необходимо передавать все чеки(даже без скидочной карты) в процессинг системы лояльности, то нужно выставить "Yes, if possible". Однако надо учитывать, что если на объекте проблемы с интернетом, то при закрытии чеков это может вызывать ошибку. Как временное решение в таком случае, можно изменить значение на "by script". 

Добавить на кассовом сервере драйвер XML interface for Windows

В поле порт указать номер любого свободного порта

Создание логических интерфейсов

В “Сервис” - ”Интерфейсы” создать новый интерфейс и привязать ранее созданный PDS Interface в разделе «Файлы библиотек»:

В “Сервис” - ”Интерфейсы” создать новый интерфейс и привязать ранее созданный XML interface for windows в разделе «Файлы библиотек»:

Для загрузки добавленных драйверов и созданных интерфейсов кассовым сервером, его необходимо перезапустить.

Создание MCR-алгоритма

В “Сервис” – “Обработка сигналов устройств” – “MCR алгоритмы” добавить новый алгоритм.
В настройках алгоритма необходимо указать область применения «Интерфейс», а в объекте указать ранее созданный интерфейс и выставить флаги на типах устройств, которые планируется использовать (пример на скрине):

В свойство скрипт скопировать, убрав дефолтное значение:

begin    
    Result := (
      ( Copy( Parameter, 1, 4 ) = '0000' ) or // префикс MindBoxID из приложения
      (( Length( Parameter ) >= 12 ) and ( Length( Parameter ) <= 13 )) or // Номера карт
      (( Length( Parameter ) >= 6 ) and ( Length( Parameter ) <= 8 )) or // Динамические коды
      (( Length( Parameter ) = 11 ) and
       (( Copy( Parameter, 1, 1 ) = '7' ) or (Copy( Parameter, 1, 1 ) = '8' ))) or // номера телефонов с префиксом
      ( Length( Parameter ) = 10 ) or // номера телефонов без префикса
      ( Parameter = '12345' ) // специальный код
      ) and not GUI.CheckFormInPayMode;
end;

Значения констант в MCR алгоритме должны соответствовать настройкам плагина, их необходимо скорректировать, если вы меняете соответствующие настройки.
Префикс для ввода MindboxId гостя проверяется в строке 3, значение префикса должно совпадать с соответствующей настройкой в плагине.
Диапазон номеров карт проверяется в строке 4, параметры диапазона должны совпадать с соответствующей настройкой в плагине.
Динамический код из мобильного приложения проверяется в строке 5, значение длины кода в символах должно совпадать с соответствующей настройкой в плагине. Если клиент не использует коды из мобильного приложения, строку 5 следует удалить целиком.
Специальный код карты для удаления расчета из заказа и применения промокода в анонимных заказах проверяется в строке 8, значение должно совпадать с соответствующей настройкой в плагине. Если числовой код из строки 8 неудобен персоналу или пересекается с другими MCR алгоритмами, можно заменить его коротким символьным кодом, например "МБ" с помощью следующего кода:

begin    
    Result := (
      ( Copy( Parameter, 1, 4 ) = '0000' ) or // префикс MindBoxID из приложения
      (( Length( Parameter ) >= 12 ) and ( Length( Parameter ) <= 13 )) or // Номера карт
      (( Length( Parameter ) >= 6 ) and ( Length( Parameter ) <= 8 )) or // Динамические коды
      (( Length( Parameter ) = 11 ) and
       (( Copy( Parameter, 1, 1 ) = '7' ) or (Copy( Parameter, 1, 1 ) = '8' ))) or // номера телефонов с префиксом
      ( Length( Parameter ) = 10 ) // номера телефонов без префикса
      ) and not GUI.CheckFormInPayMode;
    if ( Parameter = 'МБ' ) and not GUI.CheckFormInPayMode then
    begin
        Parameter := '12345'; // специальный код
        Result := True;
    end;      
end;

В таком случае в значении Parameter в строке 9 указывается символьный код, а в строке 11 - числовой, совпадающий с соответствующей настройкой в плагине

Добавление скидок

4. В меню “Деньги” – “Скидки” создать 3 скидки. Для удобства и порядка можно создать отдельную папку под эти скидки. Для одновременной работы всех скидок необходимо в настройках каждой скидки изначально задать флаг “Комбинировать с любой скидкой”.

Первая скидка процентная для авторизации карты в заказе:
Название для скидки “Карта MB”
Галочки на “Не вручную” и "На заказ"
Детализация на 0 процентов

Вторая скидка суммовая для Бонусов. 
Название “Бонусы MB”
Галочки на “Не вручную” и "На блюдо"
В настройках надо указать тип «Сумма», в детализации установить значение 100 000.

Третья скидка суммовая для работы доп. акций. 
Название “Скидка MB”
Галочки на “Не вручную” и "На блюдо"
В настройках надо указать тип «Сумма», в детализации установить значение 100 000.

Редактирование скриптов экранных форм

В форме редактирования заказа (обычной и для быстрого чека) нужно добавить скрипты.

Перед редактированием формы, нужно проанализировать актуальную схему и её формы на наличие возможных конфликтующих скриптов.

В самом начале обработчика событий формы нужно вставить текст скриптов и указать верные коды скидок:

// Лояльность mindbox
function MBMarkerCode : Integer;
begin
  Result := 9; // Скидка для авторизации карты лояльности в заказе
end;

function MBBonusCode : Integer;
begin
  Result := 10; // Суммовая скидка для бонусов
end;

function MBActionCode : Integer;
begin
  Result := 11; // Суммовая скидка для акций
end;

function IsMBMarker(O : TObject) : Boolean;
begin
  Result := False;
  if SYS.ObjectInheritsFrom(O, 'TDiscountItem') then
  begin
    Result := TDiscountItem(O).code = MBMarkerCode;
  end;
end;

function IsMBDiscount(O : TObject) : Integer; // 0 - не скидка, 1 - бонусы, 2 - акции
var
  code : integer;
begin
  Result := 0;
  if SYS.ObjectInheritsFrom(O, 'TCheckItem') then
  begin
    code := TCheckItem(O).Code;
    if Code = MBBonusCode then Result := 1
    else if Code = MBActionCode then Result := 2;
  end;
end;

function CheckMBDiscounts : Integer;
var
  i, j : Integer;
  it : TCheckItem;
  dish : TDish;
begin
  Result := 0;
  for i := 0 to RKCheck.CurrentOrder.Sessions.LinesCount - 1 do
  begin
    it := RKCheck.CurrentOrder.Sessions.Lines[i];
    if it.state <> disDeleted then
    begin
      if SYS.ObjectInheritsFrom(it, 'TDish') then
      begin 
        dish := TDish(it);
        for j := 0 to dish.discounts.count - 1 do
        begin
          Result := Result or ( IsMBDiscount( dish.discounts.items[j] )*2 );
          if Result and 6 = 6 then Break;
        end;
      end
      else if IsMBMarker( it ) then Result := Result or 1
      else if SYS.ObjectInheritsFrom(TObject(it), 'TDiscountItem')
      then Result := Result or ( IsMBDiscount( it )*2 );
    end;
    if Result and 7 = 7 then Exit;
  end;
end;

procedure RemoveMBDiscounts;
var
  i, j : Integer;
  it : TCheckItem;
  dish : TDish;
  discount : TCheckItem;    
begin
  for i := 0 to RKCheck.CurrentOrder.Sessions.LinesCount - 1 do
  begin
    it := RKCheck.CurrentOrder.Sessions.Lines[i];
    if it.state <> disDeleted then
    begin
      if SYS.ObjectInheritsFrom(it,'TDish') then
      begin
        dish := TDish(it);
        j := 0;
        while j < dish.discounts.count do
        begin
          discount := dish.discounts.items[j];
          if IsMBDiscount(discount) > 0
          then RKCheck.DeleteCheckItem(discount)
          else j := j + 1;
        end;      
      end
      else if SYS.ObjectInheritsFrom(TObject(it), 'TDiscountItem') and ( IsMBDiscount(it) > 0 )
      then RKCheck.DeleteCheckItem(it);
    end;
  end;
end;

procedure CheckAndRemoveMBDiscounts;
var
  check : Integer;
begin
  check := CheckMBDiscounts; 
  if ( check > 0 ) and ( check and 1 = 0 ) then RemoveMBDiscounts;
end;

// лояльность mindbox - конец кода; дальше код в обработчиках
  

В этой же форме(редактирование заказа и редактирование заказа для быстрого чека) в самом низу добавить данный кусок:

procedure CheckViewOnBeforeCheckViewEdit(Sender: TObject; AEditType: TEditType; AObjectBef, AObjectAft: TObject; var AAllow: boolean; var AMessage: string);
var
  Allow : Boolean;
  HasDiscounts : Integer;
  MarkingModi : TModiItem; // для проверки маркировки
begin
  CheckAndRemoveMBDiscounts;  
  HasDiscounts := CheckMBDiscounts;
  if ( HasDiscounts and 1 = 1 ) and ( HasDiscounts and 6 > 0 ) then
  begin
    Allow := False;
    if (AEditType = etRemove) and IsMBMarker(AObjectBef) then Allow := True;
    if (AEditType = etInsert) and ( IsMBDiscount(AObjectAft) > 0 ) then Allow := True;
    if SYS.ObjectInheritsFrom(AObjectBef, 'TPayLine') or
       SYS.ObjectInheritsFrom(AObjectAft, 'TPayLine') 
    then Allow := True;
    // исключение для ввода маркировки
    if SYS.ObjectInheritsFrom(AObjectAft,'TModiItem') then
    begin
      MarkingModi := TModiItem(AObjectAft);
      if (MarkingModi.Sifr = 2012) or (MarkingModi.Sifr=2112) then Allow := True;
    end;    
    if not Allow then
    begin
      AMessage := 'Редактирование заказа после применения карты лояльности запрещено.';
      AAllow := False;
      Exit;
    end;
  end;  
end;

procedure CheckViewOnOrderVerify(Sender: TObject; AVerifyType: TVerifyType; oper: integer; var AContinue: boolean);
begin
  CheckAndRemoveMBDiscounts;
end;

procedure DesignFormOnOperation(Sender: TBasePanel; Operation, Param: integer; var res: integer);
var
  HasDiscounts : Integer;
begin
  ShowOrderInfo('hide');
  if Operation = 412 then
  begin
    HasDiscounts := CheckMBDiscounts;
    if HasDiscounts and 1 = 1 then
    begin
      res := 1;
      gui.ShowMessage( 'Редактирование заказа после применения карты лояльности запрещено.' );
    end
    else if HasDiscounts and 6 > 0 then RemoveMBDiscounts;
  end
  else if ( Operation = 420 ) or ( Operation = 455 ) then CheckAndRemoveMBDiscounts;
end;

procedure DesignFormOnProcessCard(IntfID, EntranceCardType: integer; CardCode: string; RKCardInfo: TRKCardInfo; var res: integer);
begin
  CheckAndRemoveMBDiscounts;
end;

Настройка и запуск Farcards

Установка Farcards

Запустите инсталлятор MindBoxSetup на компьютере где располагается Midserv, укажите:

• Путь для новой установки ПО
• Сетевое имя Farcards такое же, как указали ранее в параметре PDS Server Name при добавлении драйверов кассового сервера
• Номер TCP порта - любой свободный TCP порт

Нажмите Выполнить и дождитесь завершения установки. Конфигуратор настроек MindBoxSettings запустится автоматически. 

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

Запустите настроек MindBoxSettings (если он не был запущен автоматически после установки). При первом запуске необходимо задать пароль для доступа к настройкам, затем войти, используя заданный пароль. Возможные варианты уже установленных паролей: Gfhjkm1!, 12345 и 123456
Пролицензируйте экземпляр ПО. Для этого сообщите Код запроса и дополнительную информацию о клиенте ответственному за настройку интеграции сотруднику. Перечень дополнительной информации, необходимой для генерации лицензии:

• Наименование ЮЛ
• ИНН КПП
• Фактическое название заведения
• Фактический адрес заведения
• Код ресторана РК
• Идентификатор ПК, на который устанавливается интеграция (любая информация, которая поможет идентифицировать машину - ip (если он статический), сетевое имя, роль (сервер, главная касса и т.д.)
• Контактное лицо: ФИО, телефон, почта
• Код запроса

Введите полученный лицензионный ключ в поле Код ответа и нажмите Сохранить.

Настройки плагина в MindBoxSettings

Укажите необходимые настройки в конфигураторе. Ниже приведено общее изображения окна настроек, описание параметров находится в следующих разделов:

Подключение к API и его настройки

Значение параметров URL API, Ключ API, Endpoint ID, ID ресторана, Имя Id блюд передает менеджер Mindbox, стандартная ссылка: https://api.mindbox.ru/v3/operations/sync

Настройки r_keeper

Код скидки для авторизации карты, Код скидки для бонусов, Код скидки для акций - коды r_keeper соответствующих скидок, созданных ранее.

Код интерфейса - код r_keeper логического PDS интерфейса, созданного ранее.

Использовать скидки на блюдо - предпочитаемое значение по умолчанию "Включено", в случае отключения скидка будет автоматически распределяться самим r-keeper между блюд и появятся копейки при расчетах. Если принимается решение отключить использование скидок на блюда, необходимо изменить настройку у суммовых скидок в r_keeper, созданных ранее: снять флаг "На блюдо" и выставить флаг "На заказ"

Адрес кассового сервера - IP-адрес, по которому доступен кассовый сервер.

Номер порта - порт XML интерфейса, добавленного ранее.

Код кассы, для которой запрашиваются цены - код r_keeper кассовой станции, тип цен которой будет использоваться при загрузке цен в MindBox.

Настройка режимов работы плагина

Выбрать сумму бонусов к списанию - включить/отключить возможность выбрать количество баллов, отличное от максимально возможного в меньшую сторону. Если отключена - можно списывать только максимально доступное для этого пользователя и заказа количество бонусов.

Использовать промокоды - включить/отключить возможность использования промокодов.

Загрузка меню с кассового сервера в процессинг - включить/отключить функцию загрузки меню с кассового сервера в процессинг, при включении активирует дополнительный блок настроек Настройки для загрузки меню в процессинг.

Автоматически удалять старые расчеты через - указывается кол-во часов через которые будут удалены рассчитанные скидки в заказах которые не были закрыты. Используется для разблокирования зарезервированных скидок в случае, если карту добавили, но потом удалили из заказа или в целом весь заказ был аннулирован.

Настройки для загрузки меню в процессинг

Изменить название операции на - используется, если необходимо использовать название операции, отличное от ImportProducts.

ID Бренда - значение поля BrandSystemName в MindBox.

Загрузка цен блюд меню с кассового сервера в процессинг - включить/отключить функции загрузки цен из меню r_keeper в MinBox. Для определения загружаемого типа цен используется код станции r_keeper, указанный ранее. Если включено, активирует поле ID региональных данных для загрузки цен.

ID региональных данных для загрузки цен - значение поля AreaExternalID в MindBox.

Сохранять локальную копию загружаемых данных в файл - включить/отключить сохранение локальной копии загружаемых в MindBox данных в файл. Может быть использована при отладке.

Диапазоны и префиксы

Префикс для ввода mindboxId гостя - используется при вводе короткого id по схеме префикс+id.

Диапазон номеров карт от... до... - согласовывается с Mindbox. Длина не может быть менее 12 символов, чтобы не пересекаться с номерами телефонов. Указываются минимальное и максимальное значение номера карты в диапазоне.

Динамические коды от... до... - диапазон возможных значений динамических кодов в мобильном приложении, согласовывается с MindBox. Указываются минимальное и максимальное значение динамического кода в диапазоне.

Специальный код карты для удаления расчета из заказа и применения промокодов в анонимных заказах - используется в случае если нужно аннулировать расчет по примененной карте в заказе не дожидаясь автоматического удаления расчета, или для применения промокода в анонимном заказе.

Префикс для передачи mindboxId заказа от FastOperator, Префикс для передачи minboxId заказа с сайта -  значение выставляется автоматически при первом сохранении, не менять.

Ведение лога

Записывать лог работы в файл - включить/отключить логирование

Насколько подробным должен быть лог - выставление уровня подробности логирования

Записывать весь http трафик в отдельный файл - включить/отключить дополнительное логирование http-трафика

Логирование по умолчанию используется только для фиксации ошибок. 
При возникновении проблем можно воспользоваться расширенным логированием XML, JSON и трафика HTTP. 

Описание механики работы с промокодами

Применение промокода в анонимном заказе

Если у Гостя нет карты MindBox, но есть промокод, необходимо ввести специальный код из настроек плагина (или его символьный эквивалент из скрипта MCR-алгоритма), например через Код с клавиатуры:

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

В форме экранного ввода ввести промокод:

В окне авторизации нажать на поле [Картинка]:

Промокод применится к заказу.

Применение промокода в авторизованном заказе

Если у гостя есть карта MindBox и промокод, необходимо в первую очередь авторизовать карту Minbox стандартным способом и, после авторизации выбрать кнопку Ввести промокод.
Если авторизация промокода не требуется, следует выбрать кнопку Продолжить без промокода

В форме экранного ввода ввести промокод:

После ввода промокода информация о нем отобразится в поле в правом верхнем углу, и появится следующий набор кнопок:

Не списывать бонусы. Использовать скидку - отказаться от списания бонусов, оставить в заказе только скидку, примененную по промокоду.
Списать Х бонусов - списать максимальное доступное для этого пользователя и заказа количество бонусов (как и в стандартном сценарии работы с картой MindBox).
Выбрать количество бонусов - указать для списания количество бонусов меньшее, чем максимальное доступное для этого пользователя и заказа (как и в стандартном сценарии работы с картой MindBox).

После выбранного сценария работы с бонусами откроется окно авторизации карты, необходимо нажать на поле [Картинка]:

После к заказу применится и скидка по промокоду, и учтутся бонусы (если был выбран соответствующий сценарий)