HTTP протокол для FarCards
Введение
Требования к процессинговому серверу:
Сервер может отдавать ответ, используя 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
Доступные методы
Получение информации по карте
Вызывается метод по адресу, определенному параметром 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>
Где:
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>
Здесь важен 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>
Получение изображения по карте
Вызывается метод по адресу, определенному параметром getcardimageex
Метод: POST
Тело запроса :
<?xml version="1.0" encoding="UTF-8"?>
<ROOT>
<QRY CardCode="8002"/>
</ROOT>
Где 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
И будет получена картинка средствами 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>
Поиск счета по e-mail
Вызывается метод по адресу, определенному параметром findemail
Метод: POST
Тело запроса:
<?xml version="1.0" encoding="UTF-8"?>
<ROOT>
<QRY Email="director@rkeeper.ru"/>
</ROOT>
Где 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>
Счет не найден:
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>
Транзакции для кассового чека
Вызывается метод по адресу, определенному параметром 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>
Где:
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>
Транзакции выполнились с ошибкой:
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>
Нотификация об ошибках лицензирования
Предназначено для того, чтобы в случае ошибки лицензирования dll, сервер мог узнать об этом, получив xml с текстом ошибки
Вызывается метод по адресу, определенному параметром LicenseInfo
Метод: POST
Тело запроса:
<?xml version="1.0" encoding="UTF-8"?>
<ROOT>
<QRY Restaurant="199990053" Status="License was expired"/>
</ROOT>
Особенности лицензирования
Обязательно утилита Http_LicGen.exe должна лежать рядом с dll
1)Нужно добавить мастер лицензий для продукта interface Farcards-HTTP. Дождемся уведомления об успешной обработке заявки
2)Для генерации лицензии используем утилиту Http_LicGen.exe. Для входа в приложение используем дилерский логин/пароль
3)Выбираем нужный ресторан из списка.
4)Нажимаем «Получить лицензию». Выбираем дату окончания лицензии. При желании можем автоматически узнать максимальную дату окончания лицензии
5)Далее…
При успешном запросе появится сообщение «Лицензия была успешно создана». При возникновении ошибки, появится ее текст
Приложение можно закрыть. Запускаем Farcards