Sitoo Tax Free SPI

The SPI Tax Free is for services that offer a tax refund at airports and similar places. The customer is paying the taxes at the store and get a tax free voucher. The voucher is printed in the Sitoo POS on behalf of a tax free service provider.

SPI (Service Provider Interface)

The SPI is the definition of the API required to use the service in Sitoo. Therefore, the external service needs to fully implement the API definition.

Each request from the POS to the server implementing the SPI has the following optional headers:

Tax free transactions

To create a tax free transaction the POS makes a call to POST /transactions. The returned object contains the property webpage_url with an url that the POS will open in a web view. The POS injects a callback function that should be invoked as sitooPosCallbackTaxfreeDone(result) to close the web view.

The callback is defined as:

result = {
  success: <bool>,
  transaction_id: <string>,
  print_data: <array<array:string>>
  error_code: <string:enum>,
  error_message: <string>
}

function sitooPosCallbackTaxfreeDone(result)

A successfully completed transaction will invoke the callback function with result.success set to true and the transaction_id with the ID of the created transaction. The POS will then refer to the returned receipt_type value from the previous call to POST /transactions and proceed with different flows based on the type. In case of receipt_type being

• print-data: The POS expects data to be present in result.print_data which is printed on the receipt printer.
• none: The POS will request data from the GET /transaction/{transaction_id}/printouts endpoint and print the returned Printouts on the receipt printer.

A non-successful transaction sets result.success to false and is expected to have a result.error_code with an optional result.error_message.

The result.error_code should be one of:

• cancelled
• not-eligble-amount
• other
• service-unavailble
• service-unauthorized

Order update on success

If the transaction was successful, the POS will update the order and add the following additional data fields:

Printouts

The result.print_data from the web view callback and the returned value from GET /transaction/{transaction_id}/printouts endpoint is an array of Printouts, where each Printout is a separate strip of paper printed on the receipt printer.

A Printout is defined as an array of strings, with optional tags for formatting text and the possibility to include images and render data as QR codes and barcodes. Each string in the array corresponds to a row and can include a tab control character (\t) to split the row in two columns.
Note: If more than one tab control character is present in a row, the rendering behavior is undefined.

Text can be formatted with tags (see available tags in the table below), which are applied to the whole row, e.g. {{Style:BOLD}} will make all text on the row rendered in bold. The Alignment tag is only applicable for single column rows, i.e rows without the tab control character. A row with two columns will always be rendered with the first column aligned with START (left) and the second column aligned with END (right).

The non-text tags Image, QR and Barcode must be on its own row and not combined with text or other tags. The Image tag expects a PNG image encoded as base64.

List of supported tags

Printout example

[
  [
    "{{Alignment:CENTER}}{{Style:BOLD}}TAX FREE",
    "",
    "Bracelet\t$123.00",
    "{{Style:BOLD}}Total\t$123.00",
    "",
    "{{QR:123456}}",
    ""
  ]
]

Authentication

Authentication of the calls are done using the HTTP basic authentication mechanism. Requests to the endpoint will add an Authorization header to the request. Example:

Authorization: Basic MTAwMjAtMTQwOmJ1TnhvT3gybzVrTTJKTWMzVmhCWDIwazRHaWs0cUtYeUtmZzMzMkE=

Public Server

The URL used for the service needs to have public access with a valid SSL certificate.

Errors

When a request is not successful an error object should be returned. It should consist of the request_id, an error_code and an error_data field. The error code is defined as one of the following strings

• field-missing
• field-unknown
• field-readonly
• field-type
• field-validation
• version-invalid
• condition-failed
• other

If the error_code value is one of the following field-missing, field-unknown, field-readonly, field-type, field-validation then error_data should contain the property field. The value should be the path to the invalid property in the request object.

Example error message:

{
  "error_code": "field-unknown",
  "error_data": {
    "field": "order.items[1].vaat_value",
    "message": "Unknown field 'order.items[1].vaat_value'"
  },
  "request_id": "cba36882-22cd-447e-94f4-04ecef411be1"
}