Data Structures

This chapter outlines several data structures, which are used in the communication with the fiskaltrust.Middleware.

The following conventions apply to all tables in this chapter:

• Field names are the JSON property names and are case-sensitive.
• Fields marked with * are required and are always serialized, even when they hold their default value. All other fields are optional and are omitted from the JSON payload when they are null. Optional numeric fields are also omitted when they hold their default value (for example Position with the value 0). Collections that are initialized by the Middleware, such as ftSignatures, are always serialized, even when they are empty.
• Nullable indicates whether the field accepts null.
• Fields of type number($decimal) are interpreted according to the DecimalPrecisionMultiplier of the containing structure: when the multiplier is 1 they are floating-point numbers, otherwise they are integers that must be divided by the multiplier to obtain the decimal representation.

ReceiptRequest

The cash register transfers the data of an entire receipt request to fiskaltrust.Middleware using the ReceiptRequest data structure. The details of the fields supported by this structure are outlined in the following table.

The ftReceiptCase fiskaltrust field is of critical importance for the correct processing of the receipt. This field defines the receipt type, determines whether the receipt must be secured according to national law, and specifies how to calculate the correct values for each national counter.

Field Name	Data Type	Default Value	Nullable	Description
cbTerminalID	string Max 1023	null	true	Optional unique identification of the input-station/terminal within a cash-register/pos-system identified by ftCashBoxID.
cbReceiptReference*	string Max 1023	-	false	The reference number sent 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 for the cash register's dataset.
cbReceiptMoment*	string($date-time)	-	false	The moment at which the receipt was created by the cash register. It must be provided in UTC. Example: 2020-06-29T17:45:40.505Z.
cbChargeItems*	ChargeItem[]	-	false	List of line items related to services and products. See ChargeItem.
cbPayItems*	PayItem[]	-	false	List of line items related to payments. See PayItem.
ftCashBoxID	string($uuid)	null	true	Identification of the cash register.
ftPosSystemId	string($uuid)	null	true	Identification of the used software of the cash register.
ftReceiptCase*	integer($uint64)	0	false	Type of business according to fiskaltrust reference. For more information, see ftReceiptCase. This field is relevant for fiskaltrust.middleware processing and represents a country-specific mapping.
ftReceiptCaseData	object	null	true	This optional field provides additional details for the defined type of business, as referenced by fiskaltrust.
ftQueueID	string($uuid)	null	true	Optional routing instruction used to identify a specific queue behind a load balancer or in other use cases.
cbPreviousReceiptReference	string Max 1023 or string[]	null	true	Optional reference to the cbReceiptReference of one or more previous receipts. This is used to connect multiple requests within a single Business Case. Either a single string or an array of strings can be provided.
cbReceiptAmount	number($decimal)	null	true	Optional total receipt amount, including value added taxes (i.e., gross receipt amount). This field is provided to prevent calculation and rounding differences. Systems that use net amounts as the central calculation should always use this property. If not provided, the sum of amount in all provided cbChargeItems is used as total receipt amount.
cbUser	object	null	true	Optional Identification of the user who creates the receipt.
cbArea	object	null	true	Optional Identification of the area, section, or field in which the receipt is created. Examples include table number of a restaurant business, a department of a commercial establishment, or the vehicle of a taxi company.
cbCustomer	object	null	true	Optional Identification of the consumer for whom the receipt is created. Examples include an email address, phone number, or personal tax number.
cbSettlement	object	null	true	Optional Settlement identification indicating where this receipt will be added. Examples include a shift number or the day of operation.
Currency	string (enum)	EUR	false	This field is used as currency code for money numbers along ISO 4217 (https://en.wikipedia.org/wiki/ISO_4217). 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]
DecimalPrecisionMultiplier	integer($int32)	1	false	This field is used as a multiplier for decimal numbers. When the value is 1, the relevant numbers are interpreted as floating-point numbers. For all other values, the relevant numbers are interpreted as integers and must be divided by the Multiplier to obtain the decimal representation. Enum: [1, 100, 10000, 1000000, 100000000]

Table 1. Fields of the ReceiptRequest data structure sent by the cash register to the Middleware.

ReceiptResponse

fiskaltrust.Middleware sends the processed data back to the cash register through the ReceiptResponse. The data included in the request, such as header, service, pay items, and footer, will not be sent back. The returned data is added to the receipt as supplement to the data of the receipt request.

Field Name	Data Type	Default Value	Nullable	Description
ftQueueID*	string($uuid)	00000000-0000-0000-0000-000000000000	false	Identification of the queue used for processing.
ftQueueItemID*	string($uuid)	00000000-0000-0000-0000-000000000000	false	Identification of the item within a specific queue that is used for processing.
ftQueueRow*	integer($int64)	0	false	Row in which the item is stored within a specific queue used for processing.
ftCashBoxIdentification*	string Max 1023	-	false	Human-readable identification or serial number of the cash register, as required by national regulations/law. This must be printed on the receipt to identify the cash register within a merchant and is unique over a single merchant. Note: do not confuse ftCashBoxID with ftCashBoxIdentification. The ftCashBoxID identifies a configuration container and is used for authentication purposes. In contrast, ftCashBoxIdentification is the human-readable identification of the queue.
ftCashBoxID*	string($uuid)	null	true	Mirror from ReceiptRequest identification of the cash register.
cbTerminalID	string Max 1023	null	true	Mirror from ReceiptRequest. Represents the unique identification of the input station or terminal within a cash-register or POS system, as identified by ftCashBoxID.
cbReceiptReference*	string Max 1023	null	true	Mirror from ReceiptRequest. Represents the reference number sent by the cash register. This value must be a unique string/receipt number related to the calling cash register and serves as a unique primary key within the cash register's dataset.
ftReceiptIdentification*	string Max 1023	-	false	Human-readable identification of the receipt, as required by national regulations/law and the ftCashBoxIdentification/Queue. This must be printed on the receipt to identify it within a merchant and cash register. This always starts with ft, followed by the row number of the queue in hexadecimal, then a #, followed by the national required or defined receipt numbering.
ftReceiptMoment*	string($date-time)	-	false	The moment at which the receipt was processed by fiskaltrust.Middleware. It must be provided in UTC. This must be printed on the receipt at local date/time. Example: 2020-06-29T17:45:40.505Z.
ftReceiptHeader	string[]	null	true	Additional header lines that must be printed on the receipt.
ftChargeItems	ChargeItem[]	null	true	List of line items added by fiskaltrust.Middleware during request processing, related to services and products. These items must be printed on the receipt. See ChargeItem.
ftChargeLines	string[]	null	true	Additional text lines for line items related to services and products. This must be printed on the receipt.
ftPayItems	PayItem[]	null	true	List of line items added by fiskaltrust.Middleware during request processing, related to payments. These items must be printed on the receipt. See PayItem.
ftPayLines	string[]	null	true	Additional text lines for line items related to payments. This must be printed on the receipt.
ftSignatures	SignatureItem[]	[]	false	List of signature items generated by fiskaltrust.Middleware. This field is always present in the response and is an empty list when no signatures were generated. This must be printed on the receipt according to given format instructions to comply with national regulations/law and to enable fiskaltrust's Compliance-as-a-Service. See SignatureItem.
ftReceiptFooter	string[]	null	true	Additional footer lines that must be printed on the receipt.
ftState*	integer($uint64)	0	false	Indicates the status of the fiskaltrust.Middleware according to fiskaltrust reference. For more information, see ftState.
ftStateData	object	null	true	This optional field provides additional details for the status of fiskaltrust.Middleware related to fiskaltrust reference.

Table 2. Fields of the ReceiptResponse data structure returned by the Middleware to the cash register.

ChargeItem

Represents an item related to a service or a product that is taxable.

Field Name	Data Type	Default Value	Nullable	Description
ftChargeItemId	string($uuid)	null	true	Optional. This field is used as an identifier of a chargeitem when reading data.
Quantity*	number($decimal)	1	false	Defines the quantity of the line item. The line items with the same Description, VATRate, and itemprice (=Amount/Quantity) can be accumulated for better visualization.
Description*	string Max 1023	-	false	Defines the description of the line item. The line items with the same Description, VATRate, and itemprice (=Amount/Quantity) can be accumulated for better visualization.
Amount*	number($decimal)	0	false	Defines the (total) amount of the line item. To obtain itemprice, the amount must be divided by quantity.
VATRate*	number($decimal)	0	false	Defines the value added tax rate as a percentage of the line item. The line items with same Description, VATRate, and itemprice (=Amount/Quantity) can be accumulated for better visualization.
ftChargeItemCase	integer($uint64)	0	false	Optional. Defines the type of service or product related to fiskaltrust reference. For more information, see ftChargeItemCase. This field is relevant for fiskaltrust.middleware processing and represents a country-specific mapping. If not specified, the service or product delivered at the point of sale with the defined VATRate is used as a fallback.
ftChargeItemCaseData	object	null	true	Optional. Provides additional details for defined type of service or product related to fiskaltrust reference.
VATAmount	number($decimal)	null	true	Optional. When provided and not null, this amount is used as the total value-added tax for the line item to avoid rounding when accumulating value added taxes. The systems that use net amounts as central calculation should always use this property.
Moment	string($date-time)	null	true	Optional. The moment at which the service or product was ordered or delivered. It must be provided in UTC. The accumulated line items obtain the minimum (first) moment. If not provided, the cbReceiptMoment is used as fallback. Example: 2020-06-29T17:45:40.505Z.
Position	number($decimal)	0	false	Optional. Used to sort and group the line items for receipt visualization. The accumulated line items obtain the minimum (first) position. When grouping of multiple line items is activated with a specific instruction/flag in ftReceiptCase, Position is treated as a decimal number: the whole number represents the grouped line item, and the fractional part is used within the group.
AccountNumber	string Max 1023	null	true	Optional account number for bookkeeping export purposes.
CostCenter	string Max 1023	null	true	Optional cost center for cost accounting purposes.
ProductGroup	string Max 1023	null	true	Optional product group related to line item.
ProductNumber	string Max 1023	null	true	Optional product number related to line item.
ProductBarcode	string Max 1023	null	true	Optional product barcode related to line item.
Unit	string Max 1023	null	true	Optional unit of measurement for the line item. For example, on one charging session of an electric vehicle, this would be Quantity 1 and the total amount of the session within amount. The unit of measurement could be kW for DC charging or minutes for AC charging.
UnitQuantity	number($decimal)	null	true	Optional. The quantity related to the unit of measurement defined in Unit. For example, on one charging session of an electric vehicle, this would be Quantity 1 and the total amount of the session within amount. If the unit of measurement is kW for DC charging, the UnitQuantity could be 65.4, indicating that the line item represents a charging session with a total amount of power of 65.4 kW.
UnitPrice	number($decimal)	null	true	Optional. The price related to the unit of measurement defined in Unit. For example, on one charging session of an electric vehicle, this would be Quantity 1 and the total amount of 30.7 of the session within amount. If the unit of measurement is kW for DC charging, the UnitQuantity could be 65.4 as an example, and for the given total amount the UnitPrice would be 0.5, indicating that the line item represents a charging session with a total amount of power of 65.4 kW with a price of 0.5 per kW.
Currency	string (enum)	EUR	false	This field is used as currency code for money numbers along ISO 4217 (https://en.wikipedia.org/wiki/ISO_4217). 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]
DecimalPrecisionMultiplier	integer($int32)	1	false	This field is used as a multiplier for decimal numbers. When the value is 1, the relevant numbers are interpreted as floating-point numbers. For all other values, the relevant numbers are interpreted as integers and must be divided by the Multiplier to obtain the decimal representation. Enum: [1, 100, 10000, 1000000, 100000000]

Table 3. Fields of the ChargeItem data structure representing a taxable service or product.

PayItem

Represents an item related to a payment.

Field Name	Data Type	Default Value	Nullable	Description
ftPayItemId	string($uuid)	null	true	Optional. This field is used as an identifier of a payitem when reading data.
Quantity	number($decimal)	1	false	Optional. Defines the quantity of the line item. The line items with the same Description and itemprice (=Amount/Quantity) can be accumulated for better visualization. The field is omitted from the JSON payload when it holds the default value 1.
Description*	string Max 1023	-	false	Defines the description of the line item. The line items with the same Description and itemprice (=Amount/Quantity) can be accumulated for better visualization.
Amount*	number($decimal)	0	false	Defines the (total) amount of the line item.
ftPayItemCase	integer($uint64)	0	false	Optional. Defines the type of payment related to fiskaltrust reference. For more information, see ftPayItemCase. This field is relevant for fiskaltrust.middleware processing and represents a country-specific mapping. If not specified, the cash payment at the point of sale is used as a fallback.
ftPayItemCaseData	object	null	true	Optional. Provides additional details for defined type of payment related to fiskaltrust reference.
Moment	string($date-time)	null	true	Optional. The moment at which the payment was executed. It must be provided in UTC. The accumulated line items obtain the minimum (first) moment. If not provided, the cbReceiptMoment is used as fallback. Example: 2020-06-29T17:45:40.505Z.
Position	number($decimal)	0	false	Optional. Used to sort and group the line items for receipt visualization. The accumulated line items obtain the minimum (first) position. When grouping of multiple line items is activated with a specific instruction/flag in ftReceiptCase, Position is treated as a decimal number: the whole number represents the grouped line item, and the fractional part is used within the group.
AccountNumber	string Max 1023	null	true	Optional account number for bookkeeping export purposes.
CostCenter	string Max 1023	null	true	Optional cost center for cost accounting purposes.
MoneyGroup	string Max 1023	null	true	Optional group related to line item.
MoneyNumber	string Max 1023	null	true	Optional number related to line item.
MoneyBarcode	string Max 1023	null	true	Optional barcode or serial number related to line item.
Currency	string (enum)	EUR	false	This field is used as currency code for money numbers along ISO 4217 (https://en.wikipedia.org/wiki/ISO_4217). 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]
DecimalPrecisionMultiplier	integer($int32)	1	false	This field is used as a multiplier for decimal numbers. When the value is 1, the relevant numbers are interpreted as floating-point numbers. For all other values, the relevant numbers are interpreted as integers and must be divided by the Multiplier to obtain the decimal representation. Enum: [1, 100, 10000, 1000000, 100000000]

Table 4. Fields of the PayItem data structure representing a payment.

SignatureItem

The signature of the receipt must comply with national law. The signature data returned in the response must be visualized on the receipt according to the format instructions and the fiskaltrust reference.

The signature entries can also be used to visualize hints and messages related to the fiskaltrust.SecurityMechanism.

Field Name	Data Type	Default Value	Nullable	Description
ftSignatureItemId	string($uuid)	null	true	Optional. This field is used as an identifier of a signatureitem when reading data.
ftSignatureFormat*	integer($uint64)	0	false	Format for displaying signature data according to fiskaltrust reference. For more information, see ftSignatureFormat.
ftSignatureType*	integer($uint64)	0	false	Type of signature according to fiskaltrust reference. For more information, see ftSignatureType.
Caption	string Max 1023	null	true	Optional heading displayed as text above the signature data.
Data*	string Max 1023	-	false	Signature content displayed in the specified format.

Table 5. Fields of the SignatureItem data structure describing receipt signature data.