Skip to main content

API Templating

summary

After reading this, you can use the API to roll out templates.

Introduction​

In addition to the other ways of creating a CashBox mentioned in the previous chapters, fiskaltrust also provides a REST API for a fully automated solution to set up CashBoxes. This API takes a generic template, relevant CashBox parameters and variables and creates a new CashBox based on this information. Contrary to templates used in the shop, these templates do not need to be pre-configured, but the content is sent directly with the API request.

The response to a successful request will include the ID and access token of the newly created CashBox, which will allow for an immediate rollout of a launcher instance with these values.

Using the API​

Prerequisites​

You'll need at least the following three items to run a request successfully against the template API.

  • Your account ID
  • Your account's access token
  • The desired template

You can obtain the ID and the access token from your portal's company overview at [COMPANYNAME] / Overview (Overview). You'll find your account ID (account ID) and the access token (access token) for the authentication against the API at the bottom.

Additionally to the ID and access token, you will need the template encoded for a JSON string, as you will have to include it in the API request.

Sending a request​

The API is available at https://helipad.fiskaltrust.cloud/api/configuration and takes a POST request, along with the account ID and the account's access token (please note the distinction to a CashBox's access token) and the template in question as JSON string.

sandbox

As mentioned in the chapter Sandbox, there's also a -sandbox suffixed version available at https://helipad-sandbox.fiskaltrust.cloud/api/configuration.

The account ID and access token serve as authentication information and are passed as part of the request headers accountid and accesstoken. In addition to these two headers, the request requires the template as a JSON string in the request body.

A fundamental request example would be

POST /api/configuration HTTP/1.1
Host: helipad.fiskaltrust.cloud
Content-Length: 167
Content-Type: application/json
accountid: ACCOUNT_ID
accesstoken: ACCOUNT_ACCESS_TOKEN

"{\r\n    \"ftCashBoxId\": \"|[cashbox_id]|\",\r\n    \"ftSignaturCreationDevices\": [],\r\n    \"ftQueues\": [],\r\n    \"helpers\": [],\r\n    \"TimeStamp\": 0\r\n}"

This is a standard HTTP POST request and you can use any HTTP library (e.g., Jodd HTTP for Java-based applications) or HTTP client (e.g., curl or PowerShell's Invoke-WebRequest) of your choice to send the request.

curl

curl.exe -X POST -H "Content-Type: application/json" -H "accountid: ACCOUNT_ID" -H "accesstoken: ACCOUNT_ACCESS_TOKEN" -d 'ESCAPED_TEMPLATE' https://helipad.fiskaltrust.cloud/api/configuration

Invoke-WebRequest

$headers = @{ accountid = "ACCOUNT_ID"; accesstoken = "ACCOUNT_ACCESS_TOKEN" }
Invoke-WebRequest -Uri https://helipad.fiskaltrust.cloud/api/configuration -Method Post -Headers $headers -Body "ESCAPED_TEMPLATE" -ContentType "application/json"
caution

If using the shell, please pay attention that escaping is appropriately used on all applicable characters. If you are in doubt, read Shell escaping for more details.

Escaping the template​

Please note that the API does not expect a plain JSON object in the request body but rather a (properly escaped) JSON string. So read, for example, the following template:

{
    "ftCashBoxId": "|[cashbox_id]|",
    "ftSignaturCreationDevices": [],
    "ftQueues": [],
    "helpers": [],
    "TimeStamp": 0
}

should be encoded as follows

"{\r\n    \"ftCashBoxId\": \"|[cashbox_id]|\",\r\n    \"ftSignaturCreationDevices\": [],\r\n    \"ftQueues\": [],\r\n    \"helpers\": [],\r\n    \"TimeStamp\": 0\r\n}"

In short, a traditional JSON string with quotation marks escaped with a slash, new-lines with their respective escaped counterparts, as well as any other applicable characters.

tip

You can escape the template with a number of tools, such as e.g. freeformatter.com or codebeautify.org. If you are comfortable with the browser console (F12), you can also use JSON.stringify() to escape the template object. Please make sure quotation marks enclose the string.

Shell escaping​

If you run the request from the command line, please also pay attention to escape sequences required by your shell. For example, PowerShell requires ` as escape character for quotations marks and using Invoke-WebRequest for the template object {"ftCashBoxId": "|[cashbox_id]|"} would require the following parameter

-Body "`"{\`"ftCashBoxId\`": \`"|[cashbox_id]|\`"}`""

Customising parameters​

Similar to Custom variables, you can customize many of the parameters of the individual CashBox components by providing their values in the query string.

Queue parameters​

There are three main queue parameters, each using a zero-based index to indicate the queue of the template where you'd like to apply the value.

ParameterDescription
queue{0-n}_cashboxidentificationThe identifier of the CashBox.
queue{0-n}_countrycodeISO 3166-1 alpha-2 country code of the queue.
queue{0-n}_timeoutSpecifying a millisecond value for the timeout of the queue.

For example, to specify a timeout value of 10,000 milliseconds for the second queue in your template, you'd append queue1_timeout=10000 to the query string of your HTTP call.

Market-specfic parameters​

Queue parameters​

ParameterDescription
queue{0-n}_encryptionkeybase64The encryption key used for this queue, Base64-encoded

SCU parameters​

You can specify each parameter globally or per SCU (in parentheses).

ParameterDescription
CertificateBase64 (scu{0-n}_certificatebase64)The certificate used by this SCU, Base64-encoded
Mode (scu{0-n}_mode)The active mode of the SCU (normal, backup, or deactive)
SN (scu{0-n}_sn)The serial number of the certificate
ZDA (scu{0-n}_zda)The certificate authority which signed the certificate
caution

Global values will override SCU-specific ones.

Handling the response & provisioning of the CashBox​

If your response indicates a status code 200, the request properly went through, and a new CashBox should have been created. In this case, the response body will contain a JSON object (not an escaped JSON string) with the details of that new CashBox.

{
  "cashBoxId": "",
  "accessToken": "",
  "configuration": ""
}
FieldDescription
cashBoxIdThe ID of the created CashBox.
accessTokenThe access token of the created CashBox.
configurationThe configuration object of the new CashBox, as escaped JSON string and based on the provided template.

Here, in particular, cashBoxId and accessToken are interesting, as they allow you to provision the CashBox automatically. To do that, please deploy a vanilla Launcher instance on the destination system and set its CashBox ID and Access Token parameters to the values you received in the response.

Custom variables​

In addition to the readily available system variables, you can also use custom variables in your templates. These variables follow the same syntax as system variables (i.e., |[variable_name]|); you can use them throughout your template.

Their values are passed via the query string of the request to the template API, and each custom variable used in your template needs to have a corresponding value in the query string. So, for example, if you used the variable |[my_variable]|, you'd need to pass its value in the call to the API by adding my_variable to the query string.

https://helipad.fiskaltrust.cloud/api/configuration?my_variable=desired_value

The call above will substitute all occurrences of |[my_variable]| with desired_value.

overriding system variables

You can also use the query string to override the values of system variables. Any value passed in this way will have precedence over the default value.

Demo with Postman​

Postman is a popular HTTP client and is often used to run REST requests manually. You can use it to try out and fine-tune your requests to the template API.

To download Postman, please go to https://www.postman.com/downloads and select the appropriate package for your system. fiskaltrust also provides a Postman collection with pre-configured request settings, which you can import and use as a foundation to customize your API requests.


StepDescription
Import the demo collection into your Postman instance.
Create a duplicate entry of the Sandbox environment.
Open the newly created entry.
In the Params tab, specify the desired Sandbox outlet ID and CashBox description.
In the Headers tab, specify your Sandbox account ID and Access Token.
In the portal, fetch a demo template from Configuration / Template.
Escape the template.
In the Body tab, add the escaped template as JSON string.
Send the request using the Send button.
Check if the response indicated a successful request.
In the portal, verify if the CashBox was properly created under Configuration / CashBox.