Skip to main content

Data structures

This chapter expands on the descriptions of the country-specific Data Structures, covered in the Chapter "Data Structures" of the General Part, with information applicable to the German market.

Receipt Request

Single fields

Fields from the receipt request that need special handling for the German market are listed below:

Field nameData typeDefault Value Mandatory FieldDescriptionVersion
cbTerminalIDstring (50)MandatoryThe unique identification of the input station/cash register/terminal within a ftCashBoxID1.3
cbUserstring (50)MandatoryName (not ID) of the user who creates the receipt.1.3
cbReceiptReferencestring (50)MandatoryUsed to connect all requests referring to the same business action.1.3
ftPosSystemIdGUID / string (36)MandatoryThis field identifies and documents the type and software version of the POS-System sending the request. It is used to identify the used POS-System and add it to the DSFinV-K. 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.1.3
cbPreviousReceiptReferencestringOptionalPoints to cbReceiptReference of a previous request. Used to connect requests representing a business action. E.g. split, merge or reference a receipt to be voided.1.3

Examples of using cbReceiptReference and cbPreviousReceiptReference to connect requests representing a business action can be found in our Postman collection.

caution

If using cbPreviousReceiptReference, as per DSFinV-K it must have a maximum length of 50 characters. Exceeding this length will result in export errors (e.g., DATEV MeinFiskal).

Customer data cbCustomer

If you need to provide customer data in your request, you can send it in via the field cbCustomer by filling it JSON format with following fields:

Field nameData typeDefault Value Mandatory FieldDescriptionVersion
CustomerNamestring (50)OptionalName of beneficiary customer.
Send via cbCustomer in JSON format by adding the key value pair CustomerName e.g. "cbCustomer":"{"CustomerName":"Erika Musterfrau",...}"
1.3
CustomerIdstring (50)OptionalID of the beneficiary customer.
Send via cbCustomer in JSON format by adding the key value pair CustomerId e.g. "cbCustomer":"{"customerName":"Max Mustermann", "CustomerId":"PX9819822", ...}"
1.3
CustomerTypestring (50)OptionalType of the beneficiary customer (e.g. employee).
Send via cbCustomer in JSON format by adding the key value pair CustomerType e.g. "cbCustomer":"{..., "CustomerId":"PX9819822", "CustomerType":"Mitarbeiter", ...}"
1.3
CustomerStreetstring (60)OptionalStreet and house number of the beneficiary customer.
Send via cbCustomer in JSON format by adding the key value pair CustomerStreet e.g. "cbCustomer":"{..., "CustomerStreet":"Lindwurmstr. 98", ...}"
1.3
CustomerZipstring (10)OptionalZip of the beneficiary customer.
Send via cbCustomer in JSON format by adding the key value pair CustomerZip e.g. "cbCustomer":"{..., "CustomerZip":"80337", ...}"
1.3
CustomerCitystring (62)OptionalCity of the beneficiary customer.
Send via cbCustomer in JSON format by adding the key value pair CustomerCity e.g. "cbCustomer":"{..., "CustomerCity":"München", ...}"
1.3
CustomerCountryISO 3166 ALPHA-3 country codeOptionalCountry of the beneficiary customer.
Send via cbCustomer in JSON format by adding the key value pair CustomerCountry e.g. "cbCustomer":"{..., "CustomerCountry":"DEU", ...}"
1.3
CustomerVATIdstring(15)OptionalVAT-ID of the beneficiary customer.
Send via cbCustomer in JSON format by adding the key value pair CustomerVATId e.g. "cbCustomer":"{..., "CustomerVATId":"DE123456789", ...}"
1.3

Receipt case data ftReceiptCaseData

In the general description, the field ftReceiptCaseData is described as optional. However, for the German market, the content of this field is not always optional.

For some cases, it is needed to transmit data within the field ftReceiptCaseData, that is required later for the DSFinV-K export. The following table describes when and how you have to fill them.

Field nameData typeDefault Value Mandatory FieldDescriptionVersion
UserIdstringoptionalSend via ftReceiptCaseData in JSON format. To send, please add the key value pair UserId e.g. "ftReceiptCaseData":"{ ..., "UserId": "U192", ... }". If not sent, the fiskaltrust.Middleware will automatically generate a User-ID (hash) deducted from cbUser1.3
ReceiptNotestringoptionalAdditional information on the receipt header. Can be sent via ftReceiptCaseData in JSON format. To send, add the key value pair ReceiptNote e.g. "ftReceiptCaseData":"{ ..., "ReceiptNote":"123, ich bin dabei!", ... }"1.3
ReceiptNamestringMandatory if your request mapps to the DSFinV-K BON_TYPE "AVSonstige" (see ftReceiptCase), otherwise optionalCan be sent via ftReceiptCaseData in JSON format. To send, add the key value pair ReceiptName e.g. "ftReceiptCaseData":"{ ..., "ReceiptName":"Sonstige Sonderwurst", ... }"1.3

If you need to provide a reference to another system or another cashpoint, you can add it via the field ftReceiptCaseData by providing its data as shown below:

Field nameData typeDefault Value Mandatory FieldDescriptionVersion
RefType"ExterneRechnung" or "ExternerLieferschein" or "Transaktion" or "ExterneSonstige"mandatorySend via ftReceiptCaseData in JSON format. Add the key value pair RefType e.g. "ftReceiptCaseData":"{ ..., "RefType":"Transaktion", ... }". The value "Transaktion" maps to an internal reference of another cashpoint, all other values map to external references.1.3
RefNamestringIf the external reference you want to add is of type (RefType) "ExterneSonstige", you must provide data for the field RefName.Please send it via ftReceiptCaseData in JSON format by adding the key value pair RefName e.g. "ftReceiptCaseData":"{ ..., "RefName":"Name der Referenz", ... }".1.3
RefMomentstringIf the reference you want to add is of type (RefType) "Transaktion", you must provide data for the field RefMoment.Please send it via ftReceiptCaseData in JSON format by adding the key value pair RefMoment e.g. "ftReceiptCaseData":"{ ..., "RefMoment":"2020-01-03T17:00:01", ... }".1.3
RefCashBoxIdentificationstringIf the reference you want to add is of type (RefType) "Transaktion", you must provide data for the field RefCashBoxIdentification.It should contain the value of ´ftCashBoxIdentification´ from the referenced cashpoint. Please send it via ftReceiptCaseData in JSON format by adding the key value pair RefCashBoxIdentification e.g. "ftReceiptCaseData":"{ ..., "RefCashBoxIdentification":"AHHAH1919919", ... }".1.3
RefClosingNrintegerIf the reference you want to add is of type (RefType) "Transaktion", you must provide data for the field RefClosingNr.It should provide the referenced cashpoint daily closing number of the referenced object. Please send it via ftReceiptCaseData in JSON format by adding the key value pair RefClosingNr e.g. "ftReceiptCaseData":"{ ..., "RefClosingNr":1091029, ... }". Starting from version 1.3.6, the closing numbers to reference can be obtained from the ftStateData field of daily closing receipts' responses (via the DailyClosingNumber JSON element).1.3
RefReceiptIdstringIf the reference you want to add is of type (RefType) "Transaktion", you must provide data for the field RefReceiptId.It should contain the value of ´ftReceiptIdentification´ of the referenced object. Please send it via ftReceiptCaseData in JSON format by adding the key value pair RefReceiptId e.g. "ftReceiptCaseData":"{ ..., "RefReceiptId":"UAUUA1112#20200211-112430", ... }".1.3

Charge Items Entry

In the general description, the field ftChargeItemCaseData is described as optional. However, for the German market, the content of this field is not always optional.

For some cases, it is needed to transmit data within the field ftChargeItemCaseData, that is required later for the DSFinV-K export. The following table describes how and when these need to be filled.

Field nameData typeDefault Value Mandatory FieldDescriptionVersion
VoucherNrstringmandatory if applicableSend via ftChargeItemCaseData in JSON format if the ChargeItem represents the voucher. To send, please add the key value pair VoucherNr e.g. "ftChargeItemCaseData":"{ ..., "VoucherNr":"UAUA91829182HH", ... }".1.3
AgencyIdintegermandatory if applicableMandatory if agency business (DE: Agenturgeschäft). Send via ftChargeItemCaseData (if a ChargeItem represents the voucher) or ftPayItemCaseData (if a payitem represents the voucher). To send, use the key value pair AgencyId e.g. "ftChargeItemCaseData":"{ ..., "AgencyId": "73c94a68-c329-4d82-a8e4-d48903791922", ... }" (the ID can be taken from the Portal's Agency management page).1.3
ProductGroupIdstringoptionalSend via ftChargeItemCaseData in JSON format. To send, please add the key value pair ProductGroupId e.g. "ftChargeItemCaseData":"{ ..., "ProductGroupId":192, ... }". If not sent, the fiskaltrust.Middleware will automatically generate an ID (CRC32 hash) deducted from ftChargeItem.ProductGroup1.3

The following table highlights fields of the charge item that need special handling for the German market.

Field nameData typeDefault Value Mandatory FieldDescriptionVersion
ProductNumberstring (50)mandatory if availableArticle number1.3
ProductBarcodestring (50)mandatory if applicableUse to send the Global Trade Item Number (GTIN) if the charge item represents an article.1.3
ProductGroupstring (50)mandatory if availableName of the product group.1.3
Quantitydecimal (3)mandatory if availableQuantity Payload and Export Amount Calculation1.3
Amountdecimal (5)0.0
mandatory
Gross total price of service(s) see general part and Payload and Export Amount Calculation1.3
UnitQuantitydecimal (3)mandatory if availableQuantity of the product of a single receipt entry (ChargeItem), displayed in indicated units, e.g. a big beer, Unit: "liter" UnitQuantity: 0.51.3
Unitstringmandatory if availableUnit of measurement, e.g. kg, litres or pieces1.3
UnitPricedecimal (5)mandatory if availablePrice per unit incl. VAT1.3
VATAmountdecimal (5)mandatory for special casesIn some special cases of taxation (e.g. car spare part in the car repair shop), the VAT is not a percentage of the net-price (NETTO) or the gross-price. For these cases, the field VATAmount is mandatory and a ftChargeItemCase that maps to DSFinV-K UST_SCHLUESSEL 7 should be used. The value of the field VATRate should be set to 0.0.1.3

Payload and Export Amount Calculation

To get a positive Amount: Amount and Quantity have to be positive. This is relevant e.g. for credit notes including a discount, which must be positive.

Calculated AmountReceipt AmountReceipt Quantity
+++
--+
-+-
---

Pay Items Entry

In the general description, the field ftPayItemCaseData is described as optional. However, for the German market, the content of this field is not always optional.

For some cases, it is needed to transmit data within the field ftPayItemCaseData, that is required later for the DSFinV-K export. The following table describes how and when these need to be filled.

Field nameData typeDefault Value Mandatory FieldDescriptionVersion
CurrencyCodestring (3)mandatory if foreign currency usedMandatory if a foreign currency was used for the payment. To send, add the key value pair CurrencyCode e.g. "ftPayItemCaseData":"{ ..., "CurrencyCode":"USD", ... }". Only ISO 4217 currency codes are allowed.1.3
ForeignCurrencyAmountdecimal (2)mandatory if foreign currency usedMandatory if a foreign currency was used for the payment. To send, add the key value pair ForeignCurrencyAmount e.g. "ftPayItemCaseData":"{ ..., "ForeignCurrencyAmount":23.00, ... }".1.3
BaseCurrencyAmountdecimal (2)mandatory if foreign currency usedMandatory if a foreign currency was used for the payment. Represents the converted value of the payed foreign currency amount into the base currency (EUR). To send, add the key value pair BaseCurrencyAmount e.g. "ftPayItemCaseData":"{ ..., "BaseCurrencyAmount":20.00, ... }".1.3
VoucherNrstringmandatory if applicableSend via ftPayItemCaseData in JSON format if the pay item represents the voucher. To send, please add the key value pair VoucherNr e.g. "ftPayItemCaseData":"{ ..., "VoucherNr":"UAUA91829182HH", ... }".1.3
MoneyGroupIdstringoptionalSend via ftPayItemCaseData in JSON format. To send, please add the key value pair MoneyGroupId e.g. "ftPayItemCaseData":"{ ..., "MoneyGroupId":192, ... }". If not sent, the fiskaltrust.Middleware will automatically generate an ID (CRC32 hash) deducted from ftPayItem.MoneyGroup1.3
AgencyIdintegermandatory if applicableMandatory if agency business (DE: Agenturgeschäft). Send via ftPayItemCaseData in JSON format. To send, please add the key value pair AgencyId e.g. "ftPayItemCaseData":"{ ..., "AgencyId": "73c94a68-c329-4d82-a8e4-d48903791922", ... }" (the ID can be taken from the Portal's Agency management page). Should only be used in cases where PayItems will be transformed to GV_TYPes during DSFinV-K generation - otherwise, please use ftChargeItemCaseData.1.3