Zum Hauptinhalt springen
API docs by Redocly

fiskaltrust Middleware (v0)

Download OpenAPI specification:Download

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

This fiskaltrust.Middleware is fiskaltrust's core product to abstract common functionality of POS systems.

It provides all required functionality to make POS systems compliant to fiscalization regulations, covered behind a common, international interface.

Integration & protocols

The locally hosted Middleware supports a variety of communication protocols to seamlessly integrate into all kinds of POS software stacks. While this API documentation describes the RESTful, JSON-based HTTP interface, the Middleware can also be used with SOAP (and gRPC in version 1.3+). The SaaS Middleware (i.e. the SignatureCloud) only supports rest communication via the interface describes in these specs.

Depending on the software stack, different approaches are recommended to integrate the Middleware's:

  • .NET client packages for HTTP, gRPC and SOAP are available on Nuget.org (as well as the interface package, which is also published on GitHub)
  • Samples for integrating the Middleware into C, C++, VB6 and Rust are available on GitHub
  • Aside from that, it's of course also possible to integrate the Middleware "manually", e.g. by generaring HTTP clients from these specs

API design principles

The Middleware provides the exact same interface across all markets. Business cases (containing of receipt types, VAT types for charge items, and payment types) are passed to the Middleware in the three case properties; ftReceiptCase, ftChargeItemCase, and ftPayItemCase.

These cases are described in detail in our documentation; a variety of sample requests for common operations is available in a Postman collection.

Authentication

When using a local instance of the Middleware, no authentication or authorization is required to perform requests.
The SaaS version requires authentication via Cashbox ID and Cashbox access token, which can be obtained from the fiskaltrust.Portal.

Please also note that the documentation contains appendices for the different markets the Middleware can be operated in.

Versioning

This spec describes the Middleware's API version 0, which can be used with the Middleware/Launcher 1.1 and 1.2 (for Austria and France).

Version 1, which can be used from Middleware version 1.3 onwards (and thus currently for Germany, Italy and Spain), has minor differences regarding request and return types in the Echo endpoint, and slighty differing URLs. Also, gRPC was added in this version.

fiskaltrust.Middleware

Communication test

This endpoint returns the passed input string and can e.g. used for testing the communication layer to the Middleware without any side effects.

header Parameters
cashboxid
required
string

The ID of the CashBox of this Middleware instance. Only required when using the SaaS Middleware (i.e. SignatureCloud).

accesstoken
required
string

The access token of the CashBox of this Middleware instance. Only required when using the SaaS Middleware (i.e. SignatureCloud).

Request Body schema: application/json
string

Responses

Request samples

Content type
application/json
"string"

Response samples

Content type
application/json
"string"

Sign a receipt, according to local regulations

This endpoint 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 returns the data that need to be printed onto the receipt. More details about composing receipt requests are 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

The ID of the CashBox of this Middleware instance. Only required when using the SaaS Middleware (i.e. SignatureCloud).

accesstoken
required
string

The access token of the CashBox of this Middleware instance. Only required when using the SaaS Middleware (i.e. SignatureCloud).

Request Body schema: application/json
ftCashBoxID
string or null

This ID is assigned by the fiskaltrust-user portal and is a part of the authentication of the cash register.

ftQueueID
string or null

The QueueID is required only when a load balancer is used. The value of the ftQueueID allows the load balancer to find the correct route to the corresponding Queue.

ftPosSystemId
string or null

This field identifies and documents the type and software version of the PosSystem sending the request. It is used for audits and as a base for commission calculation. The PosSystem itself has to be created in the portal and its ID can be implemented as a constant value by the PosCreator.

cbTerminalID
string or null

The unique identification of the input station/ cash register within a ftCashBoxID

cbReceiptReference
string or null

Reference number returned by the cash register. Ideally, this value would be a unique receipt number for the cash register, to allow saving of the return value to the cash register data set.

cbReceiptMoment
string <date-time>

The time of receipt creation. Must be provided in UTC.

Array of objects or null (ChargeItem)

List of services or items sold.

Array of objects or null (PayItem)

List of payment received.

ftReceiptCase
integer <int64>

Type of business transaction according to the reference table in the appendix. It is used to choose the right processing logic.

ftReceiptCaseData
string or null

Additional data for the business transaction, currently accepted only in JSON format. Although all string values are supported, we suggest using data structures serialized into JSON format.

cbReceiptAmount
number or null <double>

Total receipt amount incl. taxes (gross receipt amount). If it is not provided, it can be calculated with the sum of the amounts of the cbChargeItems. It can be useful and important for systems working with net amounts, as it helps to apply different methods of calculation and rounding.

cbUser
string or null

Identification of the user, who creates the receipt. Although all string values are supported, we suggest using data structures serialized into JSON format.

cbArea
string or null

Identification of the section/field, in which the receipt is created. Although all string values are supported, we suggest using data structures serialized into JSON format.

cbCustomer
string or null

Identification of the client, for whom the receipt is created. Although all string values are supported, we suggest using data structures serialized into JSON format.

cbSettlement
string or null

Settlement identification where this receipt will be added.

cbPreviousReceiptReference
string or null

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

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
{
  • "ftCashBoxID": "string",
  • "ftQueueID": "string",
  • "ftQueueItemID": "string",
  • "ftQueueRow": 0,
  • "cbTerminalID": "string",
  • "cbReceiptReference": "string",
  • "ftCashBoxIdentification": "string",
  • "ftReceiptIdentification": "string",
  • "ftReceiptMoment": "2019-08-24T14:15:22Z",
  • "ftReceiptHeader": [
    ],
  • "ftChargeItems": [
    ],
  • "ftChargeLines": [
    ],
  • "ftPayItems": [
    ],
  • "ftPayLines": [
    ],
  • "ftSignatures": [
    ],
  • "ftReceiptFooter": [
    ],
  • "ftState": 0,
  • "ftStateData": "string"
}

Export data from the Middleware

This endpoint can be used to export receipt data from the Middleware, e.g. in CSV, XML, or different country-specific formats (like the DSFinV-K in Germany or the DEP7 format in Austria). 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.

query Parameters
ftJournalType
required
integer <int64>

The type determining the export that should be generated. Export types are either prefixed with the HEX representation of the market's ISO code, or 0x00 for generic exports. More details and types can be found here and in the respective appendices.

from
required
integer <int64>

The inclusive timestamp defining the begin of the export (in .NET ticks - this is not a Unix timestamp).

to
required
integer <int64>

The inclusive timestamp defining the end of the export (in .NET ticks - this is not a Unix timestamp).

header Parameters
cashboxid
required
string

The ID of the CashBox of this Middleware instance. Only required when using the SaaS Middleware (i.e. SignatureCloud).

accesstoken
required
string

The access token of the CashBox of this Middleware instance. Only required when using the SaaS Middleware (i.e. SignatureCloud).

Responses

Response samples

Content type
application/json
"string"