Contents
Description of HTTP Protocol for FarCards
Requirements for processing server:The server can respond using http or httpsxml encoding: only UTF-8It is mandatory to use getcardinfoex or transactionsex. Other functions are optional
Software Requirements: Farcards version 6.04 or above
Dll consists of two modules: 1)the dll for Farcards, ExtDllHTTP.dll2)the licensing utility, Http_LicGen.exe
Settings
ExtDllHttp.ini Description
The file is used by both modules.
[Server]
;Processing server entry point
Address=http://192.168.101.141:80
;address of the GetCardInfoEx function handler, i. e. what is run is http://192.168.101.141:80/getcardinfoex.php
GetCardInfoEx=getcardinfoex.php
;TransactionsEx function handler address
TransactionsEx=transactionsex.php
;FindEmail function handler address
FindEmail=findemail.php
;GetCardImageEx function handler address
GetCardImageEx=getcardimageex.php
;address for notifications on licensing errors
LicenseInfo=licenseinfo.php
;Proxy is used for queries to the UCS licensing server
[Proxy]
;Use proxy (1 means yes; 0 means no)
UseProxy=0
BasicAuthentication=0
Server=127.0.0.1
Port=9944
UserName=
Password=
Available Methods
Receiving Card Information
The method is called using the address defined by the getcardinfoex parameter
Method: POST
Request body:
<?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>
Where:card is the card numberrestaurant is the restaurant ID unitno is the number of the calling POSINPBUF is a buffer containing an XML that has extended information on a card and receipt, for example. More details at XML description of a cash document for provision to external systems
Server response:
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="Vasily Petrovich"/>
<item_content hint="Your coupon allows to select two items from the first group and any item from the second one.">
<group name="group name" printname="Group Name" 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="Group name2" 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>
What is important here is the Result
0 means there are no errors, the Info structure is filled in
1 means the card does not exist
An example when a card is not found:
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>
Receiving Card Image
The method is called using the address defined by the getcardimageex parameter
Method: POST
Request body:
<?xml version="1.0" encoding="UTF-8"?>
<ROOT>
<QRY CardCode="8002"/>
</ROOT>
Where Code is the card number
Depending on whether an image is found or not, the response will differ.If an image is found, the server response will be the following:
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
The image will be retrieved using the DLL.
If an image or a card is not found, the server response will be the following:
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>
Finding Account by E-Mail
The method is called using the address defined by the findemail parameter
Method: POST
Request body:
<?xml version="1.0" encoding="UTF-8"?>
<ROOT>
<QRY Email="director@ucs.ru"/>
</ROOT>
Where Email is the email in question
A successful server response will be the following:
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="UCS director" Result="0"/>
</Root>
Account not found:
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>
Transactions for POS Receipt
The method is called using the address defined by the transactionsex parameter
Method: POST
Request body:
<?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>
Where:
card is a cardPersonID is a cardholder's identifierAccount is an account numberKind is a transaction typeINPBUF is a buffer containing an XML that has extended information on a card and receipt, for example. More details at XML description of a cash document for provision to external systems
0 means a payment (withdrawing money from an account)1 means a discount2 means a bonus (crediting an account)3 means a guest's expenses (how much money a guest paid)
Summa means the amount in kopeks,
for type 0 (payment):
- payment by withdrawing money from a card results in a negative amount,
- payment cancellation results in a positive amount;
for type 1 (discount):
- a discount to a customer results in a negative amount,
- discount cancellation results in a positive amount;
for type 2 (bonus):
- if a customer receives a bonus, that results in a positive amount,
- bonus cancellation results in a negative amount;
for type 3 (expenses):
- if a customer has paid that results in a positive amount,
- receipt cancellation results in a negative amount;
restaurant means a restaurant codeRKDate means a POS date ( 0 → 30/12/1899 )RKUni means a POS numberRKCheck means a receipt numberthen there is information on taxes in a receipt (8 items)VatSumA means an amount with the tax AVatPrcA means the amount of tax A as a percentage * 100 (1500 → 15.00%)VatSumB means an amount with the tax BVatPrcB means the amount of tax B as a percentage * 100VatSumC means an amount with the tax CVatPrcC means the amount of tax C as a percentage * 100VatSumD means an amount with the tax DVatPrcD means the amount of tax D as a percentage * 100VatSumE means an amount with the tax EVatPrcE means the amount of tax E as a percentage * 100VatSumF means an amount with the tax FVatPrcF means the amount of tax F as a percentage * 100VatSumG means an amount with the tax GVatPrcG means the amount of tax G as a percentage * 100VatSumH means an amount with the tax HVatPrcH means the amount of tax H as a percentage * 100
A successful server response will be the following:
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="Text for printing" value="%d" />
</TRRESPONSE>
</OutBuf>
</Root>
Transactions executed with an error:
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="Bank connection error"/>
</OutBuf>
</Root>
Notifications on Licensing Errors
Designed to ensure that in case a dll licensing error occurs the server could find that out by receiving an xml containing an error textThe method is called using the address defined by the LicenseInfo parameter
Method: POST
Request body:
<?xml version="1.0" encoding="UTF-8"?>
<ROOT>
<QRY Restaurant="199990053" Status="License was expired"/>
</ROOT>
Licensing Features
The utility Http_LicGen.exe must be located next to the dll
1)First you add the license wizard for the product interface Farcards-HTTP. Please wait for a notification on successful query processing2)To generate a license, you use the utility Http_LicGen.exe. To sign in to the app, you use the dealer login/password 3)Select a required restaurant from the list.4)Press Get license. Then select the license expiry date. If needed, you can automatically find the maximum license expiry date5)Next…If the query is successful, the following message will appear: License has been created successfully. In case of an error, you will see its textNow you can close the app and launch Farcards