Введение

Требования к процессинговому серверу:
Сервер может отдавать ответ, используя http или https
кодировка xml - только UTF-8
Обязательно использование getcardinfoex и transactionsex. Остальные функции являются опциональными

Требования к ПО:
Farcards версии 6.04 и выше

Dll состоит из 2-х модулей:
1)непосредственно dll для Farcards, ExtDllHTTP.dll
2)утилита для работы с лицензированием, Http_LicGen.exe

Настройки

Описание ExtDllHttp.ini

Файл используется обоими модулями.

[Server]
;Точка входа процессингового сервера
Address=http://192.168.101.141:80
;адрес обработчика функции GetCardInfoEx, т.е. это выполнится http://192.168.101.141:80/getcardinfoex.php
GetCardInfoEx=getcardinfoex.php
;адрес обработчика функции TransactionsEx
TransactionsEx=transactionsex.php
;адрес обработчика функции FindEmail
FindEmail=findemail.php
;адрес обработчика функции GetCardImageEx
GetCardImageEx=getcardimageex.php
;адрес для нотификации ошибок лицензирования
LicenseInfo=licenseinfo.php

;Прокси используется для запросов к системе лицензирования rkeeper
[Proxy]
;Использовать прокси (1-да, 0 - нет)
UseProxy=0
BasicAuthentication=0
Server=127.0.0.1
Port=9944
UserName=
Password
CODE

Доступные методы

Получение информации по карте

Вызывается метод по адресу, определенному параметром getcardinfoex

Метод: POST

Тело запроса:

<?xml version="1.0" encoding="UTF-8"?>
<ROOT>
<QRY Card="8002" Restaurant="9999" UnitNo="2">
    <INPBUF>
    <CHECK stationcode="2" restaurantcode="199999999" cashservername="FOCUS_MIDSERV2" generateddatetime="2013-08-2116:2316:23:56">
    <EXTINFO>
        <INTERFACES>
            <INTERFACE type="PDS" id="1" mode="0">
                <HOLDERS>
                    <ITEM cardcode="8002"/>
                </HOLDERS>
            </INTERFACE>
        </INTERFACES>
    </EXTINFO>
    </CHECK>
    </INPBUF>
</QRY>
</ROOT>
XML

Где:
card - номер карты
restaurant - идентификатор ресторана
unitno - номер вызывающей кассы
INPBUF - буфер, содержащий XML, в котором лежит расширенная информация о карте и чеке, например. Более подробно в XML описание кассового документа для предоставления внешним системам

Ответ сервера:

HTTP/1.1 200 OK
Date: Wed, 21 Aug 2013 08:22:20 GMT
Content-Length: 346
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: text/xml
 
<?xml version="1.0" encoding="utf-8"?>
<Root>
    <GetCardInfoEx CardCode="8002" Account="8002" Deleted="0" Locked="0" Seize="0" Discount="25" Bonus="4" 
    Summa="15000" DiscLimit="10000" Holder="Test farcards person 8002" unpay="4" 
    Sum2="2000" Sum3="3000" Sum4="4000" Sum5="0" 
    DopInfo="additional info" WhyLock="" 
    ScrMessage="** Message for SCREEN **" 
    PrnMessage="* Message for PRINT *" Result="0" >
 
        <OutBuf OutKind="4">
            <ident_info>
              <overide_info code="123456"/>
              <parent_ident code="4547059" printname="Василий Петрович"/>
                          <item_content hint="Ваш купон позволяет выбрать 2 товара из первой группы и любой товар из второй.">
                          <group name="group name" printname="Имя группы" order="1" maxquant="2">
                                  <item code="123" kind="summ" val="10.00" order="3" max="3" default="1" disccode="13"/>     
                                  <item code="321" kind="percent" val="10.00"order="2" max="2" disccode="123"/>            
                                  <item code="213" kind="price" val="10" order="10" max="1"  />                 
                          </group>
                          <group name="group name2" printname="Имя группы2" order="2">
                                  <item code="423" kind="summ" val="130" order="1" line_id="433242" />     
                                  <item code="621" kind="percent" val="1230"order="3" />            
                                  <item code="713" kind="price" val="110" order="2" />          
                          </group>     
                          </item_content>
            </ident_info>  
        </OutBuf>
    </GetCardInfoEx>
</Root>
XML

Здесь важен Result

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

Пример, когда карта не найдена:

HTTP/1.1 200 OK
Date: Wed, 21 Aug 2013 08:23:20 GMT
Content-Length: 346
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: text/xml
 
<?xml version="1.0" encoding="utf-8"?>
<Root>
    <GetCardInfoEx  Result="1" />
</Root>
XML

Получение изображения по карте

Вызывается метод по адресу, определенному параметром getcardimageex

Метод: POST
Тело запроса :

<?xml version="1.0" encoding="UTF-8"?>
<ROOT>
    <QRY CardCode="8002"/>
</ROOT>
XML

Где Code - номер карты

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

HTTP/1.1 200 OK
Date: Wed, 21 Aug 2013 08:22:20 GMT
Content-Length: 5862
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: image/jpg
CODE

И будет получена картинка средствами DLL.

Если изображения не было найдено или карта не найдена, то ответ от сервера будет выглядеть так:

HTTP/1.1 200 OK
Date: Wed, 21 Aug 2013 08:22:20 GMT
Content-Length: 125
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: text/xml
 
<?xml version="1.0"?>
<Root>
<GetCardImageEx ErrorText="Card or image not found"/>
</Root>
CODE

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

Вызывается метод по адресу, определенному параметром findemail

Метод: POST
Тело запроса:

<?xml version="1.0" encoding="UTF-8"?>
<ROOT>
    <QRY Email="director@rkeeper.ru"/>
</ROOT>
CODE

Где Email - интересующий e-mail

Успешный ответ от сервера будет выглядеть так:

HTTP/1.1 200 OK
Date: Wed, 21 Aug 2013 12:40:51 GMT
Content-Length: 123
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: text/xml
 
<?xml version="1.0"?>
<Root>
<FindEmail Account="8002" CardCode="8002" Name="rkeeper director" Result="0"/>
</Root>
CODE

Счет не найден:

HTTP/1.1 200 OK
Date: Wed, 21 Aug 2013 12:40:51 GMT
Content-Length: 123
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: text/xml
 
<?xml version="1.0"?>
<Root>
<FindEmail  Result="1"/>
</Root>
CODE

Транзакции для кассового чека

Вызывается метод по адресу, определенному параметром transactionsex

Метод: POST
Тело запроса:

<?xml version="1.0" encoding="UTF-8"?>
<Root>
    <Transactions>
        <TransactionsEx  Card="32" PersonID="202" Account="145" Kind="160" Summa="15" Restaurant="73" RKDate="2014-08-14T00-00-00" RKUnit="201" RKCheck="139" VatSumA="86" VatPrcA="143" VatSumB="125" VatPrcB="146" VatSumC="93" VatPrcC="119" VatSumD="28" VatPrcD="189" VatSumE="161" VatPrcE="72" VatSumF="178" VatPrcF="80" VatSumG="82" VatPrcG="42" VatSumH="200" VatPrcH="127"/>
        <TransactionsEx  Card="3" PersonID="143" Account="127" Kind="157" Summa="202" Restaurant="73" RKDate="2014-08-14T00-00-00" RKUnit="201" RKCheck="139" VatSumA="77" VatPrcA="59" VatSumB="186" VatPrcB="121" VatSumC="7" VatPrcC="125" VatSumD="254" VatPrcD="161" VatSumE="253" VatPrcE="36" VatSumF="87" VatPrcF="45" VatSumG="178" VatPrcG="81" VatSumH="47" VatPrcH="185"/>
        <TransactionsEx  Card="152" PersonID="86" Account="181" Kind="229" Summa="206" Restaurant="73" RKDate="2014-08-14T00-00-00" RKUnit="201" RKCheck="139" VatSumA="160" VatPrcA="210" VatSumB="93" VatPrcB="120" VatSumC="22" VatPrcC="117" VatSumD="67" VatPrcD="95" VatSumE="199" VatPrcE="95" VatSumF="100" VatPrcF="228" VatSumG="51" VatPrcG="162" VatSumH="56" VatPrcH="190"/>
    </Transactions>
 
    <INPBUF>
        <CHECK stationcode="6" restaurantcode="199999999" cashservername="SHOWRK7MIDSRV1" generateddatetime="2015-05-29T19:09:20" chmode="0">
        <EXTINFO reservation="0">
                    <INTERFACES current="1007682">
                        <INTERFACE type="PDS" id="1007682" mode="0">
                        <HOLDERS>
                                  <ITEM cardcode="777777"/>
                        </HOLDERS>
                        </INTERFACE>
                    </INTERFACES>
        </EXTINFO>
        </CHECK>
 
     </INPBUF>
  </Root>
CODE

Где:

card - Карта
PersonID - Идентификатор владельца карты
Account - Номер счета
Kind - Тип транзакции
INPBUF - буфер, содержащий XML, в котором лежит расширенная информация о карте и чеке, например. Более подробно в XML описание кассового документа для предоставления внешним системам

0 - платеж (снятие денег со счета)
1 - скидка
2 - бонус (начисление денег на счет)
3 - потраты гостя (сколько заплатил своих денег)

Summa - сумма, в копейках,

для типа 0 (платеж):

  • оплата снятием денег с карты - отрицательная сумма,
  • отмена оплаты - положительная сумма;

для типа 1 (скидка):

  • скидка клиенту - отрицательная сумма,
  • отмена скидки - положительная сумма;

для типа 2 (бонус):

  • клиенту начисляется бонус - положительная сумма,
  • отмена бонуса - отрицательная сумма;

для типа 3 (потраты):

  • клиент заплатил - положительная сумма,
  • отмена чека - отрицательная сумма;

    restaurant код ресторана
    RKDate кассовая дата ( 0 → 30/12/1899 )
    RKUni номер кассы
    RKCheck номер чека
    далее информация о налогах в чеке (8 штук)
    VatSumA сумма с налогом A
    VatPrcA размер налога A в процентах * 100 (1500 → 15.00%)
    VatSumB сумма с налогом B
    VatPrcB размер налога B в процентах * 100
    VatSumC сумма с налогом C
    VatPrcC размер налога C в процентах * 100
    VatSumD сумма с налогом D
    VatPrcD размер налога D в процентах * 100
    VatSumE сумма с налогом E
    VatPrcE размер налога E в процентах * 100
    VatSumF сумма с налогом F
    VatPrcF размер налога F в процентах * 100
    VatSumG сумма с налогом G
    VatPrcG размер налога G в процентах * 100
    VatSumH сумма с налогом H
    VatPrcH размер налога H в процентах * 100

Успешный ответ от сервера будет выглядеть так:

HTTP/1.1 200 OK
Date: Wed, 21 Aug 2013 12:56:25 GMT
Content-Length: 65
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: text/xml
 
<?xml version="1.0"?>
<Root>
<TransactionsEx Result="0"/>
                <OutBuf OutKind="1">
              <TRRESPONSE error_code="0" err_text="">
                         <TRANSACTION ext_id="1111111" num="222222" cardcode="777777" slip="Текст для печати" value="%d" />
                 </TRRESPONSE>          
          </OutBuf>
</Root>
CODE

Транзакции выполнились с ошибкой:

HTTP/1.1 200 OK
Date: Wed, 21 Aug 2013 12:56:25 GMT
Content-Length: 65
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: text/xml
 
<?xml version="1.0"?>
<Root>
<TransactionsEx Result="1"/>
                <OutBuf OutKind="1">
              <TRRESPONSE error_code="100500" err_text="Ошибка связи с банком"/>       
          </OutBuf>
</Root>
CODE

Нотификация об ошибках лицензирования

Предназначено для того, чтобы в случае ошибки лицензирования dll, сервер мог узнать об этом, получив xml с текстом ошибки
Вызывается метод по адресу, определенному параметром LicenseInfo
Метод: POST
Тело запроса:

<?xml version="1.0" encoding="UTF-8"?>
<ROOT>
    <QRY Restaurant="199990053" Status="License was expired"/>
</ROOT>
CODE

Особенности лицензирования

Обязательно утилита Http_LicGen.exe должна лежать рядом с dll
1)Нужно добавить мастер лицензий для продукта interface Farcards-HTTP. Дождемся уведомления об успешной обработке заявки
2)Для генерации лицензии используем утилиту Http_LicGen.exe. Для входа в приложение используем дилерский логин/пароль
3)Выбираем нужный ресторан из списка.
4)Нажимаем «Получить лицензию». Выбираем дату окончания лицензии. При желании можем автоматически узнать максимальную дату окончания лицензии
5)Далее…
При успешном запросе появится сообщение «Лицензия была успешно создана». При возникновении ошибки, появится ее текст
Приложение можно закрыть. Запускаем Farcards