This article covers the Header object ("payments"), or 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 section of the RetailForce website (Object model documentation.pdf) in the respective version directory.
Header Object
{
"uniqueClientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"applicationVersion": "6.2.5",
"applicationVersionId": "string",
"applicationVersionPrevious": "string",
"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",
"cashRegisterSerialNumber": "CR123456789",
"footerGraphicIndex": 5,
"auditLogEntryType": "other",
"amount": 0,
"identifier": "string",
"documentGuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"documentId": "S962-000001287",
"createDate": "2023-04-27T17:27:12+01:00",
"bookDate": "2023-04-27T17:27:12+01:00",
"accountingDate": "2023-04-27T17:27:12+01:00",
"processStartDate": "2023-04-27T17:27:12+01:00",
"documentNumber": "000001287",
"documentNumberSeries": "Kassenbelege",
"cancellationDocument": false,
"failedToPay": false,
"documentReference": {
"referenceType": "[0] = Cancellation",
"storeNumber": "Restaurant 03",
"terminalNumber": "002",
"documentType": "[0] = Receipt",
"documentNumber": "000000895",
"documentNumberSeries": "Kassenbelege",
"fiscalDocumentNumber": 0,
"documentGuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"documentId": "S962-000000895",
"documentBookDate": "2023-04-27T17:27:12+01:00",
"returnReasonType": "userMistake",
"returnReasonText": "Fehler passiert"
},
"isTraining": true,
"testCaseNumber": "string",
"documentType": "[0] = Receipt",
"documentTypeCaption": "Verkaufsbeleg",
"user": {
"id": "03",
"caption": "Bedienung 03",
"firstName": "Franz",
"lastName": "Österreicher",
"taxNumber": "123456789",
"dateOfEntry": "2022-10-01T08:00:00+01:00"
},
"salesPerson": {
"id": "04",
"caption": "Kassier 04",
"firstName": "Sandra",
"lastName": "Hurtig",
"taxNumber": "987654321",
"dateOfEntry": "2022-10-01T08:00:00+01:00"
},
"allocationGroups": [
"Tisch 127"
],
"partner": {
"id": "ABC1234567",
"caption": "Kunde",
"isBusiness": false,
"partnerType": "[0] = Customer",
"partnerClassification": "Privatkunde",
"vatNumber": "n.a.",
"taxNumber": "n.a.",
"identificationType": "passport",
"partnerIdentification": "ABC1234567",
"addressType": "BillingAddress",
"additionalIdentifications": {
"lotteryId": "1234567",
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"street": "Musterstraße",
"streetNumber": "186",
"postalCode": "1010",
"city": "Wien",
"community": "n.a.",
"countryCode": "AT"
},
"notes": "Anmerkungen",
"customerCount": 1,
"paymentTerms": {
"dueDateDays": 0,
"discount": 0,
"discountDueDays": 0,
"latePaymentPenaltyRate": 0
},
"servicePeriodStart": "2023-04-27T17:27:12+01:00",
"servicePeriodEnd": "2023-04-27T17:27:12+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,
"vatPercent2": 0,
"vatAmount": 0,
"vatAmount2": 0,
"netAmount": 0,
"grossAmount": 0
}
],
"fiscalResponse": {
"fiscalCountry": "[1] = Austria",
"certificationType": "string",
"fiscalisationType": "string",
"supportedPlatformTypes": "string",
"overpaymentNotAllowed": "boolean",
"documentTypeBusinessTransactionTypeSupport": "string",
"fiscalDocumentNumber": "0",
"taxPositions": [
{
"vatIdentification": 0,
"vatLabel": "string",
"vatPercent1": 0,
"vatPercent2": 0,
"vatAmount": 0,
"vatAmount2": 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+01:00",
"requestCompletionTime": "2023-04-27T17:27:12+01:00",
"qrCode": "string",
"printingFields": {},
"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+01:00",
"returnReasonType": "userMistake",
"returnReasonText": "string"
},
"cancellationPosition": true,
"deletedPosition": false,
"type": "[0] = Item",
"itemCaption": "Sample Item",
"itemId": "ITEM-001",
"itemType": "[0] = Article",
"quantity": 1.0,
"quantityUnit": { "id": "Stk" },
"businessTransactionType": "[0] = Revenue",
"netValue": 10.0,
"grossValue": 12.0,
"taxValue": 2.0,
"ItemDateOfEntry": "2021-08-08T12:00:00+01:00",
"additionalFields": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"createDate": "2023-04-27T17:27:12+01:00",
"externalIdentifier": [
"string"
],
"user": {
"id": "string",
"caption": "string",
"firstName": "string",
"lastName": "string",
"taxNumber": "string",
"dateOfEntry": "2021-08-08T12:00:00+01:00"
},
"salesPerson": {
"id": "string",
"caption": "string",
"firstName": "string",
"lastName": "string",
"taxNumber": "string",
"dateOfEntry": "2021-08-08T12:00:00+01:00"
},
"FiscalAdditionalFields": {}
}
],
"payments": [
{
"amount": 12.0,
"currencyIsoCode": "EUR",
"caption": "string",
"uniqueReadablePaymentIdentifier": "string",
"foreignAmount": 0,
"foreignAmountExchangeRate": 0,
"additionalFields": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"paymentType": "creditCard",
"createDate": "2023-04-27T17:27:12+01:00",
"vatIdentification": 0,
"vatPercent": 0,
"taxValue": 0,
"externalIdentifier": [
"string"
],
"user": {
"id": "string",
"caption": "string",
"firstName": "string",
"lastName": "string",
"taxNumber": "string",
"dateOfEntry": "2021-08-08T12:00:00+01:00"
},
"salesPerson": {
"id": "string",
"caption": "string",
"firstName": "string",
"lastName": "string",
"taxNumber": "string",
"dateOfEntry": "2021-08-08T12:00:00+01:00"
},
"paymentTerminalReferenceId": "string",
"cardData": {
"receiptCopyCount": 0,
"receipt": [
"string"
],
"cardNumberMasked": "string",
"identificationToken": "string",
"merchantCopyCount": 0,
"merchantReceipt": [
"string"
],
"cardType": "VISA",
"authorizationCode": "AUTH123",
"terminalId": "TERM-A1",
"merchantId": "MERCH-B2",
"transactionId": "TRANS-C3",
"providerSignature": "string",
"providerTransactionId": "string",
"providerSignatureMessage": "string",
"transactionDate": "2023-04-27T17:27:12+01:00",
"transactionNumber": "string"
}
}
],
"additionalHeader": [
"string"
],
"additionalFooter": [
"string"
],
"FiscalAdditionalFields": {}
}The Header object contains the following information.
Information in the "Type" column:
- M ... required ("mandatory")
- M* ... required in certain countries, or under certain conditions
- R ... recommended ("recommended")
- O ... optional
| Element | Type | Description | |
| uniqueClientId | M | Unique ID of the client, corresponds to the terminal ID in the RetailForce Cloud (is returned/assigned during commissioning via PUT /api/v1/management/clients/byCloud). | |
| 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 process. If an incorrect version number is specified (not corresponding to the certified number), it is not possible to complete the document (=error). Please also refer to: Certified Version.
Country details:
|
|
| applicationVersionId | R/M* |
ID of the cash register software version. Country details:
|
|
| applicationVersionPrevious | R/M* |
ID of the previous cash register software version. Country details:
|
|
| fiscalModuleVersion | O/M* | Version of the Fiscal Module (Trusted Fiscal Module) used to generate the respective document. Automatically set by the middleware if not transmitted by the software. | |
| fiscalCountryModuleVersion | O/M* | Version of the Country Module (Trusted Fiscal Country Module) used to generate the respective document. Automatically set by the middleware if not transmitted by the software. | |
| FiscalisationType | O | ||
| signature | O | Signature | |
| fiscalPrinter | Fiscal Printer | ||
| online | Online | ||
| signatureWithOnline | Signature with Online Connection | ||
| noFiscalisation | No Fiscalisation | ||
| FiscalisationTypeItaly | O | ||
| printer | O | Registratore Telematico | |
| retailForceReceiptId | O | Globally unique receipt number (consisting of terminalId and receipt sequential number). Can be created when creating a transaction (with createDocument). | |
| additionalFields | O | ||
| additionalProp1-x | O | ||
| automaticVatCalculation | O |
This element triggers the automatic calculation of various sum fields at the position level. 0 noCalculation - no automatic calculation takes place 1 netValueCalculation - automatic calculation of net amount and VAT amount. At least gross amount and VAT percentage/ identification must be specified. 2 grossValueCalculation - Automatic calculation of gross and tax amount. At least net value and VAT percentage/ identification must be specified. |
|
| allowedVatDeviation | O |
Can be used to compensate for rounding issues in VAT calculation. Please use with caution! If set to a high value, VAT calculation checking is 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. | |
| cashRegisterSerialNumber | O |
Serial number of the cash register device. This field identifies the specific physical cash register hardware used to process the transaction. | |
| footerGraphicIndex | O |
Via footerGraphicIndex a predefined graphic element is placed in the footer of a document. Country details:
|
|
| auditLogEntryType | Specifies the type of audit log entry when the document itself is an audit log entry. | ||
| amount | An amount associated with the document header (e.g. for audit log purposes). | ||
| identifier | A general identification field (e.g. for audit log purposes). | ||
| documentGuid | M | Unique identifier of the document using UUID / GUID. Also used as a link for digital receipts. | |
| documentId | M | Unique, sequential number of the document (receipt) within the branch / subsidiary / restaurant (across all registers), assigned by the cash register system (max. 40 characters). | |
| createDate | M | Time of document creation | |
| bookDate | M | Booking time | |
| accountingDate | O | Possible booking date for this document in accounting | |
| processStartDate | R/M* | Creation time of the first receipt within the entire process (e.g. Germany: Creation time of the first customer order in connection with the present payment receipt - see also "Special Features Gastronomy") | |
| documentNumber | R/M* | Unique, sequential number of the document (="receipt number"), assigned by the cash register system. | |
| documentNumberSeries | O/M* |
Name of the number series of the receipt number (documentNumber). Country details:
|
|
| cancellationDocument | M |
Flag whether the present document is used to cancel another (previously issued) document true - Cancellation document false - No cancellation document |
|
| failedToPay | O |
A Boolean flag (true/false) that indicates whether the payment for the document failed. |
|
| documentReference | O/M* | Used to reference another document. | |
| {...} | |||
| isTraining | O/M* | Flag to mark training / demo documents (Generated in training / demo mode of the cash register). | |
| testCaseNumber | O/M* |
Field for specifying a test case number for certification purposes. Country details:
|
|
| documentType | O | Specification of the document type | |
| documentTypeCaption | M* |
Description of the document type. Serves essentially for better description or clarification. Country details:
|
|
| user | O/M* |
Information about the (cash register) user. Country details:
|
|
| {...} | |||
| salesPerson | O/M* |
Information about the sales personnel. Country details:
|
|
| {...} | |||
| allocationGroups [] | O/M* |
Used to assign receipts to specific things (e.g. tables in gastronomy). Also refer to: Long-lasting Order Process Gastronomy. Country details:
|
|
| partner | O/M* |
Information about the respective (business) partners of the document-issuing company. Country details:
|
|
| addressType | (In the partner object) New optional field for specifying the address type (e.g. billing address). |
||
| {...} | |||
| notes | O | Recording additional notes | |
| customerCount | O/M* |
Customer count regarding this document (e.g. in gastronomy, the number of guests at the register/table) Country details:
|
|
| paymentTerms | O | Payment terms / payment conditions | |
| {...} | |||
| servicePeriodStart | O |
Start of the service period (especially for invoices) Country details:
|
|
| servicePeriodEnd | O |
End of the service period (especially for invoices) Country details:
|
|
| positionCount | O/M* |
Number of positions contained in the receipt (all positions, including item, text, booking, subTotal, total) See also Position Object. Country details:
|
|
| documentIssueType | O/M* |
Defines the type of receipt issuance.
Country details:
|
|
| coupon | O | Possibility to print additional coupons and other elements on the receipt. | |
| {...} | |||
| serviceType | O/M* |
Specification of the service type in gastronomy (table, counter service). Possible values (CamelCase to be observed!)
Country details:
|
|
| isEcommerceTransaction | O/M* |
Indication whether it is an e-commerce transaction (true / false). Country details:
|
|
| taxPositions | R |
Specification of all VAT positions of the document. Either all or no VAT positions must be specified. To get the tax positions from the document (when this property was not set), use GetTaxPositions(Document, Boolean).
Note Austria: We recommend using this array to transmit the tax positions of a receipt to avoid rounding problems within the data recording protocol ("DEP7").
|
|
| {...} | |||
| fiscalResponse | - |
Response of the fiscalisation service after transmission createDocument and storeDocument. We recommend storing the content fiscalResponse in the cash register database.
Note: certain elements of the fiscalResponse object, after calling the function createDocument, must be included in the JSON document (which should 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: Please note that in systems up to v1.7.7 the information fiscalDocumentNumber was returned in the field fiscalisationDocumentNumber of the fiscalResponse object. See also article: "Given Transaction not started". In v1.7.7 an additional field fiscalDocumentNumber (string) was introduced in the fiscalResponse object.
|
|
| fiscalDocumentRevision | O/M* |
Revision number of the fiscal document (assigned by the RetailForce system, or by the respective fiscalisation unit - e.g. TSE in Germany)
Attention: Please note that in systems up to v1.7.7 the fiscalDocumentRevision was returned in the field fiscalisationDocumentRevision in the header of the fiscalResponse. See also article: "Given Transaction not started". From v1.7.7 the property within the fiscalResponse object was renamed to 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 fiscalisation unit - e.g. TSE in Germany) | |
| positions | M | Information about the respective receipt / document position (content depends on the type of document and position - documentType, positionType) | |
| {...} | |||
| payments | O/M* | Information about payment (usage depends on the type of document - documentType) | |
| {...} | |||
| additionalHeader | O |
The additionalHeader array can be used to set additional free text lines in the document header. Country details:
Note: Currently, this array is only supported in Italy. It can also be filled in other countries, but has no effect. |
|
| additionalFooter | O |
The additionalFooter array can be used to set additional free text lines in the document footer. Country details:
Note: Currently, this array is only supported in Italy. It can also be filled in other countries, but has no effect. |
|
| FiscalAdditionalFields | O | ||
Comments
0 comments
Please sign in to leave a comment.