fiskaltrust POS API (Preview)
Download OpenAPI specification:Download
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:

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 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.
Typically, a full receipt flow when using all features (pay, sign and print) would look like this:
- Compose a
ReceiptRequest
based on the data entered into the POS software - Call the
/pay
endpoint and asynchronously wait for the result - If the payment was successful, call the
/sign
endpoint and asynchronously wait for the result - If the signing was successful, call the
/print
endpoint and asynchronously wait for the result
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
- Payload
{- "ftCashBoxID": "string",
- "ftQueueID": "string",
- "ftPosSystemId": "string",
- "cbTerminalID": "string",
- "cbReceiptReference": "string",
- "cbReceiptMoment": "2019-08-24T14:15:22Z",
- "cbChargeItems": [
- {
- "position": 0,
- "quantity": 0,
- "description": "string",
- "amount": 0,
- "vatRate": 0,
- "ftChargeItemCase": 0,
- "ftChargeItemCaseData": "string",
- "vatAmount": 0,
- "accountNumber": "string",
- "costCenter": "string",
- "productGroup": "string",
- "productNumber": "string",
- "productBarcode": "string",
- "unit": "string",
- "unitQuantity": 0,
- "unitPrice": 0,
- "moment": "2019-08-24T14:15:22Z"
}
], - "cbPayItems": [
- {
- "position": 0,
- "quantity": 0,
- "description": "string",
- "amount": 0,
- "ftPayItemCase": 0,
- "ftPayItemCaseData": "string",
- "accountNumber": "string",
- "costCenter": "string",
- "moneyGroup": "string",
- "moneyNumber": "string",
- "moment": "2019-08-24T14:15:22Z"
}
], - "ftReceiptCase": 0,
- "ftReceiptCaseData": "string",
- "cbReceiptAmount": 0,
- "cbUser": "string",
- "cbArea": "string",
- "cbCustomer": "string",
- "cbSettlement": "string",
- "cbPreviousReceiptReference": "string"
}
Response samples
- 200
{- "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
- Payload
{- "ftJournalType": 0,
- "from": 0,
- "to": 0,
- "maxChunkSize": 0
}
Response samples
- 200
{- "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
- Payload
{- "message": "string"
}
Response samples
- 200
{- "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
- Payload
{- "request": {
- "ftCashBoxID": "string",
- "ftQueueID": "string",
- "ftPosSystemId": "string",
- "cbTerminalID": "string",
- "cbReceiptReference": "string",
- "cbReceiptMoment": "2019-08-24T14:15:22Z",
- "cbChargeItems": [
- {
- "position": 0,
- "quantity": 0,
- "description": "string",
- "amount": 0,
- "vatRate": 0,
- "ftChargeItemCase": 0,
- "ftChargeItemCaseData": "string",
- "vatAmount": 0,
- "accountNumber": "string",
- "costCenter": "string",
- "productGroup": "string",
- "productNumber": "string",
- "productBarcode": "string",
- "unit": "string",
- "unitQuantity": 0,
- "unitPrice": 0,
- "moment": "2019-08-24T14:15:22Z"
}
], - "cbPayItems": [
- {
- "position": 0,
- "quantity": 0,
- "description": "string",
- "amount": 0,
- "ftPayItemCase": 0,
- "ftPayItemCaseData": "string",
- "accountNumber": "string",
- "costCenter": "string",
- "moneyGroup": "string",
- "moneyNumber": "string",
- "moment": "2019-08-24T14:15:22Z"
}
], - "ftReceiptCase": 0,
- "ftReceiptCaseData": "string",
- "cbReceiptAmount": 0,
- "cbUser": "string",
- "cbArea": "string",
- "cbCustomer": "string",
- "cbSettlement": "string",
- "cbPreviousReceiptReference": "string"
}, - "response": {
- "ftCashBoxID": "string",
- "ftQueueID": "string",
- "ftQueueItemID": "string",
- "ftQueueRow": 0,
- "cbTerminalID": "string",
- "cbReceiptReference": "string",
- "ftCashBoxIdentification": "string",
- "ftReceiptIdentification": "string",
- "ftReceiptMoment": "2019-08-24T14:15:22Z",
- "ftReceiptHeader": [
- "string"
], - "ftChargeItems": [
- {
- "position": 0,
- "quantity": 0,
- "description": "string",
- "amount": 0,
- "vatRate": 0,
- "ftChargeItemCase": 0,
- "ftChargeItemCaseData": "string",
- "vatAmount": 0,
- "accountNumber": "string",
- "costCenter": "string",
- "productGroup": "string",
- "productNumber": "string",
- "productBarcode": "string",
- "unit": "string",
- "unitQuantity": 0,
- "unitPrice": 0,
- "moment": "2019-08-24T14:15:22Z"
}
], - "ftChargeLines": [
- "string"
], - "ftPayItems": [
- {
- "position": 0,
- "quantity": 0,
- "description": "string",
- "amount": 0,
- "ftPayItemCase": 0,
- "ftPayItemCaseData": "string",
- "accountNumber": "string",
- "costCenter": "string",
- "moneyGroup": "string",
- "moneyNumber": "string",
- "moment": "2019-08-24T14:15:22Z"
}
], - "ftPayLines": [
- "string"
], - "ftSignatures": [
- {
- "ftSignatureFormat": 0,
- "ftSignatureType": 0,
- "caption": "string",
- "data": "string"
}
], - "ftReceiptFooter": [
- "string"
], - "ftState": 0,
- "ftStateData": "string"
}
}
Response samples
- 200
{- "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
- Payload
{- "ftCashBoxID": "string",
- "ftQueueID": "string",
- "ftPosSystemId": "string",
- "cbTerminalID": "string",
- "cbReceiptReference": "string",
- "cbReceiptMoment": "2019-08-24T14:15:22Z",
- "cbChargeItems": [
- {
- "position": 0,
- "quantity": 0,
- "description": "string",
- "amount": 0,
- "vatRate": 0,
- "ftChargeItemCase": 0,
- "ftChargeItemCaseData": "string",
- "vatAmount": 0,
- "accountNumber": "string",
- "costCenter": "string",
- "productGroup": "string",
- "productNumber": "string",
- "productBarcode": "string",
- "unit": "string",
- "unitQuantity": 0,
- "unitPrice": 0,
- "moment": "2019-08-24T14:15:22Z"
}
], - "cbPayItems": [
- {
- "position": 0,
- "quantity": 0,
- "description": "string",
- "amount": 0,
- "ftPayItemCase": 0,
- "ftPayItemCaseData": "string",
- "accountNumber": "string",
- "costCenter": "string",
- "moneyGroup": "string",
- "moneyNumber": "string",
- "moment": "2019-08-24T14:15:22Z"
}
], - "ftReceiptCase": 0,
- "ftReceiptCaseData": "string",
- "cbReceiptAmount": 0,
- "cbUser": "string",
- "cbArea": "string",
- "cbCustomer": "string",
- "cbSettlement": "string",
- "cbPreviousReceiptReference": "string"
}
Response samples
- 200
{- "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.
Request Body schema: application/json
type | string or null |
identifier | string <uuid> |
Responses
Request samples
- Payload
{- "type": "string",
- "identifier": "14d3030c-3b61-4070-b902-342f80e99364"
}