Data Structures

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

Receipt Request

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	undefined	false	The unique identification of the input-station/terminal within a cash-register/pos-system identified by ftCashBoxID.
cbReceiptReference*	String Max 1023	undefined	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 a unique primary key for the cash register's dataset.
cbReceiptMoment*	string($date-time)	now()	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*				List of line items related to services and products.
cbPayItems*				List of line items related to payments.
ftCashBoxID	string($uuid)	00000000-0000-0000-0000-000000000000	false	Identification of the cash register.
ftPosSystemID	string($uuid)	00000000-0000-0000-0000-000000000000	false	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. If not specified, the cash register’s business case at the point of sale is used as a fallback.
ftReceiptCaseData			false	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 usecases.
cbPrevi-ousReceiptReference	String Max 1023	null	true	Optional reference to cbReceiptReference of the previous receipt. This is used to connect multiple requests withing a single Business Case.
cbReceiptAmount	integer($int64) number($double)		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 ftChargeItems is used as total receipt amount. It uses DecimalPresissionMultiplier as discriminator between int64 and double values.
cbUser			false	Optional Identification of the user who creates the receipt.
cbArea			false	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			false	Optional Identification of the consumer for whom the receipt is created. Examples include an email address, phone number, or personal tax number.
cbSettlement			false	Optional Settlement identification indicating where this receipt will be added. Examples include a shift number or the day of operation.
Currency	CurrencyEnumCurrencyEnumstring	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	DecimalPrecisionMultiplierEnumDecimalPrecisionMulti-plierEnuminteger($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]

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($uint64)	0	false	Row in which the item is stored within a specific queue used for processing.
ftCashBoxIdentification*	String Max 1023	undefined	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.
ftReceiptIdentification*	String Max 1023	ft0#	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)	now()	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.
ftSignatures*				List of signature items generated by fiskaltrust.Middleware. 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.
ftState*	integer($uint64)	0	false	Indicates the status of the fiskaltrust.Middleware according to fiskaltrust reference. For more information, see ftState.
ftStateData			false	This optional field provides additional details for the status of fiskaltrust.Middleware defined type of business related to fiskaltrust reference.
ftCashBoxID	string($uuid)	00000000-0000-0000-0000-000000000000	false	Mirror from ReceiptRequest identification of the cash register.
cbTerminalID	String Max 1023	undefined	false	Mirror from ReceiptRequest. Represents the unique identification of the input station or terminal within a cash-registeror POS system, as identified by ftCashBoxID.
cbReceiptReference*	String Max 1023	undefined	false	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 servers as a unique primary key within the cash register’s dataset.
ftReceiptHeader	String Max 1023		false	Additional header lines that must be printed on the receipt.
ftChargeItems				List of line items added by fiskaltrust.Middleware during request processing, related to services and products. These items must be printed on the receipt.
ftChargeLines	String Max 1023		false	Additional text for line items related to services and products. This must be printed on the receipt.
ftPayItems				List of line items added by fiskaltrust.Middleware during request processing, related to payments. These items must be printed on the receipt.
ftPayLines				Additional text for line items related to payments. This must be printed on the receipt.
ftReceiptFooter				Additional footer lines that must be printed on the receipt.

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*				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. It uses DecimalPresissionMultiplier as discriminator between int64 and double values.
Description*	String Max 1023	null	true	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*				Defines the (total) amount of the line item. To obtain itemprice, the amount must be devided by quantity. It uses DecimalPresissionMultiplier as discriminator between int64 and double values.
VATRate*				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. It uses DecimalPresissionMultiplier as discriminator between int64 and double values.
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			false	Optional. Provides additional details for defined type of service or product related to fiskaltrust reference.
VATAmount			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. It uses DecimalPresissionMultiplier as discriminator between int64 and double values.
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				Optional. Used to sort and group the line items for receipt visualization. The accumulated line items obtain the minimum (first) position. It uses DecimalPresissionMultiplier as discriminator between int64 and double values with a specific instruction/flag in ftReceiptCase. When grouping of multiple line items is activated, Position is threaded 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			true	Optional. The quantity related to the unit of measurement defined in Unit. It uses DecimalPresissionMultiplier as discriminator between int64 and double values. 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			true	Optional. The price related to the unit of measurement defined in Unit. It uses DecimalPresissionMultiplier as discriminator between int64 and double values. 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 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	CurrencyEnumCurrencyEnumstring	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	DecimalPrecisionMultiplierEnumDecimalPrecisionMulti-plierEnuminteger($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]

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 chargeitem when reading data.
Quantity				Defines the quantity of the line item. The line items with the same Description and itemprice (=Amount/Quantity) can be accumulated for better visualization. It uses DecimalPresissionMultiplier as discriminator between int64 and double values.
Description*	String Max 1023	null	true	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*				Defines the (total) amount of the line item. It uses DecimalPresissionMultiplier as discriminator between int64 and double values.
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			false	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				Optional. Used to sort and group the line items for receipt visualization. The accumulated line items obtain the minimum (first) position. It uses DecimalPresissionMultiplier as discriminator between int64 and double values with a specific instruction/flag in ftReceiptCase. When grouping of multiple line items is activated, Position is threaded 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	CurrencyEnumCurrencyEnumstring	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	DecimalPrecisionMultiplierEnumDecimalPrecisionMulti-plierEnuminteger($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]

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 signautreitem 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		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	null	false	Optional signature content displayed in the specified format.