Introduction
The XML interface is the most convenient way of getting information about the RK7 system and saving data in the RK7 databases, as well as performing different operations.
There are three kinds of interfaces in r_keeper 7:
- For cash stations
- For cash servers
- For reference or report servers.
Each type of interface supports a different set of commands.
The function is called using the RK7XML.dll and the RK7XMLi.pas interface module. The XML interface runs using the iTCPXML.dll driver.
The XML enables the following:
- Viewing data from references and collections — true for all kinds of interfaces
- Creating new reference elements and editing the attributes of existing ones — true only for reference servers
- Getting information on current orders, creating and managing existing orders. Performing any cash register operations — only for the cash server
Examples of operations: - Close common shift
- Report printing.
The overall interaction scheme is given below:
The following products operate based on the XML interface:
- Mobile waiter
- Self-service Kioks, Kiosk PRO
- KDS, VDU, KDS Pro
- Delivery.
Possibilities of Reference Server Interfaces
- Viewing reference elements
- Editing the attributes of existing reference elements
- Creating new reference elements.
They are usually used for the following:
- Integrating with the restaurant's website – unloading the menu
- Unloading the menu, prices, and other parameters to an external delivery service
- Unloading the range to external accounting systems, for example, 1C
- Unloading the menu, prices and other parameters to the reference server.
Possibilities of Cash Server Interfaces
- Reading the references
- Reading the information on current orders
- Creating and editing orders
- Performing cash register operations.
They are usually used for the following:
- Integrating with the restaurant's delivery service – the full cycle from creating an order to payment
- Integrating mobile apps, self-service, delivery systems, etc.
- Monitoring the current sales status and other issues
- Integrating with loyalty programs
- Integrating with video surveillance systems.
Possibilities of Cash Station XML Interface
- Adding a dish to an open order
- Viewing the items that are part of an open order at the cash station
- Performing cash register operations — swiping the card, requesting card information
- Paying for the current order.
Licensing
A cash register server allows you to create request templates using the commands supported by a certain interface type. To independently integrate with r_keeper 7 you can use the SaveOrder and PayOrder requests for saving an order. The use of these requests is protected by a license.
The integration is fee-based. It is possible to buy an unlimited license or subscribe. The license is called R-keeper XML Module Order Saving Software; contact r_keeper to buy it.
A license can be temporary (by subscription) and unlimited.
Manager station settings
In order to work with the cash server or a cash station, it is necessary to add the XML Interface For Windows in the Drivers tab and specify a port in the Port parameter.
If the interface is uploaded to the cash register server, it is necessary to link it to the logical interface in the Service > Interfaces reference. By default, it is a preset XML interface with a 104 code. But it is possible to make a copy of this interface for each external app and link it to the driver on the cash server.
After linking the interface, restart the cash server. Make sure that the interface is loaded in the cash server properties.
To do so, launch the server with the /desktop parameter and open its interface. The loaded interface should be located on the Interfaces tab.
If you need to set up a connection with the reference or report server, set up the XML interface section.
Processing External Requests
The XMLtest.exe utility is used for sending and receiving requests.
You can download it from the FTP server ftp://ftp.ucs.ru/rk7/ForDealers/XMLInterface/
The msxml.msi should be installed in the system.
The command has the following format:
XMLTest <addr>[:<port>] <XMLRequest> [<XMLResult>] [/PASS:XXXXXX] [/CONN:YYYYYY] [/SCHEME:SchemeFileName]. |
xmltest.exe 127.0.0.1:1122 xmlquery.xml response.xml /pass:passwordParameter description:
127.0.0.1:1122 ; IP address and the port which is used to set up the XML interface in r_keeper 7
xmlquery.xml ; The name of the file with XML request
response.xml ; The name of the file where the response should be saved
/pass:password ; The password set in the XML interface in r_keeper 7
After running the utility will save the response from r_keeper 7's XML interface into the response.xml file.
To check the operation and settings, the following request can be used (it should be saved it in the xmlquery.xml file):
<?xml version="1.0" encoding="UTF-8"?>
<RK7Query>
<RK7CMD CMD="GetSystemInfo"/>
</RK7Query>
| Info |
|---|
| A license for the restaurant is needed to perform the SaveOrder request. |
Logging Requests
To turn on request logging you need to specify in the OutputDir parameter in the attributes of your XML interface at the cash server or at the cash station (the procedure is identical).
| Info |
|---|
| Important: restart the cash server after making the changes. |
The requests will be paired: INxxxxx.XML and OUTxxxxx.XML.
It is also possible to switch on the NoLogginQueries parameter which is responsible for switching off the logging of the requests specified in the parameter. Specify the necessary requests in the field.
Requests and Functions
Request List
...
#
...
CMD
...
Available at
...
1
...
GetWaiterMessages
...
CS, ST
...
2
...
WaiterMessage
...
CS
...
3
...
GetOrderList
...
CS
...
4
...
CreateOrder
...
CS
...
5
...
GetOrderMenu
...
CS
...
6
...
GetWaiterList
...
CS
...
7
...
GetRefData
...
CS
...
8
...
LoginOnStation
...
CS
...
9
...
PayOrder
...
CS
...
10
...
PrintBill
...
CS
...
11
...
SaveOrder
...
CS
...
12
...
DelWaiterMessages
...
CS
...
13
...
GetItemBlob
...
CS
...
14
...
GetDocByLayout
...
CS
...
15
...
DeleteReceipt
...
CS
- CS — cash server
- ST — cash station
You can get a list of interface requests supported by the interface using the CMD=GetFunctions universal command.
You can find the request schemes (structure and possible arguments for each request) at FTP server: ftp://ftp.ucs.ru/rk7/ForDealers/XMLInterface/XML-Schemes/.
Functions
CallRK7XMLRPC is the main function.
The function has the following parameters:
AddressName — address: port
Request — XML request
RequestSize — XML request size
ResultFile — the name of the file to save the request execution result
ErrorBuf — the location where connection errors are saved
ErrorBufSize — ErrorBuf size
The CallRK7XMLRPCToStream function is similar to the one above, but its result is written as a stream:
Parameters:
AddressName — address: port
Request — XML request
RequestSize — XML request size
ResultStream - IStream — the stream where the result is transmitted to
ErrorBuf — the location where connection errors are saved
ErrorBufSize — ErrorBuf size
The SetUseTempFileLimit function sets the file size limit if the result return time exceeds a threshold. By default, it is 1000000 ms.
The GetDLLVersion returns the DLL version
The SetCryptKey function sets an encryption key (can differ for different cash servers, is set in the XML interface attributes)
An example of a file request from a server
To receive a file (in the base64 format) stored in the reference database but not imported into an external database, the GetItemBlob request can be used.
In response to the request given in the example below, a report layout will be returned with an ID=1001 in the fr3 format (filename.fr3).
<?xml version="1.0" encoding="utf-8"?><RK7Query><RK7CMD CMD="GetItemBlob" RefName="OLAPReports" RefItemIdent="1001" RefBlobName="LAYOUT" UnpackedBlob="0"/></RK7Query>Performing XML Requests Using HTTPS 7.5.3+
HTTPS Server Setup
It is necessary to set up the access to the reference server using HTTPS in the manager station.
You need to do the following:
...
Specify the port (HTTP Data Port parameter) in the reference server settings in the HTTP Server section. It is necessary to check the Use Free Listen Port box so that the program could select another port if the one set in the HTTP Data Port property is busy. For this reason, check if the port you are setting is free. Select the restriction set in Item 1 in the HTTP Restrictions block. You need to restart the server after saving the changes.
| Info |
|---|
You can use both the port specified in the reference server properties in the manager station (HTTP Data Port) and the port listed in rk7srv.ini in the port parameter in the [TSPSOC] section for accessing the server's web interface. |
Create a role with a right to the privilege from Item 1.
| Info |
|---|
Only roles of the current restaurant and the head office are used for HTTP requests authorization. |
...
Authentication/Authorization
An RK7 employee's name and password are used for authentication and authorization.
The WEB interface has the following limitations at the time this article is written:
- A new WEB interface: http://ip:port/webgui/, for example: http://ip:port/webgui/index.htm;
- API version 0 (xml interface and internal RK7 procedures): http://ip:port/rk7api/v0, for example: http://ip:port/rk7api/v0/xmlinterface.xml;
- API version 1 (new functions for interacting with RK7) http://ip:port/rk7api/v1, for example: https://127.0.0.1:13665/rk7api/v1/serverstatus.xml;
There is an access right for each of these items, which is set in the server properties.
After the right is set and the respective role is assigned, it is possible to check if the settings are correct by opening the respective pages in the WEB interface.
Enter one of the following options in the address bar. In the authorization window, enter the employee's name and password.
Request execution examples
XML interface test page
To check the XML interface using the HTTPs interface, go to https://ip:port/webgui/iservxmltest.htm (for example, https://127.0.0.1:13665/webgui/iservxmltest.htm), enter the user name and password, and the text of the XML request to be executed. Then click Execute. The result should be as in the figure below.
Wget command line utility
An example of a request executed using the wget utility:
wget.exe --secure-protocol=TLSv1 --no-check-certificate --header="Content-Type: text/xml" --http-user=9006 --http-password=9006 --post-file=requestData.xml https://127.0.0.1:20001/rk7api/v0/xmlinterface.xml |
Parameters:
1. User: --http-user=9006
2. Password: --http-password=9006
3. Request file: --post-file=requestData.xml
After such a request is executed, its result will be saved in the xmlinterface.xml file.