Skip to main content
API docs by Redocly

fiskaltrust POS API (Preview)

Download OpenAPI specification:Download

fiskaltrust: hello@fiskaltrust.eu License: This documentation and samples are released under the MIT license.

This API provides a variety of different functionalities for POS systems and is the central entry point to the fiskaltrust.Middleware. It can be used to fiscalize (or sign) receipts, execute payments via different payment providers, digitally print receipts, and to export data from the Middleware.

The POS API is a superset of the Middleware's "original" IPOS interface, and uses the same models for /sign, /journal and /echo. This means that existing implementations can very easily be reused by adjusting them to the asynchronous flow. The IPOS interface will continue to be fully supported by the Middleware.

As most operations (especially print and payment requests, but also sign operations in specific cases) may take an extended amount of time, this API is designed in a completely asynchronous way. After sending a request to one of the endpoints listed below, the API immediately returns a message identifier (i.e. an UID), which can then be used to query for the result via the /response endpoint. A general sample of this process flow is illustrated in the picture below:

process-flow

Availability

The production API can be reached at https://pos-api.fiskaltrust.cloud; as for all fiskaltrust services, the sandbox instance should be used for development and testing: https://pos-api-sandbox.fiskaltrust.cloud.

The exact same endpoints will also be added to the on-premise Launcher (natively in version 2.0, and via additional Helper packages for the versions below).

Authentication

Authentication is handled via the headers cashboxid and accesstoken, which are mandatory for each request. Those values can be obtained by creating a CashBox in the one of the country-specific fiskaltrust.Portals.

Operation flow

Typically, a full receipt flow when using all features (pay, sign and print) would look like this:

  1. Compose a ReceiptRequest based on the data entered into the POS software
  2. Call the /pay endpoint and asynchronously wait for the result
  3. If the payment was successful, call the /sign endpoint and asynchronously wait for the result
  4. If the signing was successful, call the /print endpoint and asynchronously wait for the result

POS API

Asynchronously signs a receipt, according to local regulations

This method can be used to sign different types of receipts according to local fiscalization regulations. After signing the receipt according to the fiscal law, this method asynchronously returns the data that need to be printed onto the receipt. The format of the receipt request is documented in the Middleware API docs, and the exact behavior of the method is determined by the cases sent within the properties (e.g. ftReceiptCase, ftChargeItemCase and ftPayItemCase.

header Parameters
cashboxid
required
string
accesstoken
required
string
Request Body schema: application/json
ftCashBoxID
string or null
ftQueueID
string or null
ftPosSystemId
string or null
cbTerminalID
string or null
cbReceiptReference
string or null
cbReceiptMoment
string <date-time>
Array of objects or null (ChargeItem)
Array of objects or null (PayItem)
ftReceiptCase
integer <int64>
ftReceiptCaseData
string or null
cbReceiptAmount
number or null <double>
cbUser
string or null
cbArea
string or null
cbCustomer
string or null
cbSettlement
string or null
cbPreviousReceiptReference
string or null

Responses

Request samples

Content type
application/json
{
  • "ftCashBoxID": "string",
  • "ftQueueID": "string",
  • "ftPosSystemId": "string",
  • "cbTerminalID": "string",
  • "cbReceiptReference": "string",
  • "cbReceiptMoment": "2019-08-24T14:15:22Z",
  • "cbChargeItems": [
    ],
  • "cbPayItems": [
    ],
  • "ftReceiptCase": 0,
  • "ftReceiptCaseData": "string",
  • "cbReceiptAmount": 0,
  • "cbUser": "string",
  • "cbArea": "string",
  • "cbCustomer": "string",
  • "cbSettlement": "string",
  • "cbPreviousReceiptReference": "string"
}

Response samples

Content type
application/json
{
  • "type": "string",
  • "identifier": "14d3030c-3b61-4070-b902-342f80e99364"
}

Executes an asynchronous data export

This method can be used to start data exports from the underlying Middleware, e.g. in CSV, XML, or different country-specific formats. The export format is determined by the ftJournalType property in the body (possible values are described in the Middleware API docs and its country-specific appendices.

header Parameters
cashboxid
required
string
accesstoken
required
string
Request Body schema: application/json
ftJournalType
integer <int64>
from
integer <int64>
to
integer <int64>
maxChunkSize
integer <int32>

Responses

Request samples

Content type
application/json
{
  • "ftJournalType": 0,
  • "from": 0,
  • "to": 0,
  • "maxChunkSize": 0
}

Response samples

Content type
application/json
{
  • "type": "string",
  • "identifier": "14d3030c-3b61-4070-b902-342f80e99364"
}

Asynchronously returns the input value, e.g. for communication tests

This method can be used to verify that the communication to the POS API and the underlying Middleware are working without any side effects.

header Parameters
cashboxid
required
string
accesstoken
required
string
Request Body schema: application/json
message
string or null

Responses

Request samples

Content type
application/json
{
  • "message": "string"
}

Response samples

Content type
application/json
{
  • "type": "string",
  • "identifier": "14d3030c-3b61-4070-b902-342f80e99364"
}

Asynchronously creates a digital receipt

This method can be used to "print" a digital receipt, based on the receipt-request and -response pair from signing a receipt via the sign endpoint. The asynchronously created response contains the link to the digital receipt.

For further information about the digital receipt, please refer to the Middleware API documentation

header Parameters
cashboxid
required
string
accesstoken
required
string
Request Body schema: application/json
object (ReceiptRequest)
object (ReceiptResponse)

Responses

Request samples

Content type
application/json
{
  • "request": {
    },
  • "response": {
    }
}

Response samples

Content type
application/json
{
  • "type": "string",
  • "identifier": "14d3030c-3b61-4070-b902-342f80e99364"
}

Asynchronously triggers a payment

This method can be used to trigger a digital payment via one of the payment providers supported by the Middleware (details coming soon). The request is processed asynchronously, as payment operations may take a while, depending on the provider.

Payment operations will be identified by the used `ftPayItemCase` (e.g. cash payments won't trigger any online payment operations); currently this method triggers on credit- and debit card cases.

The payment provider and the required credentials will be configurable in the Portal and connectable to the used Middleware instance soon.

header Parameters
cashboxid
required
string
accesstoken
required
string
Request Body schema: application/json
ftCashBoxID
string or null
ftQueueID
string or null
ftPosSystemId
string or null
cbTerminalID
string or null
cbReceiptReference
string or null
cbReceiptMoment
string <date-time>
Array of objects or null (ChargeItem)
Array of objects or null (PayItem)
ftReceiptCase
integer <int64>
ftReceiptCaseData
string or null
cbReceiptAmount
number or null <double>
cbUser
string or null
cbArea
string or null
cbCustomer
string or null
cbSettlement
string or null
cbPreviousReceiptReference
string or null

Responses

Request samples

Content type
application/json
{
  • "ftCashBoxID": "string",
  • "ftQueueID": "string",
  • "ftPosSystemId": "string",
  • "cbTerminalID": "string",
  • "cbReceiptReference": "string",
  • "cbReceiptMoment": "2019-08-24T14:15:22Z",
  • "cbChargeItems": [
    ],
  • "cbPayItems": [
    ],
  • "ftReceiptCase": 0,
  • "ftReceiptCaseData": "string",
  • "cbReceiptAmount": 0,
  • "cbUser": "string",
  • "cbArea": "string",
  • "cbCustomer": "string",
  • "cbSettlement": "string",
  • "cbPreviousReceiptReference": "string"
}

Response samples

Content type
application/json
{
  • "type": "string",
  • "identifier": "14d3030c-3b61-4070-b902-342f80e99364"
}

Returns the response of a previous async call

This method is used to obtain the result of a previously executed asynchronous operation. Callers should pass the result object from this referenced operation into the body, and the method will either return the requested response, or HTTP 204 in case the operation has not finished yet.

header Parameters
cashboxid
required
string
accesstoken
required
string
Request Body schema: application/json
type
string or null
identifier
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "type": "string",
  • "identifier": "14d3030c-3b61-4070-b902-342f80e99364"
}