Contents

• XML description of a cash document for provision to external systems
  • Purpose
  • General Description
  • Usage Aspects
    • Orders/Receipts
    • Interfaces
    • Extension
• XML Document Description
  • CHECK
    • EXTINFO
    • CHECKDATA
    • XML Document Example
  • Getting Current Interface Code
  • Checking Added Coupon
  • Writing-Off a Coupon for Transactions

XML description of a cash document for provision to external systems

Purpose

This standard has been developed to enable uniform provision of purchase details to external stakeholder systems such as CCTV monitoring systems, loyalty systems, etc.

General Description

POS systems by the UCS company transmit information about receipts to external systems through a number of interfaces; for RKeeper v7 the main interface is FarCards.
Tags are always uppercase, attributes are always lowercase. Date and time are formatted according to XML Date/Time

Usage Aspects

Orders/Receipts

An XML document generated by the POS system has to include all the order details available for the POS at the moment of generating an order. If there are several receipts in one order, an XML document transmits precisely the details of a particular receipt, otherwise of an order (in this case, the CheckNum attribute is not filled in).

Interfaces

Interface is a program element interacting with the POS system, receiving XML documents and able to provide the payment, discount and bonus functionality.
The list of interfaces for which an XML is prepared (according to the POS) is located in the INTERFACES tag of the EXTINFO tag. Without any interference, the interface has to control the compliance of its type to those indicated in the type attributes of the nested INTERFACE tag. The external identifier of an interface also has to be specified in the interface attribute of the Payment, Discount and Bonus tags if a corresponding operation has been assisted by that interface. It is the interface actually involved in generating an operation that is specified. This is necessary for an external system to control the presence/absence of other system interference in the receipt that is being processed.
To identify the calling side, the INTERFACE tag has the current=Х attribute that takes a value equal to the internal identifier of the interface for which an XML document is being generated. The external value of the interface identifier is located in the interface attribute of the INTERFACE tag. To identify a receipt from an external system (external supply), the reservation attribute of the EXTINFO tag is used (filled in upon generating an XML in RKeeper 6).

Extension

Below is a minimal list of mandatory and recommended tags. It is possible to extend it. For example, the ticketkind attribute is not specified in the description but is present in the example. Presence of such attributes is not guaranteed and should be ignored by the receiving side.

XML Document Description

CHECK

top level tag

Acceptable values of the chmode attribute and their description:

Example of a short XML:
<CHECK chmode="0" stationcode="5" restaurantcode="722500001" cashservername="RLSERV" generateddatetime="2012-04-15T21:32:00" locale="1049" shiftdate="xmldate" shiftnum="int" >
<EXTINFO>
<INTERFACES current="12348">
<INTERFACE type="PDS" id="12348" mode="3" interface="8">
<HOLDERS>
<ITEM cardcode="11301867"/>
</HOLDERS>
</INTERFACE>
</INTERFACES>
</EXTINFO>
</CHECK >

EXTINFO

A tag for describing layout purpose: this tag contains tags determining the layout applicability for different systems. If some system is not identified in the list, it is not guaranteed that the document itself will contain any information for it. It is in that system's tag that specific attributes for the target system are transmitted. It is not allowed to add attributes after this tag (as for some system it is generated externally and is based on string substitutions).
Acceptable tags: VIDEO: for CCTV systems

KDS: for KDS/VDU

PDS: for loyalty systems

PDS → HOLDERS: in RK7, when calling in Transaction, all undeleted cards of this interface from the receipt are transmitted and when calling GetCardInfo, only one current card is transmitted. In version 35 the new tag ALLCARDS is added where all cards of that interface are transmitted on which there is information in the order being processed (not only in the receipt). In RK7 these are cards specified in discounts and payments for this interface. But the card for which a request is in progress (if this is the first request) is not transmitted; this card is specified in the cardcode attribute of the INTERFACE tag; if it is a GetCardInfo call, the Transaction is not filled in. PDS → ALLCARDS → ITEM and PDS → HOLDERS → ITEM: tag for a list element with a card in the cardcode attribute.
When SberSpasibo is integrated, in PDS → HOLDERS RK7 adds the card code extracted from additional information about the payment if the payment has been made by a Sberbank card and the terminal driver has filled in the «PdsCard=» in ExtTransactionInfo. To turn this option on in RK7, By script must not be indicated in the property Pass All Receipts XML Data of the pdsempty.dll interface.

EXTDATA

This tag contains information unrelated to the order but related to the context of communication with the external system. Information that is requested from the operator for integration purposes can be transmitted in this tag. Information provided by the customer and entered to the special dialog (for example, an authorization code sent to the customer in a text for two factor authentication) is transmitted in the clientinfoinput attribute starting from 27. The information type in clientinfoinput can be transmitted in the tag attribute which is filled in at the direction of the external system. To request this information, the external system has to return a special XML with the dialog tag, see Coupons are executed through farcards

CHECKDATA

receipt contents

CHECKPERSONS, CHECKLINES, CHECKCATEGS, CHECKDISCOUNTS, CHECKBONUSES CHECKPAYMENTS

tags by receipt string types and their nested tags

For non-distributable extra charges in case there is a connection between the discount and the interface please write not only in the string of the dish type but also in CHECKDISCOUNTS

Type Attribute

String types in the receipt contents:

• undefined: discretionary element
• dish: dish string
• combo: combo dish
• modify: modifier
• ticket: ticket

Combo dishes are recorded the following way: a combo container of the modify type that is referenced by the dish type strings.

XML Document Example

<?xml version="1.0" encoding="utf-8"?>
<--
possible variation:
<?xml version="1.0" encoding="IBM866"?>
-->
<CHECK chmode="4" stationcode="5" restaurantcode="722500001" cashservername="RLSERV" generateddatetime="2012-04-15T21:32:00" shiftdate="xmldate" shiftnum="int">
<EXTINFO reservation="49">
<EXTDATA select="12,123" clientinfoinput="123412" tag="AUTHCODE"/>
<INTERFACES current="12348">
<INTERFACE type="PDS" id="12348" mode="3" interface="8" cardcode="11307">
<HOLDERS>
<ITEM cardcode="11307"/>
</HOLDERS>
<ALLCARDS>
<ITEM cardcode="-999999999"/>
<ITEM cardcode="ucs1"/>
<ITEM cardcode="9511234567"/>
</ALLCARDS>
</INTERFACE>
<INTERFACE type="VIDEO" id="1"/>
<INTERFACE type="KDS" posid="132" id="3"/>
</INTERFACES>
</EXTINFO>
 
<CHECKDATA checknum="102628" guests="2" tablename="1028" startservice="2012-04-15T20:32:00" closedatetime="2012-04-15T21:30:00" ordernum="2944804.1" >
 
<CHECKPERSONS count="2">
<PERSON role="K" name="B. A. Vdovin" code="1234" />
<PERSON role="W" name="A. A. Vdovina" code="3654" />
</CHECKPERSONS>
 
<CHECKLINES count="3">
<LINE id="432" type="dish" name="Herring with garnish" code="7644" quantity="2.00" price="23.60" sum="27.20" servprint="bar" categ="bar2" stored="1">
<ATTRS>
<ATTR type_id="{338D933D-B332-3339-8334-33B733B3733B}" type_name="some_type" key_id="{D38D99CD-BBE2-4939-8414-DFB78FB3776B}" key_name="some name" value="424rfwer5" />
<ATTR type_id="{344D9344-4432-3444-4444-33B73443733B}" type_name="other_type" key_id="{228229CD-B222-4229-8224-D2278223226B}" key_name="other name" value="rsdfsdfwer5" />
 
 
</ATTRS>
<LINETAXES count="2">
<TAX id="2" char="A" sum="3" />
<TAX id="5" char="B" sum="89" />
</LINETAXES>
</LINE>
<LINE id="433242" type="dish" name="Herring without garnish" code="8644" quantity="2.00" price="23.60" sum="27.20" servprint="bar" categ="bar2" last="1" stored="0">
<LINETAXES count="2">
<TAX id="{4DDEC90E-709B-4962-935D-F36B8FBB5B8D};1800" sum="3" />
<TAX id="{1B38B63A-60D9-4162-BFD6-B765CE7E05D5};1000" sum="89" />
</LINETAXES>
<DISCOUNTS count="2">
<DISCOUNTPART id="{0A021EF0-5ED6-45A4-934E-29C8A779B3C2}" sum="-20.00" disclineuni="21214"/>
</DISCOUNTS>
</LINE>
<LINE id="442" parent_line="433242" type="modify" name="without garnish" code="844" quantity="2.00" price="0" sum="0" servprint="bar" categ="bar2" last="1" stored="0"/>
 
<LINE id="412" type="ticket" name="Mega Movie" code="84" quantity="1.00" price="23.60" sum="27.20" categ="action" ticketkind="ordinary" stored="0" >
<LINEPROPS custom="values"/>
</LINE>
</CHECKLINES>
 
<CHECKCATEGS count="2">
<CATEG id="42" code="3" sum="1.17" discsum="0.99" name="FOOD" />
<CATEG id="2" code="3" sum="1.17" discsum="0.99" name="FOOD" />
</CHECKCATEGS>
 
 
<CHECKDISCOUNTS count="1">
<DISCOUNT id="4" code="19" sum="-0.18" name="15%" interface="8" cardcode="11301867" account="2312312312" uni="21214"/>
</CHECKDISCOUNTS>
 
<CHECKBONUSES count="1">
<BONUS id="2" code="12" sum="3" name="2%" interface="9" cardcode="11867" account="2312312312" />
</CHECKBONUSES>
 
<CHECKPAYMENTS count="2">
<PAYMENT id="32" code="HRCP" paytype="3" sum="0.990" name="HR Coupon" interface="8" cardcode="11301867" account="2312312312" ownerinfo="Roman Mikhailovich Pribytkov" extTransactionInfo="12" />
<PAYMENT id="2" code="RUR" paytype="1" sum="200" name="Rubles" />
</CHECKPAYMENTS>
<CHECKTAXES count="2">
<TAX id="2" char="A" code="12" rate="10.00" sum="3" name="VAT" />
<TAX id="2" char="B" code="12" rate="18.00" sum="10" name="VAT" />
<TAX id="5" char="B" code="02" rate="9.00" sum="89" name="Sales Tax" />
</CHECKTAXES>
</CHECKDATA>
 
</CHECK>

Getting Current Interface Code

function tSailPlayProcessor.CurrentInterfaceID(XML: IXmlDocument):Integer;
var
interfaces:IXmlNodeList;
i:integer;
begin
Result:=XML.DocumentElement.NeedChild('EXTINFO').NeedChild('INTERFACES').GetIntAttr('current');
interfaces:=XML.DocumentElement.NeedChild('EXTINFO').NeedChild('INTERFACES').SelectNodes('INTERFACE');
for i:=0 to interfaces.Count-1 do
if (interfaces[i].GetIntAttr('id',Result)=Result) or (Result=0) then begin
Result:=interfaces[i].GetIntAttr('interface',Result);
Break;
end;
end;

Checking Added Coupon

function tSailPlayProcessor.GiftExists(XML: IXmlDocument; sku:string):boolean;
var Discount:IXmlNode;
Lines,Discounts:IXmlNodeList;
i,j,CurrentIntf:integer;
begin
CurrentIntf:=CurrentInterfaceID(XML);
Lines:=XML.DocumentElement.NeedChild('CHECKDATA').NeedChild('CHECKLINES').SelectNodes('LINE');
Discounts:=XML.DocumentElement.NeedChild('CHECKDATA').EnsureChild('CHECKDISCOUNTS').SelectNodes('DISCOUNT');
Result:=False;
for i:=0 to Discounts.Count-1 do begin
Discount:=Discounts[i];
if (Discount.GetIntAttr('interface')=CurrentIntf) and (Discount.GetAttr('objectuni')<>'') then
for j:=0 to Lines.Count-1 do begin
if (Lines[j].GetAttr('uni')=Discount.GetAttr('objectuni')) and (Lines[j].GetAttr('code')=sku) then begin
Result:=True;
exit;
end;
end;
end;
end;

Writing-Off a Coupon for Transactions

procedure tSailPlayProcessor.ProcessGifts(XML: IXmlDocument; return: boolean; Connect: ISailPlayLow);
var Discount:IXmlNode;
Lines,Discounts:IXmlNodeList;
i,j,CurrentIntf:integer;
begin
CurrentIntf:=CurrentInterfaceID(XML);
Lines:=XML.DocumentElement.NeedChild('CHECKDATA').NeedChild('CHECKLINES').SelectNodes('LINE');
Discounts:=XML.DocumentElement.NeedChild('CHECKDATA').EnsureChild('CHECKDISCOUNTS').SelectNodes('DISCOUNT');
for i:=0 to Discounts.Count-1 do begin
Discount:=Discounts[i];
if (Discount.GetIntAttr('interface')=CurrentIntf) and (Discount.GetAttr('objectuni')<>'') and
(Discount.GetIntAttr('code')=GiftDiscountCode) then
for j:=0 to Lines.Count-1 do begin
if Lines[j].GetAttr('uni')=Discount.GetAttr('objectuni') then
Connect.GiftTransaction(Discount.GetAttr('cardcode'),
XML.DocumentElement.NeedChild('CHECKDATA').GetAttr('checkguid'),
Lines[j].GetAttr('code'),
return);
end;
end;
end;
[<span style="color: #0000ff"><span style="text-decoration: underline; ">¹⁾</span></span>]
1
[<span style="color: #0000ff"><span style="text-decoration: underline; ">²⁾</span></span>]
hereinafter: sifr is for RK6, GUID is for RK7
[<span style="color: #0000ff"><span style="text-decoration: underline; ">³⁾</span></span>]
undefined: discretionary element, dish: dish string, combo: combo dish, modify: modifier, ticket: ticket, excluded: tip, not included in the revenue, zero in the receipt
[<span style="color: #0000ff"><span style="text-decoration: underline; ">⁴⁾</span></span>]
4
[<span style="color: #0000ff"><span style="text-decoration: underline; ">⁵⁾</span></span>] , [<span style="color: #0000ff"><span style="text-decoration: underline; ">⁶⁾</span></span>]
for RK7: 'Classification for aggregate shift report'
[<span style="color: #0000ff"><span style="text-decoration: underline; ">⁷⁾</span></span>]
5
[<span style="color: #0000ff"><span style="text-decoration: underline; ">⁸⁾</span></span>]
6
[<span style="color: #0000ff"><span style="text-decoration: underline; ">⁹⁾</span></span>]
7