1. In general
1.1. Sometimes companies, which are using UCS R-Keeper system, have their own loyalty system and want to integrate it with R-Keeper (make possible to accept personal client cards in R-Keeper POS terminals). In such cases UCS provides the "FarCards" solution, which allows connection between R-Keeper and external systems.
1.2. The communication works through DLL which should have certain functions inside and it will be loaded by FarCards.
1.3. When discount/bonus/payment card is detected in R-Keeper POS terminal by algorithm, R-Keeper cash server connects to FarCards, which invokes functions in ExtDLL, which connects to external system.
1.4. ExtDLL emulates UCS cardserver behaviour (new version 6 takes different function names).
1.5. DLL emulating the work of personal cards for cash stations must give the following functions: GetCardInfoEx and TransactionsEx. Other functions are optional.
2. Description of ExtDLL.dll
2.1. Obligatory functions
2.1.1. function GetCardInfo( Card: DWORD; Info: PCardInfo ): Integer; stdcall; (before v.5)
2.1.1.1. This function returns the card information from external system to R-Keeper.
2.1.1.2. entering parameters:
Card - card number;
Info - the address of the structure, which must be filled in by the function if the card exists
2.1.1.3. result
0 - with no errors, Info structure is filled in
1 - card does not exist
2.1.1.4. The structure, at which "Info" points:
Word structure size = 344 bytes (this field is filled in when call is made)
Byte the card existed, but was deleted
0 - no, it still exists
1 - yes, it is deleted
(when it is not 0 when calling, then it is the number of the calling cash station)
Byte the card must be taken away
0 - no
1 - yes
Byte the card is expired
0 - no
1 - yes
Byte now the card is not valid
0 - no, it is valid
1 - yes, it is not valid
Byte manager's confirmation is required
0 - not required
1 - required
Word discount number
Int64 the amount available for payment for a bill, in copecks
40 byte Asciiz line - card holder's name
Word bonus number
Byte the card is frozen
0 - no
1 - yes
40 byte Asciiz line - the reason why the card is frozen - will be displayed on the cash station
Int64 ceiling amount, in copecks
DWORD defaulter type
200 байт Asciiz line - random card information
Int64 amount on the card account N 2, in copecks
Int64 amount on the card account N 3, in copecks
Int64 amount on the card account N 4, in copecks
Int64 amount on the card account N 5, in copecks
In case when the cash station sends its number for a query, the number will be at the function's entrance in the Info structure in the byte with 02 shift - right after the structure size.
2.1.1. changed to (v.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;
2.1.1.2. Parameters (input):
| Card | card number |
| Restaurant | restaurant code |
| UnitNo | station code |
| Info | адрес структуры, которую функция должна заполнить, если карта существует |
| InpBuf | дополнительная информация от кассы о заказе |
| InpLen | длина информации от кассы |
| InpKind | тип информации от кассы (1-XML) |
| OutBuf | дополнительная ответная информация |
| OutLen | длина ответной информации |
| OutKind | тип ответной информации (2-Pr1me) |
2.1.1.3. Result:
| 0 | no error, but "Info" structure filled |
| 1 | card does not exist |
2.1.1.4. The structure, at which "Info" points:
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 - информация для распечатки на принтере
2.1.2. function Transaction( Card: DWORD; Info: PTransInfo ): Integer; stdcall;
2.1.2.1. This function makes the transaction for the card on current order payment.
2.1.2.2. entering parameters:
Card - card number
Info - the ddress of the structure, which contains information about the transaction
result
0 - with no errors
1 - transaction was not made
The structure, at which Info points:
Word structure size = 104 bytes
Byte Transaction type
0 - payment (drawing money from the card)
1 - discount
2 - bonus (depositing money on the card)
3 - guest's expenditures (how much money of his own he spent)
Int64 amount, in copecks,
for the type 0 (payment):
payment from the card - negative amount,
cancel payment - positive amount;
for the type 1 (discount):
discount for the client - negative amount,
cancel discount - positive amount;
for the type 2 (bonus):
bonus is added for the client - positive amount,
cancel bonus - negative amount;
for the type 3 (expenditures):
client paid - positive amount,
cancel receipt - negative amount;
Word restaurant code
DWORD cash station date ( 0 -> 30/12/1899 )
Byte cash station number
Word receipt number A (the old variant, this field can be used if the number never exceeds 65535)
further see the VAT by A B C D taxes information
Int64 amount with tax A
Word the amount of tax A in percent * 100 (1500 -> 15.00%)
Int64 amount with tax B
Word the amount of tax B in percent * 100
Int64 amount with tax C
Word the amount of tax C in percent * 100
Int64 amount with tax D
Word the amount of tax D in percent * 100
Int64 amount with tax E
Word the amount of tax E in percent * 100
Int64 amount with tax F
Word the размер налога F in percent * 100
Int64 amount with tax G
Word the amount of tax G in percent * 100
Int64 amount with tax H
Word the amount of tax H in percent * 100
DWORD receipt B number (new variant, low word is the same as receipt A number)
2.1.2. changed to:
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 - тип информации от кассы (1-XML)
OutBuf - дополнительная ответная информация
OutLen - длина ответной информации
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
2.2. Additional functions
2.2.1. function GetCardImage( Card: DWORD; Info: PImageInfo ): Integer; stdcall;
Returns file with an image for the card, e.g. card holder's photo, or his signature.
Type of the image - BMP, JPEG, GIF.
Pixels - up to 64000, if more - it will be adjusted to scale.
entering parameters:
Card - card number
Info - the address of the structure, which the function must fill in
0 - without errors
1 - no card or image
Structure, at which Info points:
Word structure size = 258 bytes
256 bytes Asciiz line - file name with an image
2.2.1. function GetCardImageEx( Card: Int64; Info: Pointer ): Integer; stdcall;
Возвращает файл с картинкой для карты, например фотографию владельца
или его подпись.
Тип изображения - BMP, JPEG, GIF.
входные параметры:
Int64 Карта
Info адрес структуры, которую функция должна заполнить
результат
0 - без ошибок
1 - нет счета либо нет картинки
Структура, на которую указывает Info:
Word размер структуры = 258 байт
256 байт Asciiz строка - имя файла с картинкой
2.2.2. function GetCardMessage( Card: DWORD; Info: PMsgInfo ): Integer; stdcall;
If needed, returns the message, which will be displayed on the cash station, for the card.
entering parameters:
Card - card number
Info - the address of the structure, which the function must fill in
result
0 - without errors
1 - no card
Structure, at which Info points:
Word structure size = 258 bytes
256 bytes Asciiz line - message
2.2.3. function GetDiscLevelInfo( Card: DWORD; Info: PDLInfo ): Integer; stdcall;
returns the information about the current card discount level
entering parameters:
Card - card number
Info - the address of the structure, which function must fill in, if the card exists
result
0 - without errors, Info structure is filled in
1 - the card does not exist
Structure, at which Info points:
Word structure size = 90 bytes (this field is filled in when call is being made)
40 байт Asciiz line - the name of the current discount level.
40 байт Asciiz строка - нthe name of the next discount level.
Int64 amount, available to go to the next level
2.2.3. function GetDiscLevelInfoL( Account: DWORD; Info: Pointer ): Integer; stdcall;
возвращает информацию о текущем дисконтном уровне карты
входные параметры:
Account - номер счета
Info - адрес структуры, которую функция должна заполнить если карта существует
результат
0 - без ошибок, структура Info заполнена
1 - cчет не существует
Структура, на которую указывает Info:
Word размер структуры = 90 байт (это поле заполнено при вызове)
40 байт Asciiz строка - название текущего дисконтного уровня.
40 байт Asciiz строка - название cледующего дисконтного уровня.
Int64 сумма, необходимая для перехода на следующий уровень
2.2.4. function CheckInfo( Card: DWORD; Info: Pointer; Size: DWORD ): Integer; stdcall; /deprecated in v.6
The cash station sends info about closed bill in XML format .
entering parameters:
Card - card number
Info - buffer, in which there is information about the receipt
Size - information length
result
0 - without errors
1 - no card
2.2.5. procedure FindCardsL( FindText: PAnsiChar; CBFind: Pointer; Back: Pointer ); stdcall;
Поиск счетов по подстроке.
Для каждого найденного счета DLL должна вызывать call-back функцию CBFind().
Первым параметром в ней DLL должна передать Back.
Card и Holder - информация из найденного счета.
Тип функции CBFind:
2.2.6. procedure CBFind( Back: Pointer; Account: DWORD; Card: Int64; Holder: PAnsiChar ); stdcall;
2.2.7. procedure AnyInfo( InpBuf: Pointer; InpLen: DWORD; var OutBuf: Pointer; var OutLen: DWORD ); stdcall;
Обмен произвольной информацией
InpBuf - информация от кассы
InpLen - длина информации от кассы
OutBuf - ответная информация
OutLen - длина ответной информации
2.2.8. 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 строка - имя владельца карты
2.3. Additional procedures
2.3.1. The following procedures can be given:
2.3.1.1. procedure Init; stdcall; - is called after downloading DLL
2.3.1.2. procedure Done; stdcall; - is called after uploading DLL
3. Installation
3.1. Get files
3.1.1. Copy files from installation folder to local drive.
3.2. Farcards.ini
3.2.1. Set like
[FarServer] Type = 1 DLL = XXXXXX [ExtDLL] Server = AServ |
3.2.2. "DLL" - file name.
3.3. FarCards.exe server can be run with keys /desktop (as application) or /service (to install windows service).
4. Setup external module
4.1. ExtDLL ini
4.1.1. Usually, ExtDLL uses network connection to external system.
4.1.2. Often, ExtDLL has its own ini file to set this.
4.1.3. Example format of ini file (like PROTEL link uses: hotel.ini):
| [Main] URL=192.168.0.191:90 CacheSecs=30 [Taxes] 1=1 2=2 3=3 [RK] Charges=16,18 TipCode=12 |
4.2. server side
4.2.1. You need to configure corresponding interface in external system to accept ExtDLL (FarCards) connections
4.2.2. You have to configure references in external system valid to translate R-Keeper data
5. Setup and use RK7 side
5.1. Do configuration in rk7man.exe similar to any UCS CRM/PDS/Shelter interface.
5.2. Call for interface using "Code from keyboard" button on doscash.exe, because other ways (from currency offer) may include additional characters or call for different functions, because there are plenty of specific integrations.