This article describes the header object ("payments"), respectively the elements in the header within the document object.
A complete description of the RetailForce DOM (Document Object Model), as well as a description of the individual elements, can be found in the downloads area of the RetailForce website (Object model documentation.pdf) in the respective version directory.
Header object
The entire document schema, including sample data, is shown below. The sub-objects (positions, payments,...) are described in more detail in the linked articles (links also within the schema).
{
"uniqueClientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"applicationVersion": "6.2.5",
"fiscalModuleVersion": "1.8.8",
"fiscalCountryModuleVersion": "1.0.5",
"softwareName": "GreatesPOS",
"retailForceReceiptId": "W3D9C2Q1",
"additionalFields": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"automaticVatCalculation": "noCalculation",
"allowedVatDeviation": 0.01,
"terminalSlaveId": "Pad05",
"footerGraphicIndex": "5",
"documentGuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"documentId": "S962-000001287",
"createDate": "2023-04-27T17:27:12.541+01:00",
"bookDate": "2023-04-27T17:27:12.541+01:00",
"accountingDate": "2023-04-27T17:27:12.541+01:00",
"processStartDate": "2023-04-27T17:27:12.541+01:00",
"documentNumber": "000001287",
"documentNumberSeries": "receipt",
"cancellationDocument": true,
"documentReference": {
"referenceType": "[0] = Cancellation",
"storeNumber": "Restaurant 03",
"terminalNumber": "002",
"documentType": "[0] = Receipt",
"documentNumber": "000000895",
"documentNumberSeries": "receipt",
"fiscalDocumentNumber": 0,
"documentGuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"documentId": "S962-000000895",
"documentBookDate": "2023-04-27T17:27:12.541+01:00",
"returnReasonType": "userMistake",
"returnReasonText": "error happened"
},
"isTraining": true,
"documentType": "[0] = Receipt",
"documentTypeCaption": "Sales receipt",
"user": {
"id": "03",
"caption": "Service 03",
"firstName": "Jane",
"lastName": "Doe",
"taxNumber": "123456789",
"dateOfEntry": "2022-10-01T08:00:00+01:00"
},
"salesPerson": {
"id": "04",
"caption": "Cashier 04",
"firstName": "Sandra",
"lastName": "Hurry",
"taxNumber": "987654321",
"dateOfEntry": "2022-10-01T08:00:00+01:00"
},
"allocationGroups": [
"Tisch 127"
],
"partner": {
"id": "ABC1234567",
"caption": "Kunde",
"isBusiness": false,
"partnerType": "[0] = Customer",
"partnerClassification": "private customer",
"vatNumber": "n.a.",
"taxNumber": "n.a.",
"identificationType": "passport",
"partnerIdentification": "ABC1234567",
"additionalIdentifications": {
"lotteryId": "1234567",
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"street": "Pattern Street",
"streetNumber": "186",
"postalCode": "1010",
"city": "Vienna",
"community": "n.a.",
"countryCode": "AT"
},
"notes": "Anmerkungen",
"customerCount": 1,
"paymentTerms": {
"dueDateDays": 0,
"discount": 0,
"discountDueDays": 0,
"latePaymentPenaltyRate": 0
},
"servicePeriodStart": "2023-04-27T17:27:12.541+01:00",
"servicePeriodEnd": "2023-04-27T17:27:12.541+01:00",
"positionCount": 1,
"documentIssueType": "paper",
"coupon": {
"header": [
{
"text": "string",
"barcodeType": "qrCode",
"barcode": "https://retailforce.cloud"
}
],
"grafic": "string",
"footer": [
{
"text": "string",
"barcodeType": "qrCode",
"barcode": "https://retailforce.cloud"
}
]
},
"serviceType": "string",
"isEcommerceTransaction": true,
"taxPositions": [
{
"vatIdentification": 0,
"vatLabel": "string",
"vatPercent1": 0,
"vatAmount": 0,
"netAmount": 0,
"grossAmount": 0
}
],
"fiscalResponse": {
"fiscalCountry": "[1] = Austria",
"fiscalDocumentNumber": "0",
"taxPositions": [
{
"vatIdentification": 0,
"vatLabel": "string",
"vatPercent1": 0,
"vatAmount": 0,
"netAmount": 0,
"grossAmount": 0
}
],
"fiscalDocumentStartTime": 0,
"processStartTime": 0,
"errorDescription": "string",
"cashRegisterId": "string",
"signature": "string",
"userMessage": "string",
"printMessage": "string",
"requestTime": "2023-04-27T17:27:12.541+01:00",
"requestCompletionTime": "2023-04-27T17:27:12.541+01:00",
"retailForceReceiptId": "0p4j0001", /// nur bei createDocument
"AdditionalFields": {}
},
"fiscalDocumentNumber": 0,
"fiscalDocumentRevision":0,
"FiscalDocumentStartTime": 0,
"positions": [
{
"positionNumber": 0,
"positionReference": {
"positionNumber": 0,
"referenceType": "[0] = Cancellation",
"storeNumber": "string",
"terminalNumber": "string",
"documentType": "[0] = Receipt",
"documentNumber": "string",
"documentNumberSeries": "string",
"fiscalDocumentNumber": 0,
"documentGuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"documentId": "string",
"documentBookDate": "2023-04-27T17:27:12.541+01:00",
"returnReasonType": "userMistake",
"returnReasonText": "string"
},
"cancellationPosition": true,
"type": "[0] = Item",
"itemDateOfEntry": "2022-10-01T08:00:00+01:00",
"additionalFields": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"createDate": "2023-04-27T17:27:12.541+01:00",
"externalIdentifier": [
"string"
],
"user": {
"id": "string",
"caption": "string",
"firstName": "string",
"lastName": "string",
"taxNumber": "string",
"dateOfEntry": "2022-10-01T08:00:00+01:00"
},
"salesPerson": {
"id": "string",
"caption": "string",
"firstName": "string",
"lastName": "string",
"taxNumber": "string",
"dateOfEntry": "2022-10-01T08:00:00+01:00"
},
"FiscalAdditionalFields": {}
}
],
"payments": [
{
"amount": 0,
"currencyIsoCode": "string",
"caption": "string",
"uniqueReadablePaymentIdentifier": "string",
"foreignAmount": 0,
"foreignAmountExchangeRate": 0,
"additionalFields": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"paymentType": "cash",
"createDate": "2023-04-27T17:27:12.541+01:00",
"vatIdentification": 0,
"vatPercent": 0,
"taxValue": 0,
"externalIdentifier": [
"string"
],
"user": {
"id": "string",
"caption": "string",
"firstName": "string",
"lastName": "string",
"taxNumber": "string",
"dateOfEntry": "2022-10-01T08:00:00+01:00"
},
"salesPerson": {
"id": "string",
"caption": "string",
"firstName": "string",
"lastName": "string",
"taxNumber": "string",
"dateOfEntry": "2022-10-01T08:00:00+01:00"
},
"paymentTerminalReferenceId": "string",
"cardData": {
"receiptCopyCount": 0,
"receipt": [
"string"
],
"cardNumberMasked": "string",
"identificationToken": "string",
"merchantCopyCount": 0,
"merchantReceipt": [
"string"
]
}
}
],
"additionalHeader": [
"string"
],
"additionalFooter": [
"string"
],
"FiscalAdditionalFields": {}
}
The header object contains the following information.
Information in "Type" column:
- M ... mandatory / requird
- M* ... mandatory / requird in certain countries or under certain conditions
- R ... recommended
- O... optional
| Elements | Type | Description | |
| uniqueClientId | M | Unique ID of the client, corresponds to the terminal ID in the RetailForce Cloud (returned / assigned via PUT /api/v1/management/clients/byCloud during commissioning). | |
| applicationVersion | R/M* |
Version of the cash register software.
Attention: Please note that in some countries (France) the version number is fixed as part of the certification. If the version number is incorrect (does not correspond to the certified number), the document cannot be closed (=error). Please also note: Certified version.
|
|
| fiscalModuleVersion | O/M* |
Version of the fiscal module (Trusted Fiscal Module) that was used to generate the respective document. Is set automatically by the middleware if not transmitted by the software. |
|
| fiscalCountryModuleVersion | O/M* |
Version of the country module (Trusted Fiscal Country Module) that was used to generate the respective document. Is automatically set by the middleware if not transmitted by the software. |
|
| softwareName | O/M* |
Name of the POS software with which the respective document was generated. Is automatically set by the middleware if not transmitted by the software. |
|
| retailForceReceiptId | O |
Globally unique document number (consisting of terminalId and document number sequence number). Can be created when creating a process (with createDocument). |
|
| additionalFields | O |
|
|
| additionalProp1-x | O |
|
|
| automaticVatCalculation | O |
This element triggers the automatic calculation of various sum fields at item level. 0 noCalculation - no automatic calculation takes place. 1 netValueCalculation - automatic calculation of net and VAT amount. At least gross amount and VAT percentage/identifier must be specified. 2 grossValueCalculation - Automatic calculation of gross and tax amount. At least net amount and VAT percentage/identifier must be specified. |
|
| allowedVatDeviation | O |
Can be used to compensate for rounding problems when calculating VAT. Please use with caution! If set to a high value, the VAT calculation check will be disabled! Example: "allowedVatDeviation": 0.05, allows 5 cent deviation between net value + tax value = gross value(+-0.05) |
|
| terminalSlaveId | O | Specification of the ID of an input terminal. | |
| footerGraphicIndex | O |
A predefined graphic element is placed in the footer of a document via footerGraphicIndex.
Country details:
|
|
| documentGuid | M | Unique identifier of the document by means of UUID / GUID. Also used as a link for digital receipts. | |
| documentId | M | Unique, consecutive number of the document (receipt) within the branch / subsidiary / restaurant (across cash registers), assigned by the cash register system (max. 40 characters). | |
| createDate | M | Time of document recording | |
| bookDate | M | Time of booking of document | |
| accountingDate | O | Possible booking date for this document in the accounting department | |
| processStartDate | R/M* | Creation time of the first document within the entire process (e.g. Germany: Creation time of the first customer order in connection with the present payment document - see also "Characteristics in the catering industry") | |
| documentNumber | R | unique, consecutive number of the document (="receipt number"), assigned by the POS system. | |
| documentNumberSeries | O/M* |
Designation of the number range of the document number (documentNumber).
Country details:
|
|
| cancellationDocument | M |
Flag whether the present document is used to cancel another (previously issued) document. true - Cancellation document false - Not a cancellation document |
|
| documentReference | O/M* | is used to reference another document. | |
| {...} |
|
||
| isTraining | O/M* | Flag to mark training / demo documents (generated in training / demo mode of the cash register). | |
| documentType | M | Specification of the document type | |
| documentTypeCaption | M* |
Designation of the document type. Serves mainly for a better description or explanation.
Country details:
|
|
| user | O/M* |
(Cash register) user details.
Country details:
|
|
| {...} | |||
| salesPerson | O/M* |
Sales staff details.
Country details:
|
|
| {...} | |||
| allocationGroups [] | O/M* |
Used to assign receipts to specific items (e.g. tables in the catering industry). Please also note: Long term order process. |
|
| partner | O | Information on the respective (business) partner of the document issuing company. | |
| {...} | |||
| notes | O | Recording of additional notes | |
| customerCount | O/M* | Number of customers concerning this document (e.g. in the catering industry, the number of guests at the cash desk/table). | |
| paymentTerms | O | Terms of payment / payment conditions | |
| {...} | |||
| servicePeriodStart | O | Start of the performance period (especially for invoices) | |
| servicePeriodEnd | O | End of the performance period (especially for invoices) | |
| positionCount | M* |
Number of positions contained in the document (all items, incl. item, text, booking, subTotal, total). See also Position Object.
Country details:
|
|
| documentIssueType | O/M* |
Defines how the document was issued.
Country details:
|
|
| coupon | O |
Possibility to print additional coupons on the receipt. |
|
| {...} |
|
||
| serviceType | O/M* |
Indication of the type of service in the catering trade (table service, counter service).
Country details:
|
|
| isEcommerceTransaction | O/M* |
Indication of whether this is an e-commerce transaction (true / false).
Country details:
|
|
| taxPositions | R |
Indication of all VAT positions of the document. Either all or none of the VAT positions must be specified. To get the tax positions from the document (if this property has not been set), use GetTaxPositions(Document, Boolean).
Note Austria: we recommend using this array to transmit the tax positions of a document to avoid rounding problems within the data collection protocol ("DEP7").
|
|
| {...} |
|
||
| fiscalResponse | - |
Response of the fiscalisation service after sending createDocument and/or storeDocument. We recommend saving the fiscalResponse content in the cash register database.
Note: certain elements of the fiscalResponse object, after calling the createDocument function, must be included in the JSON document (which is to be sent to storeDocument). Please do NOT include the entire fiscalResponse object!
|
|
| {...} | |||
| fiscalDocumentNumber | M* |
Fiscal document number (assigned by the RetailForce system, or by the respective fiscalisation unit - e.g. TSE in Germany).
Attention: that in systems up to v1.7.7 fiscalDocumentNumber was returned in the fiscalisationDocumentNumber field of the fiscalResponse object. See also article: "Given Transaction not started". As of v1.7.7, an additional field fiscalDocumentNumber (string) has been introduced in the fiscalResponse object.
|
|
| fiscalDocumentRevision | O/M* |
Revision number of the fiscal document (assigned by the RetailForce system, or by the respective fiscal unit - e.g. TSE in Germany).
Attention: please note that in systems up to v1.7.7 the fiscalDocumentRevision was returned in the fiscalisationDocumentRevision field in the fiscalResponse header. See also article: "Given Transaction not started". As of v1.7.7, the property within the fiscalResponse object has been renamed fiscalDocumentRevision and is now only returned in the additionalFields array of the fiscalResponse-Germany.
|
|
| FiscalDocumentStartTime | M* | Time of creation of the fiscal document (assigned by the RetailForce system, or by the respective fiscal unit - e.g. TSE in Germany). | |
| positions | M | Details of the respective document / document position (content depends on the type of document and the position - documentType, positionType) | |
| {...} | |||
| payments | O/M* | Payment details (use depending on the type of document - documentType) | |
| {...} | |||
| additionalHeader | O | ||
| additionalFooter | O | ||
| FiscalAdditionalFields | O | ||
Comments
0 comments
Please sign in to leave a comment.