Настройка FarCards для внешней системы лояльности

Введение

У некоторых компании, использующих r_keeper 7, есть собственная система лояльности. Для интеграции необходимо использовать FarCards. Система позволяет установить связь между r_keeper и внешними CRM-системами.

Связь осуществляется через DLL-библиотеку, которая содержит определенные функции и загружается с помощью FarCards.

При использовании дисконтной, бонусной или платежной карты в POS-терминале r_keeper, кассовый сервер подключается к FarCards, который запускает работу функций в ExtDLL — библиотеке, подключающейся к внешней CRM-системе.

ExtDLL эмулирует поведение сервера карт CARDSERV.

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

DLL, эмулирующая работу персональных карт, должна предоставить функции GetCardInfoEx и TransactionsEx.
Остальные функции не являются обязательными.

Описание ExtDLL.dll

Обязательные функции

Функция GetCardInfoEx

Эта функция возвращает информацию о карте из внешней системы в r_keeper.
До версии 5:
function GetCardInfo (
Card: DWORD;
Info: PCardInfo
): Integer; stdcall;

Параметры:
Card — номер карты
Info — адрес структуры, которую должна заполнять функция, если карта существует

Результат:
0 — без ошибок, структура Info заполнена
1 — карта не существует

Структура, на которую указывает Info:
Word        размер структуры = 344 байта (это поле заполнено при вызове)
Byte        Карта существовала, но была удалена
            0 — нет, и сейчас есть
            1 — да, удалена
При вызове возвращает либо 0, либо номер кассовой станции, на которой происходит оплата

Byte        Карту надо изъять
            0  — нет
            1 — да

Byte        Истек срок действия
            0 — нет
            1 — да

Byte        Сейчас карта не действует
            0 — нет, действует
            1 — да, не действует

Byte        Нужно ли подтверждение менеджера
            0 — не нужно
            1 — нужно

Word       номер скидки
Int64       сумма, доступная для оплаты счета, в копейках
40 byte   Asciiz строка — имя владельца карты
Word      номер бонуса

Byte        Карта заблокирована
            0 — нет
            1 — да
40 byte    Asciiz строка — причина блокировки карты — будет показана на кассе

Int64        предельная сумма, в копейках
DWORD   тип неплательщика
200 byte   Asciiz строка — произвольная информация о карте
Int64        сумма на карточном счете N 2, в копейках
Int64        сумма на карточном счете N 3, в копейках
Int64        сумма на карточном счете N 4, в копейках
Int64        сумма на карточном счете N 5, в копейках

CODE

В случае, если касса присылает свой номер на запрос, номер будет отображен на входе функции в структуре Info в строке Byte со сдвигом 02 — сразу после размера структуры.

Изменения в версии 6:

function GetCardInfoEx (
Card: Int64;
Restaurant, UnitNo: DWORD;
Info: Pointer;
InpBuf: Pointer;
InpLen: DWORD;
InpKind: Word;
var OutBuf: Pointer;
var OutLen: DWORD;
var OutKind: Word
): Integer;
stdcall;

Параметры:
Card — номер карты
Restaurant — код ресторана
UnitNo — номер кассы
Info  — адрес структуры, которую функция должна заполнить,
              если карта существует
InpBuf — дополнительная информация от кассы о заказе
InpLen — длина информации от кассы
InpKind — тип информации от кассы (0 —  нет, 1 — XML)
OutBuf  — дополнительная ответная информация
OutLen — длина ответной информации (не более 150kb)
OutKind — тип ответной информации  (2 — Pr1me, 101 — Пластек)

Результат:
0 — без ошибок, структура Info заполнена
1 — карта не существует



Структура, на которую указывает Info:

Word        размер структуры = 1164 байт (это поле заполнено при вызове)

Byte        Карта существовала, но была удалена
            0 — нет, и сейчас есть
            1 — да, удалена

Byte        Карту надо изъять
            0  — нет
            1 — да

Byte        Истек срок действия
            0 — нет
            1 — да

Byte        Сейчас карта не действует
            0 — нет, действует
            1 — да, не действует

Byte        Нужно ли подтверждение менеджера
            0 — не нужно
            1 — нужно

Byte        Карта заблокирована
            0 — нет
            1 — да
256 байт    Asciiz строка — причина блокировки карты — будет показана на кассе

40 байт     Asciiz строка — имя владельца карты
Int64       Идентификатор владельца карты
DWORD       Номер счета
DWORD       тип неплательщика
Word        номер бонуса
Word        номер скидки
Int64       предельная сумма скидки, в копейках
Int64       сумма, доступная для оплаты счета, в копейках
Int64       сумма на карточном счете N 2, в копейках
Int64       сумма на карточном счете N 3, в копейках
Int64       сумма на карточном счете N 4, в копейках
Int64       сумма на карточном счете N 5, в копейках
Int64       сумма на карточном счете N 6, в копейках
Int64       сумма на карточном счете N 7, в копейках
Int64       сумма на карточном счете N 8, в копейках
256 байт    Asciiz — произвольная информация о карте
256 байт    Asciiz — информация для вывода на экран кассы
256 байт    Asciiz — информация для распечатки на принтере

CODE

Функция TransactionEx

Эта функция проводит транзакции для кассового чека.

Старая версия функции:
function Transaction (
Card: DWORD;
Info: PTransInfo
): Integer; stdcall;

Параметры:
Card — номер карты
Info — адрес структуры, который содержит информацию о транзакции

Результат:
0 — все транзакции проведены
1 — ни одна транзакция не проведена

Структура, на которую указывает Info:

Word        размер структуры = 104 байта
Byte        Тип транзакции
            0 — платеж (снятие денег со счета)
            1 — скидка
            2 — бонус (начисление денег на счет)
            3 — траты гостя (сколько заплатил своих денег)

Int64       сумма, в копейках,
              для типа 0 (платеж):
                оплата с карты  — отрицательная сумма,
                отмена оплаты — положительная сумма;
              для типа 1 (скидка):
                скидка клиенту — отрицательная сумма,
                отмена скидки — положительная сумма;
              для типа 2 (бонус):
                клиенту начисляется бонус  — положительная сумма,
                отмена бонуса — отрицательная сумма;
              для типа 3 (траты):
                клиент заплатил — положительная сумма,
                отмена чека — отрицательная сумма;

Word        код ресторана
DWORD       кассовая дата ( 0 -> 30/12/1899 )
Byte        номер кассы
Word        номер чека А (старая версия, это поле используется, если число не превышает 65535)
Int64       сумма с налогом A
Word        размер налога A в процентах * 100  (1500 -> 15.00%)
Int64       сумма с налогом B
Word        размер налога B в процентах * 100
Int64       сумма с налогом C
Word        размер налога C в процентах * 100
Int64       сумма с налогом D
Word        размер налога D в процентах * 100
Int64       сумма с налогом E
Word        размер налога E в процентах * 100
Int64       сумма с налогом F
Word        размер налога F в процентах * 100
Int64       сумма с налогом G
Word        размер налога G в процентах * 100
Int64       сумма с налогом H
Word        размер налога H в процентах * 100
DWORD      номер чека В  (новая версия, младшее слово такое же, как в номере чека А)

CODE

Новая версия функции:

function TransactionsEx(
Count: DWORD; List: Pointer;
InpBuf: Pointer; InpLen: DWORD; InpKind: Word;
var OutBuf: Pointer; var OutLen: DWORD; var OutKind: Word
): Integer; stdcall;

Параметры:

Count       — количество транзакций
List        — адрес списка, каждый элемент котoрого — ссылка (Pointer) на
              описание транзакции (см. ниже)
InpBuf      — дополнительная информация от кассы о чеке
InpLen      — длина информации от кассы
InpKind     — тип информации от кассы  (0—нет 1—XML)
OutBuf      — дополнительная ответная информация
OutLen      — длина ответной информации (не более 150kb)
OutKind     — тип ответной информации

Результат:

0 — все транзакции проведены
1 — ни одна транзакция не проведена
частичного выполнения быть не должно — либо все проходят, либо ни одна!

Описание одной транзакции

Word        размер структуры = 122 байт
Int64       Карта
Int64       Идентификатор владельца карты
DWORD       Номер счета
Byte        Тип транзакции
            0 — платеж (снятие денег со счета)
            1 — скидка
            2 — бонус (начисление денег на счет)
            3 — затраты гостя (сколько заплатил своих денег)

Int64       сумма, в копейках,
              для типа 0 (платеж):
                оплата снятием денег с карты  — отрицательная сумма,
                отмена оплаты — положительная сумма;
              для типа 1 (скидка):
                скидка клиенту - отрицательная сумма,
                отмена скидки - положительная сумма;
              для типа 2 (бонус):
                клиенту начисляется бонус  - положительная сумма,
                отмена бонуса - отрицательная сумма;
              для типа 3 (затраты):
                клиент заплатил - положительная сумма,
                отмена чека - отрицательная сумма;
Word        код ресторана
DWORD       кассовая дата ( 0 -> 30/12/1899 )
Byte        номер кассы
DWORD       номер чека
   далее информация о налогах в чеке (8 штук)
Int64       сумма с налогом A
Word        размер налога A в процентах * 100  (1500 -> 15.00%)
Int64       сумма с налогом B
Word        размер налога B в процентах * 100
Int64       сумма с налогом C
Word        размер налога C в процентах * 100
Int64       сумма с налогом D
Word        размер налога D в процентах * 100
Int64       сумма с налогом E
Word        размер налога E в процентах * 100
Int64       сумма с налогом F
Word        размер налога F в процентах * 100
Int64       сумма с налогом G
Word        размер налога G в процентах * 100
Int64       сумма с налогом H
Word        размер налога H в процентах * 100

CODE

Дополнительные функции

Функция GetCardImage

function GetCardImage (
Card: DWORD;
Info: PImageInfo
): Integer; stdcall;

Возвращает файл с картинкой для карты, например фотографию владельца или его подпись.
Тип изображения - BMP, JPEG, GIF.
Размер — до 64000. Если больше, изображение будет масштабироваться.

Входные параметры:

Int64       Карта
Info        адрес структуры, которую функция должна заполнить

Результат:

0 — без ошибок
1 — нет карты, либо нет картинки

Структура, на которую указывает Info:

Word        размер структуры = 258 байт

256 байт     Asciiz строка - имя файла с картинкой

CODE

Функция GetCardImageEx

function GetCardImageEx (
Card: Int64;
Info: Pointer
): Integer; stdcall;

Возвращает файл с картинкой для карты, например фотографию владельца
или его подпись.
Тип изображения - BMP, JPEG, GIF.

Входные параметры:

Int64       Карта
Info        адрес структуры, которую функция должна заполнить

результат

0 — без ошибок
1 — нет счета либо нет картинки

Структура, на которую указывает Info:

Word        размер структуры = 258 байт

256 байт     Asciiz строка - имя файла с картинкой

CODE

Функция GetCardMessage

function GetCardMessage (
Card: DWORD;
Info: PMsgInfo
): Integer; stdcall;

Если необходимо, возвращает сообщение, которое будет отображаться на кассовой станции для карты.

Входные параметры:
Card — номер карты
Info — адрес структуры, которую функция должна заполнить

Результат:
0 — без ошибок
1 — нет карты

Структура, на которую указывает Info:
Word        размер структуры = 258 байт
256 bytes     Asciiz строка — сообщение

CODE

Функция GetDiscLevelInfoL

function GetDiscLevelInfoL (
Account: DWORD;
Info: Pointer
): Integer; stdcall;

Возвращает информацию о текущем дисконтном уровне карты

Входные параметры:

Account — номер счета
Info — адрес структуры, которую функция должна заполнить если карта существует

Результат:
0 — без ошибок, структура Info заполнена
1 — cчет не существует

Структура, на которую указывает Info:
Word        размер структуры = 90 байт (это поле заполнено при вызове)
40 байт     Asciiz строка — название текущего дисконтного уровня.
40 байт     Asciiz строка — название cледующего дисконтного уровня.
Int64       сумма, необходимая для перехода на следующий уровень

CODE

Функция CheckInfo (не используется в версии 6)

function CheckInfo (
Card: DWORD;
Info: Pointer;
Size: DWORD
): Integer; stdcall;

Кассовая станция присылает информацию о закрытом чеке в XML-формате.

Входные параметры:
Card — номер карты
Info — буфер, в котором содержится информация о чеке
Size — длина данных

Результат:
0 — без ошибок
1 — карта не существует

CODE

Процедура FindCardsL

procedure FindCardsL(
FindText: PAnsiChar;
CBFind: Pointer;
Back: Pointer
); stdcall;

Поиск счетов по подстроке.

Для каждого найденного счета DLL должна вызывать call-back функцию CBFind().
Первым параметром в ней DLL должна передать Back.
Card и Holder — информация из найденного счета.
Тип функции CBFind:

Процедура CBFind

procedure CBFind(
Back: Pointer;
Account: DWORD;
Card: Int64;
Holder: PAnsiChar
); stdcall;

Процедура AnyInfo

procedure AnyInfo(
InpBuf: Pointer;
InpLen: DWORD;
var OutBuf: Pointer;
var OutLen: DWORD
); stdcall;

Обмен произвольной информацией

InpBuf — информация от кассы
InpLen — длина информации от кассы
OutBuf — ответная информация
OutLen — длина ответной информации

CODE

Функция FindEmail

function FindEmail(
Email: PAnsiChar;
Info: Pointer
): Integer; stdcall;

Поиск счета по e-mail.

Входные параметры:

Email — искомый e-mail
Info — адрес структуры, которую функция должна заполнить, если счет найден

Результат:

0 — без ошибок, структура Info заполнена
1 — cчет не существует

Структура, на которую указывает Info:

Word        размер структуры = 54 байт (это поле заполнено при вызове)
DWORD       Номер счета
Int64       Номер карты
40 байт     Asciiz строка — имя владельца карты

CODE

Процедура FindAccountsByKind(

procedure FindAccountsByKind(
Kind: Integer;
FindText: PAnsiChar;
CBFind: Pointer;
Back: Pointer
); stdcall;

Поиск счетов по разным признакам.

Kind — тип искомой информации
       2 — номер комнаты (для гостиниц)
       3 — по QR коду

Для каждого найденного клиента DLL должна вызывать call-back функцию CBFind().
Первым параметром в ней DLL должна передать Back.
Card и Holder — информация из найденного счета.
Тип функции CBFind:

procedure CBFind( Back: Pointer; Account: DWORD; Card: Int64; Holder: PAnsiChar ); stdcall;

CODE

Дополнительные процедуры

procedure Init; stdcall; — вызовется после загрузки DLL

procedure Done; stdcall; — вызовется перед выгрузкой DLL

Установка

Скопируйте файлы из установочной папки на локальный диск.
Укажите следующие настройки в Farcards.ini:
[FarServer]
Type = 1
DLL = XXXXXX
[ExtDLL]
Server = AServ
где DLL — имя файла
Сервер FarCards.exe

Настройка внешнего модуля

Настройка ExtDLL.ini

Обычно ExtDLL подключается ко внешней системе по сети.
Часто у библиотеки ExtDLL есть свой конфигурационный файл INI.

Пример настройки INI файла:

[Main]
URL=192.168.0.191:90
CacheSecs=30
[Taxes]
1=1
2=2
3=3
[RK]
Charges=16,18
TipCode=12

Настройка сервера

Настройте соответствующий интерфейс внешней системы для приема подключений ExtDLL (FarCards).

Затем настройте соответствующие справочники внешней системы для перевода данных r_keeper.

Настройка в r_keeper 7

Выполните настройку в rk7man.exe аналогично настройке любого из интерфейсов r_keeper CRM, PDS или Shelter.

Вызовите интерфейс с помощью кнопки Код с клавиатуры в doscash.exe, потому что другие способы (из меню выбора валюты) могут включать дополнительные символы или вызывать другие функции, поскольку существует множество различных интеграций.