Zum Hauptinhalt springen
API docs by Redocly

fiskaltrust PosSystem API (2.0)

Download OpenAPI specification:Download

fiskaltrust: hello@fiskaltrust.eu License: This documentation and samples are released under the EUPL 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 (e.g. via the Receipt Bundle), and to export data from the Middleware.

API design principles

While the POSSystem API was designed to be easily usable via HTTP calls and JSON the call patterns follow a processual principle. We believe that by giving POS Systems a way to handle core processes in a stateful way as if they are a statemachine, that we can always ensure that the processes run as frictionless as possible. Each call that is handled by the POS System API is safe to be replayed and idempotent.

Authentication

The POSSystem API can only be used with the access data of a CashBox. These credentials can be found on the fiskaltrust.Portal in the CashBox Configuration page.You will need both CashBoxId and AccessToken to use this API.

Versioning

This API uses semantic versioning, meaning only major version changes contain breaking changes. Non-breaking changes (like returning additional data without changing the original model) will not increase the major version.

  • The latest version is used if no version is specified (like in the samples in this collection).
  • Users can specify versions by explicitly stating it in the URL once more versions are released.

Headers:

  • x-operation-id: The operation id is meant to be a idempotency key that let's the caller of the API endpoints safely retry calls. In case of timeouts, network interruptions this gives the ability to safely retry the process. While the request on the server side is still in progress calling the endpoint again with the same operation id does return a 422 Unprocessable Content. As soon as the request is finished whatever the initial request has finished with will be returned to the caller whenever the endpoint is called with the same body and the same operation-id.

    e.g. Calling /sign with x-operation-id ea4279ee-8684-412f-b8eb-32b5dea52811. The operation fails with a timeout. The caller handles the exception by performing the exact same operation again. The backend notices that this operation-id has been used in another transaction already and checks the state. If the state is finished it returnes the original response body

SynchronAPI

synchronous call pattern

caller / watcher description

successfull

timeout / retry

failed

Executes a blocking echo call end-to-end

This method can be used to perform a basic health and communcation check. It is also used for reseting the Middleware Instance (echo(null)

Authorizations:
(CashBoxIdCashBoxAccessToken)
header Parameters
x-operation-id
required
any (x-operation-id)

operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.

x-operation-lifetime
any (x-operation-lifetime)

operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.

x-operation-callback-state
any (x-operation-callback-state)

single state callback setting for current operation, executed each time when a status change occures

x-terminal-id
any (x-terminal-id)

identifies the terminal #TODO

x-possystem-id
any (x-possystem-id)

identifies the calling possystem #TODO

Request Body schema: application/json
object

Responses

Callbacks

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Callback payload samples

Callback
POST: OperationCallbackStateUrl
Content type
application/json
{
  • "OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
  • "QueueID": "1de0bf44-f9a4-4fc2-8140-0edabd852b0a",
  • "State": "done",
  • "StateMessage": "string",
  • "StateData": "string"
}

execute a sign call end-to-end

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 synchronously 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.

Authorizations:
(CashBoxIdCashBoxAccessToken)
header Parameters
x-operation-id
required
any (x-operation-id)

operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.

x-operation-lifetime
any (x-operation-lifetime)

operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.

x-operation-callback-state
any (x-operation-callback-state)

single state callback setting for current operation, executed each time when a status change occures

x-terminal-id
any (x-terminal-id)

identifies the terminal #TODO

x-possystem-id
any (x-possystem-id)

identifies the calling possystem #TODO

Request Body schema: application/json
cbTerminalID
string <= 1023 characters
Default: "undefined"

The unique identification of the input-station/terminal within a cash-register/pos-system identified by ftCashBoxID.

cbReceiptReference
required
string <= 1023 characters
Default: "undefined"

Reference number send by the cash register. This value must be a unique string/receipt number related to the calling cash register. This string/receipt number is a unique primary key of the dataset of the cash register.

cbReceiptMoment
required
string <date-time>

moment at which the receipt was create by the cash register, must be provided in UTC.

required
Array of objects (ChargeItem)

list of line items related to services and products

required
Array of objects (PayItem)

list of line items related to payments

ftCashBoxID
string <uuid>
Default: "00000000-0000-0000-0000-000000000000"

identification of the cash register

ftPosSystemID
string <uuid>
Default: "00000000-0000-0000-0000-000000000000"

identification of the used software of the cash register

ftReceiptCase
integer <uint64>
Default: 0

Type of business according to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO! this is relevant for fiskaltrust middleware processing and is a country specific mapping. as fallback when not specified, a cash register business case at the point-of-sale is used.

(string or null) or object

optional gives additional details for defined type of business related to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO!

ftQueueID
string or null <uuid>

optional routing instruction to identify a specific queue behind a load balancer or in other usecases

cbPreviousReceiptReference
string or null <= 1023 characters

optional Reference cbReceiptReference of the previous receipt. Used to connect multiple requests for a single Business Case.

(integer or null) or (number or null)
Default: null

optional total receipt amount, including value added taxes (=gross receipt amount) given to avoid calculation and rounding differences. systems which are using net amounts as central calculation should alsways use this property. if not provided, the sum of Amount in all provided ftChargeItems is used as total receipt amount. uses DecimalPresissionMultiplier as discriminator between int64 and double

(string or null) or object
Default: null

optional Identification of the user, who creates the receipt.

(string or null) or object
Default: null

optional Identification of the area/section/field, in which the receipt is created. e.g. Table number of a restaurant business; a department of a commercial establishment; the vehicle of a taxi company

(string or null) or object
Default: null

optional Identification of the consumer, for whom the receipt is created. e.g. Email address, phone number, personal tax number

(string or null) or object
Default: null

optional Settlement identification where this receipt will be added. e.g. shift number or day of operation

Currency
string (CurrencyEnum)
Default: "EUR"
Enum: "EUR" "CHF" "CZK" "HUF" "BAM" "DKK" "RON" "NOK" "PLN" "RSD" "SEK" "UAH" "USD" "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYN" "BZD" "CAD" "CDF" "CHE" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUP" "CVE" "DJF" "DOP" "DZD" "EGP" "ERN" "ETB" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HTG" "IDR" "ILS" "INR" "IQD" "IRR" "ISK" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRU" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PYG" "QAR" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SGD" "SHP" "SLE" "SLL" "SOS" "SRD" "SSP" "STN" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UGX" "USN" "UYI" "UYU" "UYW" "UZS" "VED" "VES" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL"

used as currency code for money numbers. along ISO 4217 (https://en.wikipedia.org/wiki/ISO_4217)

DecimalPrecisionMultiplier
integer <int32> (DecimalPrecisionMultiplierEnum)
Default: 1
Enum: 1 100 10000 1000000 100000000

is used as multiplier for decimal numbers. when value 1 is used, revlevant numbers are interpreted as floating-point numbers. for all other values, relevant numbers are interpreted as integer and need to be devided by the Multiplier to get the decimal representation.

Responses

Callbacks

Request samples

Content type
application/json
{
  • "cbTerminalID": "undefined",
  • "cbReceiptReference": "undefined",
  • "cbReceiptMoment": "2020-06-29T17:45:40.505Z",
  • "cbChargeItems": [
    ],
  • "cbPayItems": [
    ],
  • "ftCashBoxID": "00000000-0000-0000-0000-000000000000",
  • "ftPosSystemID": "00000000-0000-0000-0000-000000000000",
  • "ftReceiptCase": 0,
  • "ftReceiptCaseData": "string",
  • "ftQueueID": "fb6ee7af-f98e-4d5a-891b-ff24d7313836",
  • "cbPreviousReceiptReference": "string",
  • "cbReceiptAmount": null,
  • "cbUser": null,
  • "cbArea": null,
  • "cbCustomer": null,
  • "cbSettlement": null,
  • "Currency": "EUR",
  • "DecimalPrecisionMultiplier": 1
}

Response samples

Content type
application/json
{
  • "ftQueueID": "00000000-0000-0000-0000-000000000000",
  • "ftQueueItemID": "00000000-0000-0000-0000-000000000000",
  • "ftQueueRow": 0,
  • "ftCashBoxIdentification": "undefined",
  • "ftReceiptIdentification": "ft0#",
  • "ftReceiptMoment": "2020-06-29T17:45:40.505Z",
  • "ftSignatures": [
    ],
  • "ftState": 0,
  • "ftStateData": "string",
  • "ftCashBoxID": "00000000-0000-0000-0000-000000000000",
  • "cbTerminalID": "undefined",
  • "cbReceiptReference": "undefined",
  • "ftReceiptHeader": [
    ],
  • "ftChargeItems": [
    ],
  • "ftChargeLines": [
    ],
  • "ftPayItems": [
    ],
  • "ftPayLines": [
    ],
  • "ftReceiptFooter": [
    ]
}

Callback payload samples

Callback
POST: OperationCallbackStateUrl
Content type
application/json
{
  • "OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
  • "QueueID": "1de0bf44-f9a4-4fc2-8140-0edabd852b0a",
  • "State": "done",
  • "StateMessage": "string",
  • "StateData": "string"
}

execute a issue call end-to-end

execute a issue call end-to-end

Authorizations:
(CashBoxIdCashBoxAccessToken)
header Parameters
x-operation-id
required
any (x-operation-id)

operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.

x-operation-lifetime
any (x-operation-lifetime)

operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.

x-operation-callback-state
any (x-operation-callback-state)

single state callback setting for current operation, executed each time when a status change occures

x-terminal-id
any (x-terminal-id)

identifies the terminal #TODO

x-possystem-id
any (x-possystem-id)

identifies the calling possystem #TODO

Request Body schema: application/json
One of
required
object (ReceiptRequest_1)

The cash register transfers the data of an entire receipt request to the fiskaltrust.Middleware using the ReceiptRequest data structure.

required
object (ReceiptResponse_1)

The fiskaltrust.Middleware sends back the processed data to the cash register through the receipt response.

Responses

Callbacks

Request samples

Content type
application/json
Example
{
  • "ReceiptRequest": {
    },
  • "ReceiptResponse": {
    }
}

Response samples

Content type
application/json
{
  • "ftQueueID": "fb6ee7af-f98e-4d5a-891b-ff24d7313836",
  • "ftQueueItemID": "92273d5f-5d3a-4415-bfc8-f7895ceaecf6",
  • "DocumentURL": "http://example.com",
  • "DocumentContentType": "string"
}

Callback payload samples

Callback
POST: OperationCallbackStateUrl
Content type
application/json
{
  • "OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
  • "QueueID": "1de0bf44-f9a4-4fc2-8140-0edabd852b0a",
  • "State": "done",
  • "StateMessage": "string",
  • "StateData": "string"
}

get content of an issued receipt

get content of an issued receipt in requested format, without updateing the submitted state

Authorizations:
(CashBoxIdCashBoxAccessToken)
path Parameters
QueueId
required
string <uuid>
QueueItemId
required
string <uuid>

Responses

Response samples

Content type
No sample

updates an issued and/or submitted receipt

execute a update call end-to-end

Authorizations:
(CashBoxIdCashBoxAccessToken)
path Parameters
QueueId
required
string <uuid>
QueueItemId
required
string <uuid>
header Parameters
x-operation-id
required
any (x-operation-id)

operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.

X-operation-lifetime
any (x-operation-lifetime)

operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.

x-operation-callback-state
any (x-operation-callback-state)

single state callback setting for current operation, executed each time when a status change occures

x-terminal-id
any (x-terminal-id)

identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

x-possystem-id
any (x-possystem-id)

identifies the calling possystem #TODO

Request Body schema: application/json
Action
required
string (IssueUpdateActionEnum)

Responses

Callbacks

Request samples

Content type
application/json
Example
{
  • "Action": "accept"
}

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "status": 100,
  • "title": "string",
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "errors": [
    ]
}

Callback payload samples

Callback
POST: OperationCallbackStateUrl
Content type
application/json
{
  • "OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
  • "QueueID": "1de0bf44-f9a4-4fc2-8140-0edabd852b0a",
  • "State": "done",
  • "StateMessage": "string",
  • "StateData": "string"
}

link visualization via qr code

get image of qr code for digital receipt url

Authorizations:
(CashBoxIdCashBoxAccessToken)
path Parameters
QueueId
required
string <uuid>
QueueItemId
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "status": 100,
  • "title": "string",
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "errors": [
    ]
}

gives the information, if the receipt was delivered, at leasted once

TBD

Authorizations:
(CashBoxIdCashBoxAccessToken)
path Parameters
QueueId
required
string <uuid>
QueueItemId
required
string <uuid>

Responses

Response samples

Content type
application/json
{ }

exectue a pay call end-to-end

Authorizations:
(CashBoxIdCashBoxAccessToken)
header Parameters
x-operation-id
required
any (x-operation-id)

operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.

x-operation-lifetime
any (x-operation-lifetime)

operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.

x-operation-callback-state
any (x-operation-callback-state)

single state callback setting for current operation, executed each time when a status change occures

x-terminal-id
any (x-terminal-id)

identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

x-possystem-id
any (x-possystem-id)

identifies the calling possystem #TODO

Request Body schema: application/json
Protocol
required
string (PaymentProtocolEnum)
Default: "use_auto"
Enum: "use_first" "use_all" "use_auto" "use_none" "bluecode" "hobex_zvt" "hobex_restapi" "hobex_softpos_posit" "gp_softpos_gptom" "gp_mpas" "gp_zvt" "payone_softpos_wpi" "payone_serverapi" "payone_fistdata" "worldline_wpi_1_3" "worldline_wpi_2"

a list of supported protocols use_first can be used to use first detected payment protocol for the specific cashboxid/terminalid combination use_all triggers all available payment protocols for the specific cashboxid/terminalid combination and uses first successfull use_auto triggers a automaticaly selected, single payment protocol, best match for given PayItemCase use_none asks the customer, to select one

Action
required
string (PaymentActionEnum)
Enum: "payment" "cancel" "refund" "pre_authorization" "other"

a list of supported actions not each protocol supports each action

required
object (PayItem)

represents a item related to a payment

AcceptUnderPayment
boolean
Default: false
AcceptOverPayment
boolean
Default: true
cbTerminalID
string <= 1023 characters
Default: "undefined"

The unique identification of the input-station/terminal within a cash-register/pos-system identified by ftCashBoxID.

ftCashBoxID
string <uuid>
Default: "00000000-0000-0000-0000-000000000000"

identification of the cash register

ftPosSystemID
string <uuid>
Default: "00000000-0000-0000-0000-000000000000"

identification of the used software of the cash register

Responses

Callbacks

Request samples

Content type
application/json
Example

request a payment amount is EUR 1.50 chooses a payment-device assigned to cbTerminalId by itself

{
  • "Action": "payment",
  • "Protocol": "use_auto",
  • "cbPayItem": {
    },
  • "cbTerminalId": 1
}

Response samples

Content type
application/json
{
  • "Protocol": "use_first",
  • "ftQueueID": "00000000-0000-0000-0000-000000000000",
  • "ftPayItems": [
    ]
}

Callback payload samples

Callback
POST: OperationCallbackStateUrl
Content type
application/json
{
  • "OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
  • "QueueID": "1de0bf44-f9a4-4fc2-8140-0edabd852b0a",
  • "State": "done",
  • "StateMessage": "string",
  • "StateData": "string"
}

stops ongoing pay call

Authorizations:
(CashBoxIdCashBoxAccessToken)
header Parameters
x-operation-id
required
any (x-operation-id)

operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.

x-operation-lifetime
any (x-operation-lifetime)

operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.

x-operation-callback-state
any (x-operation-callback-state)

single state callback setting for current operation, executed each time when a status change occures

x-terminal-id
any (x-terminal-id)

identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

x-possystem-id
any (x-possystem-id)

identifies the calling possystem #TODO

Responses

Callbacks

Callback payload samples

Callback
POST: OperationCallbackStateUrl
Content type
application/json
{
  • "OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
  • "QueueID": "1de0bf44-f9a4-4fc2-8140-0edabd852b0a",
  • "State": "done",
  • "StateMessage": "string",
  • "StateData": "string"
}

gets a single entry of a specific

gets a single entry of a specific

Authorizations:
(CashBoxIdCashBoxAccessToken)
path Parameters
StorageType
required
string (StorageTypeEnum)
Enum: "OperationItem" "OperationStateJournal" "PayItem" "ChargeItem" "QueueItem" "IssueItem" "ActionJournal" "ReceiptJournal"
Id
required
string <uuid>

Responses

Response samples

Content type
application/json
Example
{
  • "OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
  • "Method": "string",
  • "Path": "string",
  • "Header": { },
  • "Request": { },
  • "Response": { },
  • "LastState": "done",
  • "StorageType": "OperationItem"
}

echo

health check

order

execute orders

pay

execute payments

starts a pay request

Authorizations:
(CashBoxIdCashBoxAccessToken)
header Parameters
x-operation-id
required
any (x-operation-id)

operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.

x-operation-lifetime
any (x-operation-lifetime)

operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.

x-operation-callback-finalized
any (x-operation-callback-finalized)

single callback setting for current operation, executed once the operation is in final state, done or failed

x-operation-callback-state
any (x-operation-callback-state)

single state callback setting for current operation, executed each time when a status change occures

x-terminal-id
any (x-terminal-id)

identifies the terminal and overwrites also TerminalId in PaymentRequest, if given

Request Body schema: application/json
Protocol
required
string (PaymentProtocolEnum)
Default: "use_auto"
Enum: "use_first" "use_all" "use_auto" "use_none" "bluecode" "hobex_zvt" "hobex_restapi" "hobex_softpos_posit" "gp_softpos_gptom" "gp_mpas" "gp_zvt" "payone_softpos_wpi" "payone_serverapi" "payone_fistdata" "worldline_wpi_1_3" "worldline_wpi_2"

a list of supported protocols use_first can be used to use first detected payment protocol for the specific cashboxid/terminalid combination use_all triggers all available payment protocols for the specific cashboxid/terminalid combination and uses first successfull use_auto triggers a automaticaly selected, single payment protocol, best match for given PayItemCase use_none asks the customer, to select one

Action
required
string (PaymentActionEnum)
Enum: "payment" "cancel" "refund" "pre_authorization" "other"

a list of supported actions not each protocol supports each action

required
object (PayItem)

represents a item related to a payment

AcceptUnderPayment
boolean
Default: false
AcceptOverPayment
boolean
Default: true
cbTerminalID
string <= 1023 characters
Default: "undefined"

The unique identification of the input-station/terminal within a cash-register/pos-system identified by ftCashBoxID.

ftCashBoxID
string <uuid>
Default: "00000000-0000-0000-0000-000000000000"

identification of the cash register

ftPosSystemID
string <uuid>
Default: "00000000-0000-0000-0000-000000000000"

identification of the used software of the cash register

Responses

Callbacks

Request samples

Content type
application/json
Example

request a payment amount is EUR 1.50 chooses a payment-device assigned to cbTerminalId by itself

{
  • "Action": "payment",
  • "Protocol": "use_auto",
  • "cbPayItem": {
    },
  • "cbTerminalId": 1
}

Callback payload samples

Callback
Content type
application/json
{
  • "OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
  • "QueueID": "1de0bf44-f9a4-4fc2-8140-0edabd852b0a",
  • "State": "done",
  • "StateMessage": "string",
  • "StateData": "string"
}

stops a ongoing pay request

Authorizations:
(CashBoxIdCashBoxAccessToken)
header Parameters
x-operation-id
required
any (x-operation-id)

operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.

x-operation-lifetime
any (x-operation-lifetime)

operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.

x-operation-callback-finalized
any (x-operation-callback-finalized)

single callback setting for current operation, executed once the operation is in final state, done or failed

x-operation-callback-state
any (x-operation-callback-state)

single state callback setting for current operation, executed each time when a status change occures

x-terminal-id
any (x-terminal-id)

identifies the terminal and overwrites also TerminalId in PaymentRequest, if given

Responses

Callbacks

Callback payload samples

Callback
Content type
application/json
{
  • "OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
  • "QueueID": "1de0bf44-f9a4-4fc2-8140-0edabd852b0a",
  • "State": "done",
  • "StateMessage": "string",
  • "StateData": "string"
}

get state of pay request

get state of pay request

Authorizations:
(CashBoxIdCashBoxAccessToken)
header Parameters
x-operation-id
any (x-operation-id)

operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.

x-operation-lifetime
any (x-operation-lifetime)

operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.

x-terminal-id
any (x-terminal-id)

identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

Responses

Response samples

Content type
application/json
[
  • {
    }
]

get result of a pay request and purges state from queue/processor

Authorizations:
(CashBoxIdCashBoxAccessToken)
header Parameters
x-operation-id
required
any (x-operation-id)

operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.

x-operation-lifetime
any (x-operation-lifetime)

operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.

x-terminal-id
any (x-terminal-id)

identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

Responses

Response samples

Content type
application/json
Example

response to PayRequestHobexPaymentMinimum_1

{
  • "Protocol": "hobex_restapi",
  • "ftQueueId": "00000000-0000-0000-0000-xxxxxxxxxxxx",
  • "ftPayItems": [
    ]
}

sign

finalize receipts

successfull

timeout / retry

failed

callback usage

starts a sign request

starts a sign request

Authorizations:
(CashBoxIdCashBoxAccessToken)
header Parameters
x-operation-id
required
any (x-operation-id)

operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.

x-operation-lifetime
any (x-operation-lifetime)

operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.

x-operation-callback-finalized
any (x-operation-callback-finalized)

single callback setting for current operation, executed once the operation is in final state, done or failed

x-operation-callback-state
any (x-operation-callback-state)

single state callback setting for current operation, executed each time when a status change occures

x-terminal-id
any (x-terminal-id)

identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

x-possystem-id
any (x-possystem-id)

identifies the calling possystem #TODO

Request Body schema: application/json
cbTerminalID
string <= 1023 characters
Default: "undefined"

The unique identification of the input-station/terminal within a cash-register/pos-system identified by ftCashBoxID.

cbReceiptReference
required
string <= 1023 characters
Default: "undefined"

Reference number send by the cash register. This value must be a unique string/receipt number related to the calling cash register. This string/receipt number is a unique primary key of the dataset of the cash register.

cbReceiptMoment
required
string <date-time>

moment at which the receipt was create by the cash register, must be provided in UTC.

required
Array of objects (ChargeItem)

list of line items related to services and products

required
Array of objects (PayItem)

list of line items related to payments

ftCashBoxID
string <uuid>
Default: "00000000-0000-0000-0000-000000000000"

identification of the cash register

ftPosSystemID
string <uuid>
Default: "00000000-0000-0000-0000-000000000000"

identification of the used software of the cash register

ftReceiptCase
integer <uint64>
Default: 0

Type of business according to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO! this is relevant for fiskaltrust middleware processing and is a country specific mapping. as fallback when not specified, a cash register business case at the point-of-sale is used.

(string or null) or object

optional gives additional details for defined type of business related to fiskaltrust reference. for detailed definition goto https://docs.fiskaltrust.eu !TODO!

ftQueueID
string or null <uuid>

optional routing instruction to identify a specific queue behind a load balancer or in other usecases

cbPreviousReceiptReference
string or null <= 1023 characters

optional Reference cbReceiptReference of the previous receipt. Used to connect multiple requests for a single Business Case.

(integer or null) or (number or null)
Default: null

optional total receipt amount, including value added taxes (=gross receipt amount) given to avoid calculation and rounding differences. systems which are using net amounts as central calculation should alsways use this property. if not provided, the sum of Amount in all provided ftChargeItems is used as total receipt amount. uses DecimalPresissionMultiplier as discriminator between int64 and double

(string or null) or object
Default: null

optional Identification of the user, who creates the receipt.

(string or null) or object
Default: null

optional Identification of the area/section/field, in which the receipt is created. e.g. Table number of a restaurant business; a department of a commercial establishment; the vehicle of a taxi company

(string or null) or object
Default: null

optional Identification of the consumer, for whom the receipt is created. e.g. Email address, phone number, personal tax number

(string or null) or object
Default: null

optional Settlement identification where this receipt will be added. e.g. shift number or day of operation

Currency
string (CurrencyEnum)
Default: "EUR"
Enum: "EUR" "CHF" "CZK" "HUF" "BAM" "DKK" "RON" "NOK" "PLN" "RSD" "SEK" "UAH" "USD" "AED" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AUD" "AWG" "AZN" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BOV" "BRL" "BSD" "BTN" "BWP" "BYN" "BZD" "CAD" "CDF" "CHE" "CHW" "CLF" "CLP" "CNY" "COP" "COU" "CRC" "CUP" "CVE" "DJF" "DOP" "DZD" "EGP" "ERN" "ETB" "FJD" "FKP" "GBP" "GEL" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HKD" "HNL" "HTG" "IDR" "ILS" "INR" "IQD" "IRR" "ISK" "JMD" "JOD" "JPY" "KES" "KGS" "KHR" "KMF" "KPW" "KRW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MOP" "MRU" "MUR" "MVR" "MWK" "MXN" "MXV" "MYR" "MZN" "NAD" "NGN" "NIO" "NPR" "NZD" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PYG" "QAR" "RUB" "RWF" "SAR" "SBD" "SCR" "SDG" "SGD" "SHP" "SLE" "SLL" "SOS" "SRD" "SSP" "STN" "SVC" "SYP" "SZL" "THB" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TWD" "TZS" "UGX" "USN" "UYI" "UYU" "UYW" "UZS" "VED" "VES" "VND" "VUV" "WST" "XAF" "XAG" "XAU" "XBA" "XBB" "XBC" "XBD" "XCD" "XDR" "XOF" "XPD" "XPF" "XPT" "XSU" "XTS" "XUA" "XXX" "YER" "ZAR" "ZMW" "ZWL"

used as currency code for money numbers. along ISO 4217 (https://en.wikipedia.org/wiki/ISO_4217)

DecimalPrecisionMultiplier
integer <int32> (DecimalPrecisionMultiplierEnum)
Default: 1
Enum: 1 100 10000 1000000 100000000

is used as multiplier for decimal numbers. when value 1 is used, revlevant numbers are interpreted as floating-point numbers. for all other values, relevant numbers are interpreted as integer and need to be devided by the Multiplier to get the decimal representation.

Responses

Callbacks

Request samples

Content type
application/json
{
  • "cbTerminalID": "undefined",
  • "cbReceiptReference": "undefined",
  • "cbReceiptMoment": "2020-06-29T17:45:40.505Z",
  • "cbChargeItems": [
    ],
  • "cbPayItems": [
    ],
  • "ftCashBoxID": "00000000-0000-0000-0000-000000000000",
  • "ftPosSystemID": "00000000-0000-0000-0000-000000000000",
  • "ftReceiptCase": 0,
  • "ftReceiptCaseData": "string",
  • "ftQueueID": "fb6ee7af-f98e-4d5a-891b-ff24d7313836",
  • "cbPreviousReceiptReference": "string",
  • "cbReceiptAmount": null,
  • "cbUser": null,
  • "cbArea": null,
  • "cbCustomer": null,
  • "cbSettlement": null,
  • "Currency": "EUR",
  • "DecimalPrecisionMultiplier": 1
}

Response samples

Content type
application/problem+json
{
  • "type": "http://example.com",
  • "status": 100,
  • "title": "string",
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "errors": [
    ]
}

Callback payload samples

Callback
Content type
application/json
{
  • "OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
  • "QueueID": "1de0bf44-f9a4-4fc2-8140-0edabd852b0a",
  • "State": "done",
  • "StateMessage": "string",
  • "StateData": "string"
}

get state of sign request

get state of sign request

Authorizations:
(CashBoxIdCashBoxAccessToken)
header Parameters
x-operation-id
any (x-operation-id)

operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.

x-operation-lifetime
any (x-operation-lifetime)

operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.

x-terminal-id
any (x-terminal-id)

identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

Responses

Response samples

Content type
application/json
[
  • {
    }
]

get result of sign request and purges it from queue

get result of sign request and purges it from queue

Authorizations:
(CashBoxIdCashBoxAccessToken)
header Parameters
x-operation-id
required
any (x-operation-id)

operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.

x-operation-lifetime
any (x-operation-lifetime)

operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.

x-terminal-id
any (x-terminal-id)

identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

Responses

Response samples

Content type
application/json
{
  • "ftQueueID": "00000000-0000-0000-0000-000000000000",
  • "ftQueueItemID": "00000000-0000-0000-0000-000000000000",
  • "ftQueueRow": 0,
  • "ftCashBoxIdentification": "undefined",
  • "ftReceiptIdentification": "ft0#",
  • "ftReceiptMoment": "2020-06-29T17:45:40.505Z",
  • "ftSignatures": [
    ],
  • "ftState": 0,
  • "ftStateData": "string",
  • "ftCashBoxID": "00000000-0000-0000-0000-000000000000",
  • "cbTerminalID": "undefined",
  • "cbReceiptReference": "undefined",
  • "ftReceiptHeader": [
    ],
  • "ftChargeItems": [
    ],
  • "ftChargeLines": [
    ],
  • "ftPayItems": [
    ],
  • "ftPayLines": [
    ],
  • "ftReceiptFooter": [
    ]
}

issue

distribute receipts

starts an issue request

execute a issue call end-to-end publish a digital receipt

Authorizations:
(CashBoxIdCashBoxAccessToken)
header Parameters
x-operation-id
any (x-operation-id)

operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.

x-operation-lifetime
any (x-operation-lifetime)

operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.

x-operation-callback-finalized
any (x-operation-callback-finalized)

single callback setting for current operation, executed once the operation is in final state, done or failed

x-operation-callback-state
any (x-operation-callback-state)

single state callback setting for current operation, executed each time when a status change occures

x-terminal-id
any (x-terminal-id)

identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

x-possystem-id
any (x-possystem-id)

identifies the calling possystem #TODO

Request Body schema: application/json
One of
required
object (ReceiptRequest_1)

The cash register transfers the data of an entire receipt request to the fiskaltrust.Middleware using the ReceiptRequest data structure.

required
object (ReceiptResponse_1)

The fiskaltrust.Middleware sends back the processed data to the cash register through the receipt response.

Responses

Callbacks

Request samples

Content type
application/json
Example
{
  • "ReceiptRequest": {
    },
  • "ReceiptResponse": {
    }
}

Callback payload samples

Callback
Content type
application/json
{
  • "OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
  • "QueueID": "1de0bf44-f9a4-4fc2-8140-0edabd852b0a",
  • "State": "done",
  • "StateMessage": "string",
  • "StateData": "string"
}

updates an issue request

execute a issue call end-to-end

Authorizations:
(CashBoxIdCashBoxAccessToken)
path Parameters
QueueId
required
string <uuid>
QueueItemId
required
string <uuid>
header Parameters
x-operation-id
any (x-operation-id)

operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.

x-operation-lifetime
any (x-operation-lifetime)

operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.

x-operation-callback-finalized
any (x-operation-callback-finalized)

single callback setting for current operation, executed once the operation is in final state, done or failed

x-operation-callback-state
any (x-operation-callback-state)

single state callback setting for current operation, executed each time when a status change occures

x-terminal-id
any (x-terminal-id)

identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

Request Body schema: application/json
Action
required
string (IssueUpdateActionEnum)

Responses

Callbacks

Request samples

Content type
application/json
Example
{
  • "Action": "accept"
}

Callback payload samples

Callback
Content type
application/json
{
  • "OperationID": "5df88c20-350a-4721-80c0-dbff74de4240",
  • "QueueID": "1de0bf44-f9a4-4fc2-8140-0edabd852b0a",
  • "State": "done",
  • "StateMessage": "string",
  • "StateData": "string"
}

get state of issue request

get state of sign request

Authorizations:
(CashBoxIdCashBoxAccessToken)
header Parameters
x-operation-id
any (x-operation-id)

operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.

x-operation-lifetime
any (x-operation-lifetime)

operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.

x-terminal-id
any (x-terminal-id)

terminal identification

Responses

Response samples

Content type
application/json
[
  • {
    }
]

get result of issue request and purges the state from queue/processor

get result of issue request and purges it from queue/processor

Authorizations:
(CashBoxIdCashBoxAccessToken)
header Parameters
x-operation-id
required
any (x-operation-id)

operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.

x-operation-lifetime
any (x-operation-lifetime)

operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.

x-terminal-id
any (x-terminal-id)

identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

Responses

Response samples

Content type
application/json
{
  • "ftQueueID": "fb6ee7af-f98e-4d5a-891b-ff24d7313836",
  • "ftQueueItemID": "92273d5f-5d3a-4415-bfc8-f7895ceaecf6",
  • "DocumentURL": "http://example.com",
  • "DocumentContentType": "string"
}

blocks for a maxiumum timeout in second (default is 15) and comes back with 200 if delivered and 204 if not deliverd

TBD

Authorizations:
(CashBoxIdCashBoxAccessToken)
path Parameters
QueueId
required
string <uuid>
QueueItemId
required
string <uuid>
query Parameters
Timeout
number <int>
Default: 15

Responses

Response samples

Content type
application/json
{ }

blocks for a maxiumum timeout in second (default is 15) and comes back with 200 if delivered and 204 if not deliverd

TBD TEST

Authorizations:
(CashBoxIdCashBoxAccessToken)
path Parameters
QueueId
required
string <uuid>
QueueItemId
required
string <uuid>
query Parameters
Timeout
number <int>
Default: 15

Responses

Response samples

Content type
application/json
{ }

journal

export data

get a single journal entry by id

Authorizations:
(CashBoxIdCashBoxAccessToken)
path Parameters
QueueId
required
string <uuid>
StorageType
required
string (StorageTypeEnum)
Enum: "OperationItem" "OperationStateJournal" "PayItem" "ChargeItem" "QueueItem" "IssueItem" "ActionJournal" "ReceiptJournal"
Id
required
string <uuid>
header Parameters
x-operation-id
required
any (x-operation-id)

operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.

x-operation-lifetime
any (x-operation-lifetime)

operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.

x-terminal-id
any (x-terminal-id)

identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

Responses

/PeekJournalRange/{QueueId}/{StorageType}

Authorizations:
(CashBoxIdCashBoxAccessToken)
path Parameters
QueueId
required
string <uuid>
StorageType
required
string (StorageTypeEnum)
Enum: "OperationItem" "OperationStateJournal" "PayItem" "ChargeItem" "QueueItem" "IssueItem" "ActionJournal" "ReceiptJournal"
header Parameters
x-operation-id
required
any (x-operation-id)

operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.

x-operation-lifetime
any (x-operation-lifetime)

operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.

x-terminal-id
any (x-terminal-id)

identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

Responses

configuration

configuration handling and management tools for cash registers

/pair

header Parameters
x-operation-id
any (x-operation-id)

operation identification, for implementation of idempotnency, to detect multiple calls for same operations related to communicatio issues or communication network switch. calls or messages with same OperationId schould end up in only one action.

x-operation-lifetime
any (x-operation-lifetime)

operation lifetime, in ms Lifetime of the operation/message to be accepted by the receiver in ms. Timeout=NAK, Timeout happens after Lifetime+BusSLA.

x-terminal-id
any (x-terminal-id)

identifies the terminal and overwrites also TerminalId in ReceiptRequest, if given

Request Body schema: application/json

use to get credentials for initial setup

Pin
string <= 1023 characters

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "CashBoxID": "604a88e9-9153-4ab6-9da8-5c8e2b6a2f6b",
  • "AccessToken": "string"
}

/rebuild

Authorizations:
(CashBoxIdCashBoxAccessToken)

Responses