Интеграция Абонемент и RK7 через Farcards

Интеграция RK7 с Абонементом представляет собой следующую структурную схему (рис.1)

Рисунок 1

RKeeper при оплате на специальную валюту, например, "Закрытие на фолио Абонемента" в категории "платежные карты" обращается к FarCards, который вызывает подключенную к нему sdmHTTPFarCard.dll. Последняя dll обращается к ключу защиты и если лицензия найдена (проект 2 модуль 11), отправляется XML запрос на TCP/IP сервер - программу HTTPRKtoSH. Этот сервер обращается к базе данных через библиотеку ShelterConnect.dll

Интеграция проверялась на версии Абонемента 145+ с версией RK7 7.6.5.475.

Версия FarCards 6.04
Версия HttpToSH 1.5.0.1
ShelterConnect 1.9.0.3
sdmHTTPFarCard.dll 1.17.0.5

Подготовка утилит

1. FarCards

FarCards устанавливается на любом компьютере в одной сети с кассой и кассовым сервером. Если модуль лицензии прописан в одном ключе с Абонементом, то FarCards обязательно устанавливается на машину, где установлен этот ключ, как правило это сервер, в противном случае необходимо в настройках будет указать ip/port в секции [LOCK.SERVER] машины, где установлен сервер блокировок.

Настройка FARCARDS.INI

[FarServer]
Type = 1
 DLL = sdmHTTPFarCard.dll
Gate = 1
log = 30
XMLCP=1251

[LinkDLL]
1 = pds_netk
 
[pds_netk]
NetServerName=rk_first
ininame=netk.ini
DebugMessages=1

NetServerName - серверное имя. Оно понадобиться в настройках PDS интерфейса RK7.

2. sdmHTTPFarCard.dll

FarCards обращается к sdmHTTPFarCard.dll, которая должна находиться в папке с FarCards. sdmHTTPFarCard.dll защищена ключом защиты Shelter/Абонемент.

Настройки осуществляются в файле HTTPFarCard.ini. Ниже приведен его пример.

[PARAMS]
  ClientCode = HOTEL
  UserCode = UCS
  UserPwd = 12345
  LangCode = RU

[SERVER]
  Port =2277
  Host =127.0.0.1

[LOCK.SERVER]
  TCPHost = 81.94.140.196
  TCPPort = 1116
  Project = 2
  Module = 11   

[LOG]
  FileName=HTTPFarCards_AB.log
  Level = 100
  DebugLevel = 100

В данных настройках sdmHTTPFarCard.dll обращается к TCP/IP серверу, который запущен локально на машине и слушает 2277 порт.

В секции [PARAMS] задаются параметры, которыми обворачивается XML запрос. В Настройках TCP/IP сервера, могут использоваться аналогичные параметры, например для определения «свой/чужой».

В секции [LOCK.SERVER] указывается ip/port машины, где установлен сервер блокировок Shelter/Абонемент.

В файле HTTPFarCards_AB.log ведется логирование XML команд.

SdmHTTPFarCard.dll передает данные на TCP/IP сервер/ Для интеграции с Абонементом используется HTTPRKtoSH.exe

3. HTTPRKtoSH.exe

HTTPRKtoSH.exe является сервером, который слушает TCP/IP и обрабатывает XML запрос от sdmHTTPFarCard.dll. HTTPRKtoSH.exe по умолчанию всегда вызывает функции ShelterConnect.dll, которая должна находить в одной директории с ним. Основные настройки осуществляются в файле HTTPRKtoSH.ini

[SERVER]

[SERVER]
  Port = 2277
  RKInterfaceID=7
  AllCheckToHotel = 1                                      
  IdentPhysType = 2
  Autostart = 1
  Autohide =1

[LOG]
  FileName =  C:\UCS\AbRK7_Example\HTTPtoAB\LOG\HTTPRKtoSH.log
  Level = 30
  DebugLevel =30
  ByMonthes = 1
  ByDays = 1
  ByHours = 1

[MAIN]
messages=errors.msg

Секция [SERVER]

Port - порт, на который будут прилетать данные из sdmHTTPFarCard

RKInterfaceID - Код интерфейса в RK7

4. ShelterConnect.dll

ShelterConnect.ini настроечный файл ShelterConnect.dll, который управляет тем, в каком формате данные будут переданы во внешнюю систему.

[Database]
  DBname    = 81.94.140.196/3080:D:\Base\Garbage\n.kamyshnikova\Vpark2\FITNESS145.FDB
  DBUser     = ucs
  DBPassword = oQKH8n0BFUE=

[ExternalClient]
  ClientID      = 1
  IdentPhysType = 2
  ConvertOperationNeed = 1
  ToOEM = 0
  NeverRestrictTransaction = 1
  FolioMask = 1
  ShowBalance = 0
  ShowBalanceFirst = 0
  RoomInfoMode =4
  TransSection =0
  ConvertOperationType=1  

-по умолчанию 0 - тип "Групп станций". 1 - "Категории заказа"
  (закрывать разные категории заказа на разные услуги,  для случаев разных юр.лиц)

[log]
  FileName   = ShelterConnect.log
  Level      =  100
  DebugLevel =  100

[GarbageCollector]
  Enabled  = 0
  LifeTime = 120

[SCRK6]
  AlcoholicOperation =999
  Messages =sc.msg
  UseScreenHeader0 =1
  UseScreenHeader1 =1
  UseScreenSequelCode =1
  ShowBalance = 1
  ShowBalanceFirst = 1
  ShowBalanceEverywhere = 1
  UseDetails = 1
  UseSuperDetails = 1
 
[TranslateOperation]
     1 = 888
     3 = 888

[TranslatePayment]
  1 = 1005,910
  1000632 = 1005,901
  8 = 1005,901
  3 = 1005,901
    
;[Abonement]
;AbonementIdentCheckResource =ID_RESOURCE

[params]
 Balance_ExtraParamStr = &USE_ABON_FREEBALANCE=1

Секция [DataBase] - параметры подключения к БД Абонемент

[ExternalClient]
ClientID = 1
IdentPhysType = 2 - тип физической карты в Абонементе
ConvertOperationNeed = 1 - использовать секцию [TranslateOperation]
ToOEM = 0 - настройка кодировки
NeverRestrictTransaction = 1 - ( разрешить закрывать на фолио выше кредитного лимита клиента) (баланс в RK будет отображаться, как 99999999999)
FolioMask = 1 - разрешить поиск по фолио ( в рк при оплате на фолио вместо карты можем ввести F#### ( #### - номер фолио))
ShowBalance = 0 - отобразить баланс гостя
ShowBalanceFirst = 0 - отобразить баланс гостя в начале
RoomInfoMode =4 -
TransSection =0
ConvertOperationType=1 -по умолчанию 0 - сопоставлять код "Групп станций". 1 - код "Категории заказа" (закрывать разные категории заказа на разные услуги, для случаев разных юр.лиц)

Секция [SCRK6] не работает при данной схеме связки. Некоторые аналогичные параметры можно использовать в [ExternalClient]

[TranslateOperation]
;Таблица соответствия Кода групп станций r_k и создаваемой в Абонемент услуги.

Код можно посмотреть в RK7

Код услуги в Абонементе.

Настройки на стороне RK7

Все настройки производятся в станции менеджера.

1. Настройка кассовой станции и устройства (Сервис - Станции и устройства)

Добавляем в устройства PDS интерфейс.

Параметр PDS Server Name = rk_first – имя сервера FarCard, через который будет обеспечиваться связь с системой Абонемент.

Внимание! LookupCardByMailAddr = YES

Mail Addr Type Kind = 2

Pass All Receipts XML = Yes, error on not found

Если параметр Pass All Receipts XML data установить Yes, if possible то при закрытии на любую валюту этот заказ будет передаваться в Абонемент. Для этого должны быть сделаны соответствующие настройки в ShelterConnect.ini и в настройках программы. Не рекомендуемая схема работы.

Если PDS interface#1 уже есть, то рекомендуется его удалить и добавить новый.

2. Настройка интерфейса (Сервис - Интерфейсы)

Добавить новый интерфейс. Назовем его RKtoAbonement. См рис. 3 В данном интерфейсе указываем , ранее заведенный PDS interface#1. Код интерфейса нужно запомнить и прописать в файле HTTPRKtoSH.ini. См. настройки HTTPRKtoSH.exe.

Для передачи ППР позиций меню в Абонемент (с версии 136) и последующей печати их в чеке, необходимо в параметр интерфейса xml dish attributes установить как: 2560.ItemKind (Начиная с версии 7.6.5 необходимо поставить 2560.ItemKind.ItemIdent, иначе при передаче вместо значения ППР будет передаваться его GUID)!!!!

xml dish attributes = 2560.ItemKind.ItemIdent

Общая информация по полю XML dish attributes

Для того, чтобы определить из какого справочника запрашивается информация:
для этого:
1. Из строки вида 2560.ItemKind выделяем первое число - 2560
2. Нацело делим число на 256:
3. 2560 mod 256 = 10 - это идентификатор справочника, в данном случае - это MenuItems. (Идентификатор справочников можно посмотреть в таблице REFTABLES)
В полученном справочнике ищем поле ItemKind. Если поле не является ссылочным, то править ничего не нужно, должны выводиться данные из указанного поля.
Если поле ссылочное (можно определить по таблице REFLINKS по комбинации код таблицы+ название поля - если такая комбинация есть в таблице REFLINKS, то поле ссылочное, иначе - нет), то через точку можно получить значения полей из таблицы, на которую ссылается поле.
В рассмотренном примере поле ItemKind ссылается на таблицу с кодом 41 - это ENUMSTYPESDATAS.
Поля, которые можно получить из этой таблицы можно посмотреть xml запросом:

<?xml version="1.0" encoding="UTF-8"?>

<RK7Query>

<RK7CMD CMD="GetRefData" RefName="ENUMSTYPESDATAS" />

</RK7Query>

Если не задано выводимое поле, то выводится guidString (начиная с версии 7.6.5). Если нужно выводить какое-то другое поле, то его нужно указать через точку.
Например:
2560.ItemKind.ItemIdent

Доп. информация из https://docs.rkeeper.ru/pds/ru/tehnicheskaya-dokumentatsiya/podgotovka-xml-dlya-peredachi-v-getcardinfo-ili-transaction

Подготовка XML для передачи в GetCardInfo или Transaction
Xml состоит из нескольких частей, формирующихся в разных модулях. Итоговый xml собирается конкатенацией строк отдельных тэгов в модуле MIDSERV\intfcash.pas->GetXMLText

CHECKDATALink to CHECKDATA
Тэг CHECKDATA со всем содержимым формируется в модуле MIDSERV\ReceiptXML.pas. В CHECKDATA попадают не удаленные строки с блюдами, оплатами/предоплатами и скидками заказа.
Информация делится на данные о блюдах (тэг CHECKLINES), кастомных свойствах заказа (тэг ORDER - в текущий момент закоментирован) и данных по актуальному чеку (все остальные тэги).
Блок может быть пустым: например при проверке баланса карты.

EXTINFO - INTERFACESLink to EXTINFO - INTERFACES
Тэг INTERFACES формируется в модуле MIDSERV\intfcash.pas. В этом тэге указывается карта, добавление которой вызвало операцию, и все карты, добавленные с использованием текущего интерфейса в заказ. При добавлении карты в заказ она не выводится в блоке всех карт, т.к. выполняется только проверка на ее добавление.

Настройки, влияющие на формирование xmlLink to Настройки, влияющие на формирование xml
Xml dish attributes
Формат заполнения:
[Код справочника].[Имя поля]
[Код справочника].[Название поля - ссылки на справочник].[Имя поля]
Можно указать сразу несколько значений, разделенных переносом каретки
где Код справочника - код справочника в Class Infos
Код справочника = RefNo*256+Num. Если Num не указан, то он считается нулевым
Например:
<Rec RefNo="10" Group="3" GUIDString="{E4D77859-5120-486E-A10D-EAB2650584BD}" ciNameOfClass="TRK7MenuItem" ciUserName="Menu Item" ciUserPlName="Menu Items" ciOptions="3" ciNamesUnique="1" ciParentPowCode="1">
10 * 256 + 0 = 2560 - TRK7MenuItem

При заполнении этого параметра в тэге CHECKDATA добавляется дочерний тэг ATTRS. В нем выводится:

type_id - гуид справочника (из ClassInfos)
type_name - Название справочника (из ClassInfos)
key_id - guid промежуточного справочника (из ClassInfos)
key_name - Название промежуточного справочника (из ClassInfos)
value - значение поля

Output mode of non-fiscal payment in xml
Этот параметр отвечает за формат вывода оплат валютами, которые должны печататься как скидки.
Если выбрано значение Write as discount, то такие оплаты будут выводиться, как скидки
Если выбрано значение Write as payment, то такие оплаты будут выводиться, как оплаты не смотря на настройки самой валюты

3. Настройка обработки сигналов. (Сервис - Обработка сигналов и устройств - MCR алгоритм

Указываем тип «Интерфейс». Объект Интерфейс RKtoAbonement, заведенный в пункте 2.

Если указать тип «Валюта», то будет ошибка 232: "Не получается напечатать чек: Персональное ограничение для "" = 0.00."

Можно завести несколько интерфейсов для разных типов идентификаторов. Сделаем два интерфейса, один карт E-Marine и другой для Mifare. Они будут отличаться только названием и содержимым скрипта.

Пример скрипта под E-marine

function MCR1000636(DeviceSignal: Integer; DeviceIdent: Integer; var Parameter: String): Boolean;
var RestCode: integer;
    i, j, t1, t2, S, res1: Integer;
    hex, resulttext: string;
begin
  Result := false;
  if pos('Em-Marine',Parameter)>0 then
  begin
    i := pos(']',Parameter);
    j := pos(',',Parameter);
    resulttext:=copy(Parameter,i+2,3);
    resulttext:=resulttext+copy(Parameter,j+1,5);
      Result := true;
      Parameter:=resulttext;
    end;
end;

Пример скрипта под Mifare

function MCR1000637(DeviceSignal: Integer; DeviceIdent: Integer; var Parameter: String): Boolean;
var RestCode: integer;
    i, j, S: integer;
    res1, t1, t2: int64;
    hex, resulttext: string;
begin
  Result := false;
  if pos('Mifare[',Parameter)>0 then
  begin
    i := pos('[',Parameter);
    j := pos(']',Parameter);
    Parameter := copy(Parameter,i+1, j-i-1);
    if length(Parameter) > 0 then begin
      Result := true;
      res1:=strtoint64('$'+Parameter);
      Parameter:= Int64ToStr(Res1 and $FFFFFFFF );        
    end;
  end;    
end;

4. Настройка валюты (Деньги - валюты)

Заводим валюту в платежных картах. В названии НЕ используем кавычки "".

Так же можно установить наценку для чаевых и чаевые будут передаваться в Абонемент и отдельно там фиксироваться - НЕ ТЕСТИРОВАЛОСЬ.

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

- Без сдачи – флаг установлен

- Доп инфо с клавиатуры – флаг установлен

-Автозаполнение – Вся сумма + подтверждение.

Формат доп инфо - символ F и решетки.(F#########). (Указывается, если необходимо закрывать только на фолио) Символ F является ключевым, для определения типа идентификатора FOLIO.

- Не учитывать в потратах ПДС – флаг должен быть снят.

5. Отображение кнопки оплата картой

Также для отображение кнопки оплаты в интерфейсе кассы необходимо будет настроить параметр оплата платежной картой, который находится в настройках менеджера. (Настройки - параметры - параметры работы станции - редактирование заказа - расчет/оплата заказа - оплата платежной картой, в свойствах поле "значение" установить "спрашивать" )

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

Проверка настройки оплаты

Открываем кассовую станцию, создаем заказ и начисляем блюдо.

Нажимаем на оплатить.

Выбираем платежные карты

Нажимаем на созданную валюту, в нашем случае Abonement

Вводим идентификатор или номер фолио (рис А. идентификатор, рис. Б фолио)

Рисунок А.

Рисунок Б.

После ввода нажимаем на галочку и должны увидеть карточку клиента.

В нашем случае клиент с фолио номер 1598 это IIKO Maylo Maskovich. В зависимости от настройки утилит можно увидеть его реальный баланс. В нашем случае стоит параметр в утилитах на безлимит. Нажимаем на "оплата картой".

Подтверждаем наше действие. После успешной оплаты мы возвращаемся на стартовый экран. Либо мы должны увидеть ошибку в области обозначенной желтым цветом.

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

На фолио должна появится услуга с указанным кодом в ShelterConnect.ini, которая заранее заведена в Абонементе.