{ "openapi": "3.0.1", "info": { "title": "fiskaltrust Middleware", "description": "

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.

\n\n# Integration & protocols\n

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:

\n\n# API design principles\n

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.

\n\n## Authentication\n

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.

\n\n## Versioning\n

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.

", "contact": { "name": "fiskaltrust", "email": "hello@fiskaltrust.eu" }, "license": { "name": "This documentation and samples are released under the MIT license.", "url": "https://opensource.org/licenses/MIT" }, "version": "v0" }, "paths": { "/json/Echo": { "post": { "tags": [ "fiskaltrust.Middleware" ], "summary": "Communication test", "description": "This endpoint returns the passed input string and can e.g. used for testing the communication layer to the Middleware without any side effects.", "parameters": [ { "name": "cashboxid", "in": "header", "description": "The ID of the CashBox of this Middleware instance. Only required when using the SaaS Middleware (i.e. SignatureCloud).", "required": true, "style": "simple", "schema": { "type": "string" } }, { "name": "accesstoken", "in": "header", "description": "The access token of the CashBox of this Middleware instance. Only required when using the SaaS Middleware (i.e. SignatureCloud).", "required": true, "style": "simple", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "The input string that will be returned.", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/json/Sign": { "post": { "tags": [ "fiskaltrust.Middleware" ], "summary": "Sign a receipt, according to local regulations", "description": "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.", "parameters": [ { "name": "cashboxid", "in": "header", "description": "The ID of the CashBox of this Middleware instance. Only required when using the SaaS Middleware (i.e. SignatureCloud).", "required": true, "style": "simple", "schema": { "type": "string" } }, { "name": "accesstoken", "in": "header", "description": "The access token of the CashBox of this Middleware instance. Only required when using the SaaS Middleware (i.e. SignatureCloud).", "required": true, "style": "simple", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptRequest" } } }, "required": true }, "responses": { "200": { "description": "The signed response, containing the data that should be printed onto the physical receipt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptResponse" } } } } } } }, "/json/Journal": { "post": { "tags": [ "fiskaltrust.Middleware" ], "summary": "Export data from the Middleware", "description": "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.", "parameters": [ { "name": "cashboxid", "in": "header", "description": "The ID of the CashBox of this Middleware instance. Only required when using the SaaS Middleware (i.e. SignatureCloud).", "required": true, "style": "simple", "schema": { "type": "string" } }, { "name": "accesstoken", "in": "header", "description": "The access token of the CashBox of this Middleware instance. Only required when using the SaaS Middleware (i.e. SignatureCloud).", "required": true, "style": "simple", "schema": { "type": "string" } }, { "name": "ftJournalType", "in": "query", "description": "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.", "required": true, "style": "form", "schema": { "type": "integer", "format": "int64" } }, { "name": "from", "in": "query", "description": "The inclusive timestamp defining the begin of the export (in .NET ticks - this is not a Unix timestamp).", "required": true, "style": "form", "schema": { "type": "integer", "format": "int64" } }, { "name": "to", "in": "query", "description": "The inclusive timestamp defining the end of the export (in .NET ticks - this is not a Unix timestamp).", "required": true, "style": "form", "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "The requested export, depending on the ftJournalType header (either as text or base64 encoded zip file).", "content": { "application/json": { "schema": { "type": "string" } } } } } } } }, "components": { "schemas": { "ChargeItem": { "type": "object", "properties": { "position": { "type": "integer", "description": "Line number or position number on the Receipt. Used to preserve the order of lines on the receipt.", "format": "int64" }, "quantity": { "type": "number", "description": "Amount or volume (number) of service(s) or items of the entry.", "format": "double" }, "description": { "type": "string", "description": "Name, description of customary indication, or type of the service or item.", "nullable": true }, "amount": { "type": "number", "description": "Gross total price of service(s). The gross individual price, net total price, and net individual price, have to be calculated using the amount and either VAT rate or VAT amount.", "format": "double" }, "vatRate": { "type": "number", "description": "VAT rate as percentage.", "format": "double" }, "ftChargeItemCase": { "type": "integer", "description": "Type of service or item according to the reference table in the appendix. It is used in order to determine the processing logic for the corresopnding business transaction.", "format": "int64" }, "ftChargeItemCaseData": { "type": "string", "description": "Additional data about the service, currently accepted only in JSON format.", "nullable": true }, "vatAmount": { "type": "number", "description": "If the VAT amount is indicated, it can be used to calculate the net amount in order to avoid rounding errors which are especially likely to appear in row-based net price additions.", "format": "double", "nullable": true }, "accountNumber": { "type": "string", "description": "Account number for transfer into bookkeeping.", "nullable": true }, "costCenter": { "type": "string", "description": "Indicator for transfer into cost accounting (type, center, and payer).", "nullable": true }, "productGroup": { "type": "string", "description": "This value allows the customer the logical grouping of products.", "nullable": true }, "productNumber": { "type": "string", "description": "Value used to identify the product.", "nullable": true }, "productBarcode": { "type": "string", "description": "Product’s barcode", "nullable": true }, "unit": { "type": "string", "description": "Unit of measurement", "nullable": true }, "unitQuantity": { "type": "number", "description": "Quantity of the service(s) of receipt entry, displayed in indicated units.", "format": "double", "nullable": true }, "unitPrice": { "type": "number", "description": "Gross price per indicated unit.", "format": "double", "nullable": true }, "moment": { "type": "string", "description": "Time of service (year, month, day, hour, minute, second)", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "Charge items entries are used for receipt requests as well as for receipt responses." }, "PayItem": { "type": "object", "properties": { "position": { "type": "integer", "description": "Line number or positionnumber on the Receipt. Used to preserve the order of lines on the receipt.", "format": "int64" }, "quantity": { "type": "number", "description": "Number of payments. This value will be set to 1 in most of the cases. It can be greater then 1 e.g. when paying with multiple vouchers of the same value.", "format": "double" }, "description": { "type": "string", "description": "Name or description of payment.", "nullable": true }, "amount": { "type": "number", "description": "Total amount of payment.", "format": "double" }, "ftPayItemCase": { "type": "integer", "description": "Type of payment according to the reference table in the appendix. It is used in order to determine the processing logic.", "format": "int64" }, "ftPayItemCaseData": { "type": "string", "description": "Additional data about the payment, currently accepted only in JSON format.", "nullable": true }, "accountNumber": { "type": "string", "description": "Account number for transfer into bookkeeping.", "nullable": true }, "costCenter": { "type": "string", "description": "Indicator for transfer into cost accounting (type, centre and payer)", "nullable": true }, "moneyGroup": { "type": "string", "description": "This value allows the logical grouping of payment types.", "nullable": true }, "moneyNumber": { "type": "string", "description": "This value identifies the payment type.", "nullable": true }, "moment": { "type": "string", "description": "Time of payment", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "Payment entries are used for receipt requests as well as for receipt responses." }, "ReceiptRequest": { "type": "object", "properties": { "ftCashBoxID": { "type": "string", "description": "This ID is assigned by the fiskaltrust-user portal and is a part of the authentication of the cash register.", "nullable": true }, "ftQueueID": { "type": "string", "description": "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.", "nullable": true }, "ftPosSystemId": { "type": "string", "description": "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.", "nullable": true }, "cbTerminalID": { "type": "string", "description": "The unique identification of the input station/ cash register within a ftCashBoxID", "nullable": true }, "cbReceiptReference": { "type": "string", "description": "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.", "nullable": true }, "cbReceiptMoment": { "type": "string", "description": "The time of receipt creation. Must be provided in UTC.", "format": "date-time" }, "cbChargeItems": { "type": "array", "items": { "$ref": "#/components/schemas/ChargeItem" }, "description": "List of services or items sold.", "nullable": true }, "cbPayItems": { "type": "array", "items": { "$ref": "#/components/schemas/PayItem" }, "description": "List of payment received.", "nullable": true }, "ftReceiptCase": { "type": "integer", "description": "Type of business transaction according to the reference table in the appendix. It is used to choose the right processing logic.", "format": "int64" }, "ftReceiptCaseData": { "type": "string", "description": "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.", "nullable": true }, "cbReceiptAmount": { "type": "number", "description": "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.", "format": "double", "nullable": true }, "cbUser": { "type": "string", "description": "Identification of the user, who creates the receipt. Although all string values are supported, we suggest using data structures serialized into JSON format.", "nullable": true }, "cbArea": { "type": "string", "description": "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.", "nullable": true }, "cbCustomer": { "type": "string", "description": "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.", "nullable": true }, "cbSettlement": { "type": "string", "description": "Settlement identification where this receipt will be added.", "nullable": true }, "cbPreviousReceiptReference": { "type": "string", "description": "cbReceiptReference of the previous receipt. Used to connect multiple requests for a single Business Case.", "nullable": true } }, "additionalProperties": false, "description": "The cash register transfers the data of an entire receipt request to the fiskaltrust.Middleware using the ReceiptRequest data structure." }, "ReceiptResponse": { "type": "object", "properties": { "ftCashBoxID": { "type": "string", "description": "Allocated from request to response.", "nullable": true }, "ftQueueID": { "type": "string", "description": "QueueId used for processing.", "nullable": true }, "ftQueueItemID": { "type": "string", "description": "QueueItemId used for processing.", "nullable": true }, "ftQueueRow": { "type": "integer", "description": "QueueRow used for processing.", "format": "int64" }, "cbTerminalID": { "type": "string", "description": "Allocated from request to response.", "nullable": true }, "cbReceiptReference": { "type": "string", "description": "Allocated from request to response.", "nullable": true }, "ftCashBoxIdentification": { "type": "string", "description": "Cash register identification number.", "nullable": true }, "ftReceiptIdentification": { "type": "string", "description": "Upcounting receipt number allocated through fiskaltrust.SecurityMechanisms.", "nullable": true }, "ftReceiptMoment": { "type": "string", "description": "Time of receipt processing through fiskaltrust.Middleware, provided in UTC.", "format": "date-time" }, "ftReceiptHeader": { "type": "array", "items": { "type": "string" }, "description": "Additional header for the receipt. Each row can contain up to 4096 characters. Line breaks should be inserted by the cash register independently", "nullable": true }, "ftChargeItems": { "type": "array", "items": { "$ref": "#/components/schemas/ChargeItem" }, "description": "Additional data sets in the charge items block which the cash register has to print onto the receipt. By default no additional data is provided. If additional data is provided, these data sets state an amount of „0“.", "nullable": true }, "ftChargeLines": { "type": "array", "items": { "type": "string" }, "description": "Additional text line for the charge items block which the cash register has to print onto the receipt. Each row can contain up to 4096 characters, line breaks should be inserted by the cash register independently.", "nullable": true }, "ftPayItems": { "type": "array", "items": { "$ref": "#/components/schemas/PayItem" }, "description": "Additional data set in the pay items block which the cash register has to print onto the receipt. By default no additional data is provided. If additional data is provided, these data sets state an amount of „0“.", "nullable": true }, "ftPayLines": { "type": "array", "items": { "type": "string" }, "description": "Additional text line for the pay items block which the cash register has to print onto the receipt. Each row can contain up to 4096 characters, line breaks should be inserted by the cash register independently.", "nullable": true }, "ftSignatures": { "type": "array", "items": { "$ref": "#/components/schemas/SignaturItem" }, "description": "Signature block, which the cash register has to print onto the receipt.", "nullable": true }, "ftReceiptFooter": { "type": "array", "items": { "type": "string" }, "description": "Additional footer for the receipt. Each row can contain up to 4096 characters, line breaks should be inserted by the cash register independently.", "nullable": true }, "ftState": { "type": "integer", "description": "Flag indicating the status of the fiskaltrust.Middleware; set accordingly to the reference table in the appendix.", "format": "int64" }, "ftStateData": { "type": "string", "description": "Additional information regarding the status of the fiskaltrust.Middleware, currently accepted only in JSON format.", "nullable": true } }, "additionalProperties": false, "description": "The fiskaltrust.Middleware sends back the processed data to the cash register through the receipt response." }, "SignaturItem": { "type": "object", "properties": { "ftSignatureFormat": { "type": "integer", "description": "Format for displaying signature data according to the reference table in the appendix.", "format": "int64" }, "ftSignatureType": { "type": "integer", "description": "Type of signature according to the reference table in the appendix, e.g.: signature indicating a failure notification", "format": "int64" }, "caption": { "type": "string", "description": "Heading, which has to be displayed as text above the signature data.", "nullable": true }, "data": { "type": "string", "description": "Signature content which has to be displayed in the specified format.", "nullable": true } }, "additionalProperties": false, "description": "The signature entry is only used for the receipt response." } } } }