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:
Each type of interface supports a different set of commands.
The XMLinterface enables the following:
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.
They are usually used for the following:
They are usually used for the following:
There are two options for licensing the XML interface:
There are two ways to exchange data with the XML interface:
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:
If you need to create a separate privilege and role with HTTPS access right, click below.
|
Requests to the cash server should be sent to the following URL:
https://*IP:HTTPDataPort*/rk7api/v0/xmlinterface.xml |
You need to specify your own IP:HTTPDataPort.
To access the interface, you need to 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 should be performed in UTF-8 encoding.
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:
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/
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.
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;
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.
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.
