Введение

Требования к процессинговому серверу:

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

Требования к ПО:

  • Farcards версии 6.04 и выше

Dll состоит из 2-х модулей:

  • Dll для Farcards, ExtDllHTTP.dll
  • Утилита для работы с лицензированием, Http_LicGen.exe

Настройки

Описание ExtDllHttp.ini

Файл 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

Где:

Пример ответа:

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 — карта не существует

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

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

Где

  • E-mail — интересующий 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. Закажите мастер-лицензию R-Keeper интерфейс Farcards-HTTP ПО
  2. Для генерации лицензии используйте утилиту Http_LicGen.exe. Для входа в приложение используйте дилерский логин и пароль
  3. Выберите нужный ресторан из списка
  4. Нажмите на кнопку Получить лицензию
  5. Выберите дату окончания лицензии. Узнать максимальную дату окончания лицензии автоматически 
  6. Нажмите на кнопку Далее…

При успешном запросе появится сообщение об успешном создании лицензии.

При возникновении ошибки, появится ее текст.

Приложение Http_LicGen.exe можно закрыть. Запустите Farcards.