HKS

Disclaimer

This document is only collection of author’s notes, experiences and point of views. It is not, in any meaning, either complete description of the topic nor official RTB documentation. It may be inaccurate, incomplete, obsolete, misleading or completely wrong. It may even cause loss of data or damage system integrity. It may not comply with company codex, values, presentation style or economic interests or may reveal company secrets.

As such, it is absolutely prohibited to distribute this document outside of RTB & Co. GmbH. Such an action may result into legal acts against both the sender and the company. It is only intended, after review of technical and presentational correctness and accuracy, to be used as an information source for official documentation.

Always contact documentation department for information about current presentation style and allowed formats before creating customer’s documentation.

1. What is HKS

HKS offers an integrated, convenient and reliable system that easily adapts to the customer’s requirements. HKS solutions guarantee smooth workflows, especially when it comes to high visitor frequencies. This is the ideal solution for operators of highly frequented facilities such as car parks, baths, thermal spas and other leisure facilities. Cities and councils benefit from the combined all-round solutions.

HKS' primary claim is to guarantee an efficient, fast and stable guest management. HKS solutions optimise operational efficiency and meet customer requirements. Due to its modular structure the system is easily adaptable. The customised system offers maximum comfort, success and satisfaction.

See more on home page.

2. Requirement

Customer Landesgartenschau Bad Lippspringe requires selling products got from HKS’s API. There are two use cases:

Figure 1. Global use cases

There are two possible use cases. 1. User buys access QR code on PDM (Buy QR code). 2. User spends QR code on gate which let him pass to the garden (Buy QR code).

Only the first use case is relevant to this specification. The second use case is handled by HKS.

Selling QR code is composed of multiple steps. They are shown on the sequence diagram below.

Figure 2. Process of selling QR code

3. Implementation

3.1. List products

To list available products, PDM control will proxy MRQ from PDM to HKS. MRQ number is 38 and requires no parameters.

Response is a JSON list of products with their prices. List of products it self is wrapped by catalog attribute. Currently there is nothing other there but it leave possibility of extension to the future.

Example of product list

"CatalogArticles": [
    {
        "Number": "1.1.32.1272.3.0",
        "UnitPrice": 9.5,
        "ShortText": "Tageskarte Erwachsene",
        "Description": "Tageskarte Erwachsene",
        "VATSplitting": "1=100",
        "VATRates": [0, 7, 19, 0, 0],
    },
    {
        "Number": "1.1.32.1272.2.0",
        "UnitPrice": 7.5,
        "ShortText": "Tageskarte ermäßigt",
        "Description": "Tageskarte ermäßigt",
        "VATSplitting": "1=100",
        "VATRates": [0, 7, 19, 0, 0],
    }
]

Fields in response have the following meaning.

Number: Article number in HKS system. Use this number for sale requests
UnitPrice: List price.
ShortText: Short variant of description (max 30 characters).
Description: Full item description.
VATSplitting: How to calculate VAT. Possible Values:
- "0=100" (vat code 0 on 100% of the turnover)
- "1=100" (vat code 1 on 100% of the turnover)
- "2=100" (vat code 2 on 100% of the turnover)
VATRates: Array of applicable VATs categories. Value is in percent points.

3.2. Post payment

Post payment process is illustrated by the following diagram. Blue actions are performed solely by PDM. Orange ones with cooperation with PDM.control. Calls to PDM.controls return receipt to be printed.

Figure 3. Post payment process

3.2.1. Response wrapper

Content of response body from HKS depends on HTTP status code. We do not have possibility to transfer such and information outside real-time response. Therefore, it is by transferred in extra mnemonic httpStatus. Response itself is transferred in mnemonic body.

Example of real-time response

MNR{httpStatus:200,body:{...}};

Code examples in next sections shows only content of body mnemonic. If value of HTTP status is relevant, then it is mentioned only in text.

3.3. Book shopping cart

This function is realized by request number 39 and it is used to indicate to HKS that goods from shopping card has been already sold to a customer. A shopping cart is a collection of items which a user selected from a product list and wants to buy. Each item can be bought multiple times. See example request is shown below.

Example of booking shopping cart

{
   "ItemsToSale":[
      {
        "ArticleId":"1.1.32.1272.3.0",
        "Amount":1,
        "HardwareSerial": "HCm2o!1C55ft&^189gJ9",
        "Id": "1F45972B-99A0-44D1-A291-E78E8986FA04"
      },
      {
        "ArticleId":"1.1.32.1272.2.0",
        "Amount":2,
        "Id": "3FDFE479-55A0-459D-85BA-58C634057A4B"
      }
  ],
  "PaymentInfo":{
    "PaymentType":36,
    "BrandName":"Visa"
  }
}

Meaning of fields if following:

ItemsToSale
- ArticleId - article number got from list of products.
- Amount - number of pieces to sell.
- HardwareSerial - (optional) content of QR code (max 30 characters). It may be left empty. In such a case, HKS will generate the number from sequence.
- Id - (optional) Identification may be assigned to an item to be later able to identify it in response or receipt. It must be a unique GUID for every item ever sold.
PaymentInfo - Information about payment.
- PaymentType - Possible payment methods:
  - pay on a chip / medium (e.g. DayGuest, Value Card). PaymentType = -1 and give MediumNumber or HardwareSerial
  - Pay with Credit Card (e.g. web shop). PaymentType = 36 and give BrandName
  - Pay on customer / bill. PaymentType = 1 and Specify Contact or MediumNumber or HardwareSerial assigned to a customer in HKS system.

for payment with credit card (e.g. web-shop) must be 36 ** BrandName - PaymentType = 36 means type of Payment is determined by the given BrandName. It is only valid with specification of BrandName. The BrandNames must be configured in the HKS System.

Own value for QR code, field HardwareSerial can be used only if Amount is equal to 1. If you want to use own value for QR code, repeat object for each article multiple times with Amount = 1. If you want HKS to generate QR code for you, let field null. In this case, amount can be used with value more than 1.

3.3.1. Success

Success in indicated by httpStatus 200.

Example of successful booking

{
  "ReceiptNumber": "81010001-2022-19-12",
  "SaleItemResponses": [
      {
          "Id": "1F45972B-99A0-44D1-A291-E78E8986FA04",
          "ResultCode": 0,
          "ErrorMessage": null,
          "MediumNumber": 199448971,
          "HardwareSerial": "HCm2o!1C55ft&^189gJ9"
      },
      {
          "Id": "3FDFE479-55A0-459D-85BA-58C634057A4B",
          "ResultCode": 0,
          "ErrorMessage": null,
          "MediumNumber": 199448972,
          "HardwareSerial": "664880890100694814"
      },
      {
          "Id": "3FDFE479-55A0-459D-85BA-58C634057A4B",
          "ResultCode": 0,
          "ErrorMessage": null,
          "MediumNumber": 199448973,
          "HardwareSerial": "665202480100694815"
      }
  ]
}

Meaning of fields if following:

ReceiptNumber - unique number assigned to receipt by HKS. Receipt can be later requested via API GET /pos/receipt/receiptNumber.
SaleItemResponses - array of sale reposes for individual items.
- Id - item ID from request. May be null if not provided in request.
- ResultCode - undocumented.
- ErrorMessage - undocumented.
- MediumNumber - ID of medium used for this item. Additional information about it can be requested via API GET/mediumdata/{mediumNumber}
- HardwareSerial - value to be printed in QR code. If provided in request, it is just repeated here.

3.3.2. Error

Error message is indicated by httpStatus <> 200

Example of error during item booking

{
  "ErrorCode":"InternalServerError",
  "Message":"Die Verbuchung von Job \"Hks.Base.Jobs.Hardware.Sale.JobSaleItems+JobPayWrapper\" wurde mit folgendem Fehler abgebrochen: Fehler bei der Zahlung",
  "Errors":[],
  "Meta":null
}

3.4. Cancel

If PDM wants to cancel already booked shopping cart, it can use receipt number obtained in response to call cancel operation. Cancel operation is mapped to real-time request number 40. Example request is shown bellow

Example of cancelling a receipt

{
  "ReceiptNumber": "81010001-2022-19-27",
  "CancelDate": "2018-08-29T11:49:14.558Z"
}

Field meaning:

ReceiptNumber - the number of receipt obtained by booking process.
CancelDate - time stamp of cancellation. It may be omitted which means now.

Response is returned in response wrapper same way as in other requests.

3.4.1. Success

Status is indicated by httpStatus = 200. In case of success is returned an information about canceled articles.

Example of booking shopping cart

{
    "ReceiptNumber": "81010001-2022-19-30",
    "CancelMode": 0,
    "CanceledBookings": [
        {
            "ArticleNumber": "01.01.032.1272.03.00",
            "ShortText": "Tageskarte Erwachsene",
            "Amount": 1,
            "OriginalAmount": 1,
            "Price": 9.5
        },
        {
            "ArticleNumber": "01.01.032.1272.02.00",
            "ShortText": "Tageskarte ermäßigt",
            "Amount": 1,
            "OriginalAmount": 1,
            "Price": 7.5
        },
        {
            "ArticleNumber": "01.01.032.1272.02.00",
            "ShortText": "Tageskarte ermäßigt",
            "Amount": 1,
            "OriginalAmount": 1,
            "Price": 7.5
        }
    ],
    "ResponseStatus": null
}

3.4.2. Error

Error is indicated by httpStatus <> 200. .Example of booking shopping cart

{
  "errorCode": "NotFound",
  "message": "Receipt not found",
  "errors": [],
  "meta": null
}