Skip to main content

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 the fiskaltrust.Middleware using the ReceiptRequest data structure.

The details of fields supported by this data structure are outlined in the table below. The field fiskaltrust receipt case (ftReceiptCase) is of the highest importance for the correct processing of the receipt. This field defines the receipt type, determines if the receipt has to be secured accordingly to the national law, and establishes the way to calculate the correct values for each national counter.

The information necessary for processing of a receipt is provided through the configuration of fiskaltrust.SecurityMechanism.

Field nameData typeDefault Value
Mandatory Field
DescriptionIF-Version
ftCashBoxIDguid/stringempty-string
mandatory
This ID is assigned through the creation of the CashBox and is a part of the authentication of the cash register.0-
ftQueueIDguid/stringnull
optional
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.0-
ftPosSystemIdguid/stringnull
optional
This field identifies and documents the type and software version of the POS-System sending the request. It is used for audits and as a base for commission calculation. The POS-System itself has to be created in the fiskaltrust.Portal and its ID can be implemented as a constant value by the PosCreator.0-
cbTerminalIDString
Max 1k
empty-string
mandatory
The unique identification of the input station/ cash register within a ftCashBoxID.0-
cbReceiptReferenceString
Max 1k
empty-string
mandatory
Reference number send 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.0-
cbReceiptMomentDateTimenull
mandatory
The time of receipt creation. Must be provided in UTC, e.g. 2020-06-29T17:45:40.505Z.0-
cbChargeItemsChargeItem[]null
mandatory
List of services or items sold.0-
cbPayItemsPayItem[]null
mandatory
List of payment received.0-
ftReceiptCaseInt640
mandatory
Type of business transaction according to the reference table in the appendix. It is used to choose the right processing logic.0-
ftReceiptCaseDataString
Max 64k
empty-string
optional
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.0-
cbReceiptAmountDecimal?null
optional
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.0-
cbUserString
Max 1k
empty-string
optional
Identification of the user, who creates the receipt. Although all string values are supported, we suggest using data structures serialized into JSON format.0-
cbAreaString
Max 1k
empty-string
optional
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.
Examples:
Table number of a gastronomic business; a department of a commercial establishment; the vehicle of a taxi company
0-
cbCustomerString
Max 1k
empty-string
optional
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.
Example:
Email address
0-
cbSettlementString
Max 1k
empty-string
optional
Settlement identification where this receipt will be added.0-
cbPreviousReceiptReferenceString
Max 1k
null
optional
cbReceiptReference of the previous receipt. Used to connect multiple requests for a single Business Case.0-
*Table 3. Receipt Request*

C# class ReceiptRequest:

namespace fiskaltrust.ifPOS.v0{  public class ReceiptRequest  {    public string ftCashBoxID { get; set; }    public string ftQueueID { get; set; }    public string ftPosSystemId { get; set; }    public string cbTerminalID { get; set; }    public string cbReceiptReference { get; set; }    public DateTime cbReceiptMoment { get; set; }    public ChargeItem[] cbChargeItems { get; set; }    public PayItem[] cbPayItems { get; set; }    public long ftReceiptCase { get; set; }    public string ftReceiptCaseData { get; set; }    public decimal? cbReceiptAmount { get; set; }    public string cbUser { get; set; }    public string cbArea { get; set; }    public string cbCustomer { get; set; }    public string cbSettlement { get; set; }    public string cbPreviousReceiptReference { get; set; }  }}
*Code 1. Definition of class ReceiptRequest*

Receipt response#

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

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 nameData typeDefault Value Mandatory FieldDescriptionVersion
ftCashBoxIDguid/stringmandatoryAllocated from request to response.0-
ftQueueIDguid/stringmandatoryQueueId used for processing.0-
ftQueueItemIDguid/stringmandatoryQueueItemId used for processing.0-
ftQueueRowlongmandatoryQueueRow used for processing.0-
cbTerminalIDstringmandatoryAllocated from request to response.0-
cbReceiptReferencestringmandatoryAllocated from request to response.0-
ftCashBoxIdentificationstringmandatoryCash register identification number.0-
ftReceiptIdentificationstringmandatoryUpcounting receipt number allocated through fiskaltrust.SecurityMechanisms.0-
ftReceiptMomentDateTimemandatoryTime of receipt processing through fiskaltrust.Middleware, provided in UTC.0-
ftReceiptHeaderstring[]null
optional
Additional header for the receipt. Each row can contain up to 4096 characters. Line breaks should be inserted by the cash register independently.0-
ftChargeItemsChargeItem[]null
optional
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".0-
ftChargeLinesstring[]null
optional
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.0-
ftPayItemsPayItem[]null
optional
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".0-
ftPayLinesstring[]null
optional
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.0-
ftSignaturesSignatureItem[]empty-array
mandatory
Signature block, which the cash register has to print onto the receipt.0-
ftReceiptFooterstring[]null
optional
Additional footer for the receipt. Each row can contain up to 4096 characters, line breaks should be inserted by the cash register independently.0-
ftStateInt640
mandatory
Flag indicating the status of the fiskaltrust.Middleware; set accordingly to the reference table in the appendix.0-
ftStateDatastringempty-string
optional
Additional information regarding the status of the fiskaltrust.Middleware, currently accepted only in JSON format.0-
*Table 4. Receipt Response*

C# class ReceiptResponse:

namespace fiskaltrust.ifPOS.v0{  public partial class ReceiptResponse  {    public string ftCashBoxID { get; set; }    public string ftQueueID { get; set; }    public string ftQueueItemID { get; set; }    public long ftQueueRow { get; set; }    public string cbTerminalID { get; set; }    public string cbReceiptReference { get; set; }    public string ftCashBoxIdentification { get; set; }    public string ftReceiptIdentification { get; set; }    public DateTime ftReceiptMoment { get; set; }    public string[] ftReceiptHeader { get; set; }    public ChargeItem[] ftChargeItems { get; set; }    public string[] ftChargeLines { get; set; }    public PayItem[] ftPayItems { get; set; }    public string[] ftPayLines { get; set; }    public SignaturItem[] ftSignatures { get; set; }    public string[] ftReceiptFooter { get; set; }    public long ftState { get; set; }    public string ftStateData { get; set; }  }}
*Code 2. Definition of class ReceiptResponse*

Charge Items Entry#

Charge items entries are used for receipt requests as well as for receipt responses.

The details of fields supported by this data structure are outlined in the table below. The ftChargeItemCase field is particularly important for the correct processing of the receipt. A reference table for the supported values can be found in the appendix.

Field NameData TypeDefault Value
Mandatory Field
DescriptionVersion
Positionlong0
optional
Line number or position number on the Receipt. Used to preserve the order of lines on the receipt.0-
QuantityDecimal1.0
mandatory
Amount or volume (number) of service(s) or items of the entry.0-
DescriptionString
Max 1k
empty-string
mandatory
Name, description of customary indication, or type of the service or item.0-
AmountDecimal0.0
mandatory
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.0-
VATRateDecimal0.0
mandatory
VAT rate as percentage.0-
ftChargeItemCaseInt640
mandatory
Type of service or item according to the refer-ence table in the appendix. It is used in order to determine the processing logic for the corresponding business transaction.0-
ftChargeItemCaseDataString
Max 64k
empty-string
optional
Additional data about the service, currently accepted only in JSON format.0-
VATAmountDecimal?0.0
optional
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.0-
AccountNumberString
Max 1k
empty-string
optional
Account number for transfer into bookkeeping.0-
CostCenterString
Max 1k
empty-string
optional
Indicator for transfer into cost accounting (type, center, and payer).0-
ProductGroupString
Max 1k
empty-string
optional
This value allows the customer the logical grouping of products.0-
ProductNumberString
Max 1k
empty-string
optional
Value used to identify the product.0-
ProductBarcodeString
Max 1k
empty-string
optional
Product’s barcode.0-
UnitString
Max 1k
empty-string
optional
Unit of measurement.0-
UnitQuantityDecimal?null
optional
Quantity of the service(s) of receipt entry, displayed in indicated units.0-
UnitPriceDecimal?null
optional
Gross price per indicated unit.0-
MomentDateTimenull
optional
Time of service (year, month, day, hour, minute, second). Must be provided in UTC, e.g. 2020-06-29T17:45:40.505Z.0-
*Table 5. Charge Items Entry (ftChargeItems)*

C# class ChargeItem:

namespace fiskaltrust.ifPOS.v0{  public class ChargeItem  {    public long Position { get; set; }    public decimal Quantity { get; set; }    public string Description { get; set; }    public decimal Amount { get; set; }    public decimal VATRate { get; set; }    public long ftChargeItemCase { get; set; }    public string ftChargeItemCaseData { get; set; }    public decimal? VATAmount { get; set; }    public string AccountNumber { get; set; }    public string CostCenter { get; set; }    public string ProductGroup { get; set; }    public string ProductNumber { get; set; }    public string ProductBarcode { get; set; }    public string Unit { get; set; }    public decimal? UnitQuantity { get; set; }    public decimal? UnitPrice { get; set; }    public DateTime? Moment { get; set; }  }}
*Code 3. Definition of class ChargeItem*

Pay Items Entry#

Payment entries are used for receipt requests as well as for receipt responses.

The ftPayItemCase field is particularly important for the correct processing of the receipt. This field can help to decide if the receipt has to be signed and the sum counter adjusted. A reference table for the supported values can be found in the appendix.

Field NameData TypeDefault Value
Mandatory Field
DescriptionVersion
Positionlong0
optional
Line number or position number on the receipt. Used to preserve the order of lines on the receipt.0-
QuantityDecimal1.0
mandatory
Number of payments. This value will be set to 1 in most of the cases. It can be greater than 1 e.g. when paying with multiple vouchers of the same value.0-
DescriptionString
Max 1k
empty-string
mandatory
Name or description of payment0-
AmountDecimal0.0
mandatory
Total amount of payment0-
ftPayItemCaseInt640
mandatory
Type of payment according to the reference table in the appendix. It is used in order to determine the processing logic.0-
ftPayItemCaseDataString
Max 64k
empty-string
optional
Additional data about the payment, currently accepted only in JSON format.0-
AccountNumberString
Max 1k
empty-string
optional
Account number for transfer into bookkeeping0-
CostCenterString
Max 1k
empty-string
optional
Indicator for transfer into cost accounting (type, center and payer)0-
MoneyGroupString
Max 1k
empty-string
optional
This value allows the logical grouping of payment types.0-
MoneyNumberString
Max 1k
empty-string
optional
This value identifies the payment type.0-
MomentDateTime?now
optional
Time of payment. Must be provided in UTC, e.g. 2020-06-29T17:45:40.505Z.0-
*Table 6. Pay Items Entry*

C# class PayItem:

namespace fiskaltrust.ifPOS.v0{  public class PayItem  {    public long Position { get; set; }    public decimal Quantity { get; set; }    public string Description { get; set; }    public decimal Amount { get; set; }    public long ftPayItemCase { get; set; }    public string ftPayItemCaseData { get; set; }    public string AccountNumber { get; set; }    public string CostCenter { get; set; }    public string MoneyGroup { get; set; }    public string MoneyNumber { get; set; }    public DateTime? Moment { get; set; }  }}
*Code 4. Definition of class PayItem*

Signature Entry#

The signature entry is only used for the receipt response.

The signature of the receipt must comply with the national law. The signature data returned in the response should be visualized on the receipt in the correct format, which is further described in the appendix section of this document. The signature entries can also be used to visualize hints and messages related to the fiskaltrust.SecurityMechanism.

A reference text regarding the operating state of the fiskaltrust.SecurityMechanism can be sent back depending on the operating mode. This is in particular the case for receipts with special functions.

Field NameData TypeDefault Value
Mandatory Field
DescriptionVersion
ftSignatureFormatInt640
mandatory
Format for displaying signature data according to the reference table in the appendix.0-
ftSignatureTypeInt640
mandatory
Type of signature according to the reference table in the appendix, e.g.: signature indicating a failure notification.0-
CaptionString
Max 1k
empty-string
optional
Heading, which has to be displayed as text above the signature data.0-
DataString
Max 64k
empty-string
mandatory
Signature content which has to be displayed in the specified format.
*Table 7. Signature Entry*

C# class SignatureItem:

namespace fiskaltrust.ifPOS.v0{  public class SignaturItem  {    public long ftSignatureFormat { get; set; }    public long ftSignatureType { get; set; }    public string Caption { get; set; }    public string Data { get; set; }  }}
*Code 5. Definition of class SignatureItem*