Description of HTTP Protocol for FarCards

Description of HTTP Protocol for FarCards

Requirements for processing server:
The server can respond using http or https
xml encoding: only UTF-8
It is mandatory to use getcardinfoex or transactionsex. Other functions are optional

Software Requirements:
Farcards version 6.04 or above

Dll consists of two modules:

the dll for Farcards, ExtDllHTTP.dll
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>

</HOLDERS>

</INTERFACE>

</INTERFACES>

</EXTINFO>

</CHECK>

</INPBUF>

</QRY>

</ROOT>

Where:
card is the card number
restaurant is the restaurant ID
unitno is the number of the calling POS
INPBUF 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" >

<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>

</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>

</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>

</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>

</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>

</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>

</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>

</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>

</HOLDERS>

</INTERFACE>

</INTERFACES>

</EXTINFO>

</CHECK>

</INPBUF>

</Root>

Where:

card is a card
PersonID is a cardholder’s identifier
Account is an account number
Kind is a transaction type
INPBUF 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 discount
2 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 code
RKDate means a POS date ( 0 → 30/12/1899 )
RKUni means a POS number
RKCheck means a receipt number
then there is information on taxes in a receipt (8 items)
VatSumA means an amount with the tax A
VatPrcA means the amount of tax A as a percentage * 100 (1500 → 15.00%)
VatSumB means an amount with the tax B
VatPrcB means the amount of tax B as a percentage * 100
VatSumC means an amount with the tax C
VatPrcC means the amount of tax C as a percentage * 100
VatSumD means an amount with the tax D
VatPrcD means the amount of tax D as a percentage * 100
VatSumE means an amount with the tax E
VatPrcE means the amount of tax E as a percentage * 100
VatSumF means an amount with the tax F
VatPrcF means the amount of tax F as a percentage * 100
VatSumG means an amount with the tax G
VatPrcG means the amount of tax G as a percentage * 100
VatSumH means an amount with the tax H
VatPrcH 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>

</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>

</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 text
The method is called using the address defined by the LicenseInfo parameter

Method: POST

Request body:

<?xml version="1.0" encoding="UTF-8"?>

<ROOT>

</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 processing
2)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 date
5)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 text
Now you can close the app and launch Farcards

Child pages

Description of HTTP Protocol for FarCards