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.