Introduction

The following versions of r_keeper are required to use the subscription based XML interface:

  • 7.6.2.286+
  • 7.6.4.347+
  • 7.6.5.40+
  1. To work with the XML interface and execute the SaveOrder, PayOrder, MakeRetunGoods commands, you must additionally transfer information about the LicenseInfo license
  2. The license is entered and generated on the licensing server (hereinafter referred to as the LS), while the local integration database must store in encrypted form the credentials necessary to make requests to the SL: token, active license id, sequence number of the request seqNumber
  3. Integration requires one of the following licenses:
Products with XML-SaaSProductGUID
R-Keeper 7 XML interface for App 12655cee55-7bcd-4826-b6e0-a8ccf2017ef3
R-Keeper 7 XML interface for App 14458d8b1-0019-4025-8c7a-60a83ad64b66

Authorization

Preliminary settings:

  1. Enter the LS with the dealer-manager role's credentials and create a new user with limited rights
  2. Give this new user access (rights) to the card of the object on which it is planned to use the XML interface.


To work with requests for subscription based XML interfaces, you need the following data:

  • userName — email used as a login to enter the l.ucs.ru licensing system for the created user
  • password — password to enter the l.ucs.ru licensing system for the created user
  • token — a unique identifier that is given to the developer company for free and is the same for all its integrations.

Credentials, i.e. the userName and password are provided by the dealer of the object on which you plan to use the XML interface. 

To receive a token, you need to send an email with a request to integrations@rkeeper.ru. Use the email to which the account and token will be registered.
As mentioned above, a token is given to a developer company or similar person to identify the developer when making requests. The issued token must be used for all integrations of the developer company, i.e. it is not necessary to request a new token for each new object or integration.

Attention!

The token is issued for a limited time, usually for 1 year, and can be renewed by the owner of the token an unlimited number of times upon request to integrations@rkeeper.ru. At the moment, automatic renewal of tokens is not performed, so the developer should monitor on their own when the token expires and renew it in time.

Example:
The company is developing its own self-service kiosk that integrates with r_keeper 7 and uses any test or live object with subscription based XML interface licenses for this. Subsequently, it is planned to sell this integration to all interested clients.
To do this, the company needs:

  1. To request a token from UCS, which will be used for all connected objects
  2. To address the dealer servicing the integration object or test object:
    • To purchase and generate a subscription license for the XML interface for this object in the licensing system
    • To provide the developer company with an account in the licensing system with access to the integration object.

The usr parameter must be passed in the authorization request header, the rule for its formation is:

usr : Base64(userName + ";" + lowercase(md5(userName+password)) + ";" + lowercase(md5(token)))

License ID Request

The GetLicenseIdByAnchor request is made to get the license ID to the licensing system API.

GetLicenseIdByAnchor?anchor=6:<productGUID>#<restCode>/17

Where:

  • productGUID — the GUID of the product
  • restCode — the restaurant code

An example of filling in the anchor for the R-Keeper 7 XML interface for App 12 product for object 199999993:

6:655cee55-7bcd-4826-b6e0-a8ccf2017ef3:199999993/17

Important!

The characters ": #" in the string must be escaped (: - %3A # - %23)

The request will look like:

https://l.ucs.ru/ls5api/api/License/GetLicenseIdByAnchor?anchor=6%3A655cee55-7bcd-4826-b6e0-a8ccf2017ef3%23199999993/17

For a positive response, an application for the specified software must be confirmed at the facility and an active license must be generated.

In response, we will receive information about the active license:

{"id":"fe4e4c5a-3037-4f0c-8216-7b98be6d87bb","expirationDate":"2020-03-26T00:00:00","qty":1.0}

The received ID must be saved in the database of the product to be integrated and transmitted when filling in the LicenseInfo parameter in the licenseToken attribute.

The ID must be updated each time the integration starts and during periodic license checks, for example, every 30-90 minutes, or if the request fails before retrying.

Filling in LicenseInfo

When sending the SaveOrder, PayOrder, MakeRetunGoods commands, the integrated product checks for the availability of license information — license ID — in the database. If the ID is found, an additional LicenseInfo element is added to the XML request.

<LicenseInfo anchor="6:655cee55-7bcd-4826-b6e0-a8ccf2017ef3#199999993/17" licenseToken="fe4e4c5a-3037-4f0c-8216-7b98be6d87bb">
<LicenseInstance guid="instance_guid" seqNumber="0"/>
</LicenseInfo>
  • anchor — the license anchor
  • licenseToken — the license ID
  • guid — the unique GUID of the application instance. At the first start of the integration, it must be generated automatically, then stored locally and transmitted in each request
  • seqNumber — the sequence number of the request. The first time the new guid is called, it must be 0, incremented with each request. The integration must implement the storage of the current seqNumber in RAM or a local database. You can use the GetXMLLicenseInstanceSeqNumber command to get an up-to-date value at application startup, but this command should not be run too often.

Query schema XSD: XML-Schemes.zip
Current schemes can be viewed on FTP: ftp://ftp.ucs.ru/rk7/ForDealers/XMLInterface/XML-Schemes

  • No labels