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",
"additionalFields": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"automaticVatCalculation": "noCalculation",
"allowedVatDeviation": 0.01,
"documentGuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"documentId": "S962-000001287",
"createDate": "2023-04-27T17:27:12.541Z",
"bookDate": "2023-04-27T17:27:12.541Z",
"accountingDate": "2023-04-27T17:27:12.541Z",
"processStartDate": "2023-04-27T17:27:12.541Z",
"documentNumber": "000001287",
"documentNumberSeries": "receipt",
"positionCount": 1,
"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.541Z",
"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"
},
"salesPerson": {
"id": "04",
"caption": "Cashier 04",
"firstName": "Sandra",
"lastName": "Hurry",
"taxNumber": "987654321"
},
"allocationGroups": [
"Tisch 127"
],
"partner": {
"id": "ABC1234567",
"caption": "Kunde",
"partnerType": "[0] = Customer",
"partnerClassification": "private customer",
"vatNumber": "n.a.",
"taxNumber": "n.a.",
"identificationType": "passport",
"partnerIdentification": "ABC1234567",
"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.541Z",
"servicePeriodEnd": "2023-04-27T17:27:12.541Z",
"positionCount": 0,
"taxPositions": [
{
"vatIdentification": 0,
"vatLabel": "string",
"vatPercent1": 0,
"vatAmount": 0,
"netAmount": 0,
"grossAmount": 0
}
],
"fiscalResponse": {
"fiscalCountry": "[1] = Austria",
"fiscalisationDocumentNumber": 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.541Z",
"requestCompletionTime": "2023-04-27T17:27:12.541Z",
"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.541Z",
"returnReasonType": "userMistake",
"returnReasonText": "string"
},
"cancellationPosition": true,
"type": "[0] = Item",
"additionalFields": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"createDate": "2023-04-27T17:27:12.541Z",
"externalIdentifier": [
"string"
],
"user": {
"id": "string",
"caption": "string",
"firstName": "string",
"lastName": "string",
"taxNumber": "string"
},
"salesPerson": {
"id": "string",
"caption": "string",
"firstName": "string",
"lastName": "string",
"taxNumber": "string"
},
"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.541Z",
"vatIdentification": 0,
"vatPercent": 0,
"taxValue": 0,
"externalIdentifier": [
"string"
],
"user": {
"id": "string",
"caption": "string",
"firstName": "string",
"lastName": "string",
"taxNumber": "string"
},
"salesPerson": {
"id": "string",
"caption": "string",
"firstName": "string",
"lastName": "string",
"taxNumber": "string"
},
"paymentTerminalReferenceId": "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
| Elementse | 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. |
|
| 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) |
|
| 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). | |
| positionCount | M* |
Number of positions contained in the document (all items, incl. item, text, booking, subTotal, total). Attention: mandatory in France.
|
|
| 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 | O | Designation of the document type. Serves for a better description or explanation. | |
| user | O/M* | (Cash register) user details. | |
| {...} | |||
| salesPerson | O/M* | Sales staff 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 | |
| dueDateDays | Number of days within which the invoice must be paid | ||
| discount | Cash discount (specified as a percentage) if the invoice is paid within a certain number of days (discountDueDays). | ||
| discountDueDays | Number of days within which a discount can be claimed. | ||
| latePaymentPenaltyRate | The percentage of the penalty if the bill is paid late. | ||
| servicePeriodStart | O | Start of the performance period (especially for invoices) | |
| servicePeriodEnd | O | End of the performance period (especially for invoices) | |
| positionCount | O/M* | Number of document positions (all PositionObjectTypes: item, booking, text, subTotal, total). See also Position Object. | |
| 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").
|
|
| vatIdentification |
ID Identification of the VAT rate of the VAT position. Can be retrieved using GET /api/v1/information/ client/{clientId}/getVatIdentification, specifying the VAT rate of the country. Rate of the respective country. |
||
| vatLabel | |||
| vatPercent1 | Tax rate in percent of this VAT item. Position (in this case VAT position 1) | ||
| vatAmount | VAT amount of the VAT position | ||
| netAmount | Net amount (excl. VAT) of the VAT position | ||
| grossAmount | Gross amount (incl. VAT) of the VAT position | ||
| fiscalResponse | M | Response of the fiscalisation service after sending createDocument and/or storeDocument. | |
| {...} | |||
| fiscalDocumentNumber | M |
Fiscal document number (assigned by the RetailForce system, or by the respective fiscalisation unit - e.g. TSE in Germany). Attention: please note that the fiscalResponse returns the fiscalDocumentNumber information in the fiscalisationDocumentNumber field. See also article: "Given Transaction not started".
|
|
| 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 the fiscalResponse returns the fiscalDocumentRevision information in the fiscalisationDocumentRevision field. See also article: "Given Transaction not started".
|
|
| 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) | |
| {...} | |||
| FiscalAdditionalFields | O | ||
Comments
0 comments
Please sign in to leave a comment.