You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

Introduction

The XML interface is the most convenient way of getting information about the r_keeper 7 system and saving data in the r_keeper 7 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 XMLinterface 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:

Such software products as Mobile Waiter, sellf-service Kiosk, Kiosk PRO, etc. operate based on the XML interface.

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

There are two options for licensing the XML interface:

  • LifeTime — RKeeper 7 Write XML Order — a license is purchased once for a specific object and does not imply any restrictions on requests within this object.
    After purchasing a license, you need to generate a license key and add it to the restaurant properties in the manager station. Read more in the article Saving Orders XML Interface
  • Subscription based — a license for the integration of external applications for 1 or 12 months. SaveOrder, PayOrder, MakeRetunGoods requests must be signed and verified by the licensing system. For more information, see Using the XML Interface by Subscription.

Methods of Data Exchange with XML Interface

There are two ways to exchange data with the XML interface:

  • Using the HTTPS protocol — available from r_keeper version 7.05.03 and later
  • Using rk7xml.dll — in this case, you need to add an XML interface to the cash server, data exchange will be performed through the port specified in the server properties. To test the process, you may use the special utility XMLTEST.exe. Read more about the settings below in the Setting up the XML interface using rk7xml.dll section.

Configuring XML Requests Work via HTTPS

Using HTTPS for XML requests is possible only for r_keeper version 7.05.03 and later.

In the manager station, you need to configure access to the cash server via HTTPS. To do this, you need to create a worker with the appropriate privilege. Current versions of r_keeper have a pre-installed HTTPS Access right created specifically for this purpose, and we recommend using it.

If you already have a role and an employee with the HTTPS access privilege, you just need to give access to the cash server. To do this:

  1. Go to Service > Stations and Devices
  2. Select a required restaurant and go to the cash server
  3. In the server properties:
    • Specify a free port in the HTTP Data Port field. Optionally, enable the Use Free Listen Port setting to make the server choose a different port when the port specified in the HTTP Data Port property is busy.
    • In the HTTP Restrictions section, select the HTTP_Access privilege in all fields
  4. Save Changes
  5. Reboot the cash server.

If you want to create a separate privilege and role with HTTPS access right, click below.

Creating a Privilege and a Role
Go to Tools > Manager Station > Object Privileges.
Add a new privilege, such as HTTP_port.

Go to Settings > OLAP Reports > Report Servers
Select the required directory server
In the server properties:
In the HTTP Server section, find the HTTP Data Port field and enter a free port.
Enable the Use Free Listen Port setting to have the program select a different port when the port specified in the HTTP Data Port property is busy.
To access the web interface of this server, you can use:
The port specified in the properties of the directory server in the manager station is HTTP Data Port
The port specified in rk7srv.ini in the [TSPSOC] section, the port parameter.
In the HTTP Restrictions section, put the created privilege in all fields
In the Restrictions section, include the created privilege in the object privilege

Save Changes
Restart the server
In the manager station, go to Tools > Stations and Devices
Select a restaurant and go to the cash server
In the server properties:
In the HTTP Server section, find the HTTP Data Port field and enter a free port.
Enable the Use Free Listen Port setting to have the program select a different port when the port specified in the HTTP Data Port property is busy.
To access the web interface of this server, you can use:
The port specified in the properties of the directory server in the manager station is HTTP Data Port
The port specified in rk7srv.ini in the [TSPSOC] section, the port parameter.
In the HTTP Restrictions section, put the created privilege in all fields

Create a role with rights to the created privilege


When authorizing HTTPS requests, only the roles of the current restaurant and the central office are used.

For the created role, add an employee, set a password for him.
The name and password of this employee will be used for authorization on the server via HTTPS.

r_keeper 7 and Menuboard Pro communication connection example

Requests to the cash server should be sent to the following URL:

https://*IP:HTTPDataPort*/rk7api/v0/xmlinterface.xml
IP:HTTPDataPort you need to specify your own.

To access the interface, you must send a login and password — the name and password of an employee of the Basic Authorization type when sending each request.
Data exchange with the cash server must be in UTF-8 encoding.

Checking the XML interface through the built-in utility

To validate an XML interface over an HTTPS interface:

Visit https://ip:port/webgui/iserxmltest.htm. For example, https://127.0.0.1:13665/webgui/iservxmltest.htm
Enter the details of the created employee: username and password
Enter the text of the XML request to execute
Click the Execute button
The result should be like the picture below:

Authentication and query execution

For authentication and authorization, the name and password of the employee from r_keeper 7 are used.

The WEB interface at the time of this writing has limitations:

New WEB interface: https://ip:port/webgui/, for example: https://ip:port/webgui/index.htm
API version 0 - XML ​​interface and r_keeper 7 internal procedures: https://ip:port/rk7api/v0, for example: https://ip:port/rk7api/v0/xmlinterface.xml
API version 1 - new functions for interacting with r_keeper 7: https://ip:port/rk7api/v1, for example: https://127.0.0.1:13665/rk7api/v1/serverstatus.xml
After specifying the right and assigning it to the corresponding role, you can check the correctness of the settings by opening the corresponding pages in the WEB interface.

Enter one of the options in the address bar, an authorization window will appear - enter the name of the employee and password. Please note that you need to enter your IP and port.

The web interface is available at: https://ip:port/webgui/

https://ip:port/rk7api/v1

https://ip:port/rk7api/v0

Making a request via wget

An example of making a request 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
Request parameters:

User: --http-user=9006
Password: --http-password=9006
Request file: --post-file=requestData.xml
After executing such a request, its result will be saved to the xmlinterface.xml file.

Setting up the XML interface using rk7xml.dll

Attention!

This way of interacting with the XML interface is not recommended due to lack of authorization.
Instructions for setting up the XML interface using rk7xml.dll
The XML interface works through the iTCPXML.dll driver. When working with the XML interface via rk7xml.dll, in addition to the settings described above, you must manually add the interface to the POS server:

Go to Tools > Stations and Devices
Select a restaurant and go to the cash server
On the Devices tab, add the XML Interface For Windows driver
Write the port in the Port parameter

Bind the added interface to a logical interface in the Tools > Interfaces directory.
By default, the system will already have a pre-installed XML interface with code 104. For each external application, you can make a copy of this interface and associate it with the driver on the POS server.

After binding the interface, restart the cash server. Check that the interface is loaded in the cash server properties
Start the cash server with the desktop parameter and open its interface by double-clicking on its tray icon.
The loaded interface should be visible on the Interfaces tab

Functions are called via RK7XML.dll, an interface module:
CallRK7XMLRPC Function
Options:

AddressName - address:port

Request - XML ​​request

RequestSize - XML ​​request length

ResultFile - the name of the file where the result is written

ErrorBuf - the place where connection errors are written

ErrorBufSize — ErrorBuf size

CallRK7XMLRPCToStream function - similar to the function above, but its result is written to the IStream stream
Options:

AddressName - address:port
Request - XML ​​request
RequestSize - XML ​​request size
ResultStream - IStream - the stream where the result is transferred
ErrorBuf - the place where connection errors are written
ErrorBufSize — ErrorBuf size
The SetUseTempFileLimit function sets the file size limit if the result return time exceeds the threshold. Default = 1000000ms
GetDLLVersion function - returns the DLL version
SetCryptKey function - sets the encryption key. It can be different for different cash servers, it is specified in the properties of the XML interface.
The current protocol version 2 assumes control over the execution of commands by the server. In the previous version, it was impossible to know if the last request completed if there was a disconnect after the request started processing.
Now there are new functions GetLastXMLResult and GetLastXMLResultToStream for this. If the response could not be sent after the request was completed, it is stored on the server until a special request is made when calling these functions or until the next request. If the response was successfully sent, it is not stored on the server. In any case, you can always find out the number of the last executed request for a particular ConnectName.

ConnectName - arbitrary Null-terminated string, connection identifier
RequestNum - sequential number of the request, maintained for each connection identifier separately. You must pass 0, otherwise the passed request number will be used.

function CallRK7XMLRPC2(AddressName: PChar; ConnectName:PChar;
Request: PChar; RequestSize: integer;
var RequestNum: DWord; //round trip. If 0, then generated by the server.
ResultFile: PChar;
ErrorBuf: PChar; ErrorBufSize: integer):BOOL;stdcall;
function CallRK7XMLRPCToStream2(AddressName: PChar; ConnectName,
Request: PChar; RequestSize: integer;
var RequestNum: DWord; //round trip. If 0, then generated by the server.
ResultStream: IStream;
ErrorBuf: PChar; ErrorBufSize: integer):BOOL;stdcall;
function GetLastXMLResult(AddressName: PChar; ConnectName:PChar;
out RequestNum: DWord; //always returns the number of the last executed request
ResultFile: PChar; //result is filled if there was a result data transmission error, after successful transmission it is cleared
ErrorBuf: PChar; ErrorBufSize: integer):BOOL;stdcall;
function GetLastXMLResultToStream(AddressName: PChar; ConnectName: PChar;
out RequestNum: DWord; //always returns the number of the last executed request
ResultStream: IStream; //result is filled if there was a result data transmission error, after successful transmission it is cleared
ErrorBuf: PChar; ErrorBufSize: integer):BOOL;stdcall;

Validating XML Requests with TESTXML.exe

To check the request when using rk7xml.dll, use the XMLTEST.exe utility, which can be downloaded from the link or from the FTP server at: ftp://FTP.ucs.ru/rk7/ForDealers/XMLInterface/.

Launch example
Please note that when run without parameters, the utility displays usage information:

xmltest.exe 127.0.0.1:1122 xmlquery.xml response.xml /pass:password
Description parameter

ov:

127.0.0.1:1122 - IP address and port to which the XML interface is configured in r_keeper 7

xmlquery.xml - file name with XML request

response.xml is the name of the file where the response should be written

/pass:password - password set in the XML interface in r_keeper 7

After execution, the utility will save the response from the r_keeper 7 XML interface to the response.xml file. To check the functionality and correctness of the settings, you can use the following query, which should be saved to the xmlquery.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<RK7Query>
<RK7CMD CMD="GetSystemInfo"/>
</RK7Query>
For convenience, there is a utility with a graphical interface TestXML.zip.

Request logging

Enable request logging when using HTTPS
Go to Tools > Stations and Devices
Select a restaurant and go to the cash server
In the POS server properties, in the HTTP Server section, specify the HTTP Log path and check the Log HTTP query and response checkbox:

Enabling request logging when using RK7XML.dll
Go to Tools > Stations and Devices
Select a restaurant and go to the cash server
On the Devices tab, select one of the XML Interface For Windows drivers
Expand the Options section and fill in the OutputDir parameter

Be sure to restart the cash server after the changes have been made.

Requests will be paired - INxxxxx.XML and OUTxxxxx.XML.

Additionally, you can enable the NoLogginQueries parameter - it is responsible for disabling logging of the queries specified in the parameter. Specify the required requests in the field.



  • No labels