Skip to main content

Positions-object "positions"

Harald Krondorfer
  • Updated

This Article deals with the positions object within the Document object (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.

The object "positions" contains information on the respective document position of the document.

The position object consists of:

  • DocumentPositionBase - contains basic information about the position (independent of the type of the respective position)
  • Position type specific information - depending on the position type "type" (DocumentPositionType), different contents must be specified (the position type defines the content of the position).

DocumentPositionsBase

The following object contains sample data.

  "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-05-03T11:20:40.057+01:00",
        "returnReasonType": "userMistake",
        "returnReasonText": "string"
      },
      "cancellationPosition": true,
      "type": "[0] = Item",
      "additionalFields": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "createDate": "2023-05-03T11:20:40.057+01:00",
      "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": {}
    }
  ],

The DocumentPositionsBase-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
positionNumber M

Sequence number of the position. 

Attention: Number of the first position is always "0"!
positionReference O Reference to another position within the document. Equivalent to documentReference.
  {...} O  
cancellationPosition M "true" if this position cancels a position of another document; otherwise "false".
type M

specifies the position type "type" (DocumentPositionType).

Enum: 

  • [0] = Item
  • [1] = SubItem
  • [2] = Text
  • [3] = Booking
  • [9] = SubTotal
  • [10] = Total

Explanations of the individual types (DocumentPositionTypes) can be found after this table.
additionalFields O  
  {...}    
createDate M Time when the position was created.
externalIdentifier O External ID (from the previous system), for internal purposes, not relevant for fiscalisation.
user O Details of the (cash register) user who entered the respective item.
  {...}    
salesPerson O Details of the sales staff of the respective position.
  {...}    
FiscalAdditionalFields O  

 

DocumentPositionType

[0] = Item

The type "item" (DocumentPositionItem) is a specific sales item (goods or service).

Example DocumentPositionItem:

positions": [
   {
      "itemCaption": "Prime rib steak house style",
      "itemShortCaption": "PrimeRibSpec",
      "itemSerialNumber": "string",
      "discounts": [
         {
            "discountValue": 1.6900,
            "caption": "Regular customer discount",
            "discountOrder": 0,
            "type": 1,
            "typeValue": 10.00,
            "promotionKeys": [],
            "identifier": null
         }
      ],
      "type": 0,
      "useSubItemVatCalculation": false,
      "subItems": [],
      "inHouse": true,
      "itemGroupId": "1000",
      "itemGroupCaption": "mains",
      "costPrice": null,
      "itemDateOfEntry": null,
      "quantity": 1.0,
      "quantityUnit": {
         "id": null
      }
      "itemId": "1028",
      "itemType": "[0] = Article",
      "baseNetValue": 14.08,
      "baseGrossValue": 16.90,
      "baseTaxValue": 2.82,
      "baseTaxValue2": 0,
      "gtin": "8718274490558",
      "businessTransactionType": 0,
      "vatIdentification": 1,
      "vatPercent": 20.00,
      "vatPercent2": 5,
      "additionalTax": {
         "additionalTaxType": "alcohol",
         "additionalTaxTypeIdentification": "string",
         "taxPercent": 0,
         "taxValue": 0
      },
      "netValue": 12.68,
      "grossValue": 15.21,
      "taxValue": 2.53,
      "taxValue2": 0,
      "accountingIdentifier": null,
      "itemTaxType": null,
      "positionNumber": 0,
      "positionReference": null,
      "cancellationPosition": false,
      "additionalFields": {},
      "createDate": null,
      "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": {}
   }
],

The DocumentPositionItem 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
itemCaption M Article designation, description of the service
itemShortCaption O Short name of the item, used e.g. when there are restrictions on the character length, such as with fiscal printers.
itemSerialNumber O Serial number of the item
discounts   Details of discounts, price reductions, etc.
  discountValue M

Discount sum / amount of the rebate

Attention: if discountType [1] = discount, the discount sum must be entered with 4 decimal places!
  caption R

Designation of the discount

Country details:
  • Italy: discounts.caption is printed on the receipt as discount designation
  discountOrder M*

Indicates the order in which the discount is calculated. The first discount taken into account has a value of 0.

Must be specified if multiple discounts are applied to an item.
  type M

Type of discount

Enum:

  • [0] = Allowance - Sum discount 
  • [1] = Discount - percentage discount
  typeValue M

Rebate value (sum of the reduction)

bei [0] = Allowance: the discountValue (=> discountValue = typeValue)

bei [1] = Discount: the percentage (e.g. 10% discount)
  promotionKeys O Promotion Keys - if used (e.g. voucher code)
  identifier O Additional identifier for the discount (can be used e.g. for grouping discounts into discount types).
type M Positions-Typ (DocumentPositionType)
useSubItemVatCalculation O "true" if the VAT calculation of the sub-items (SubItems) is to be taken over and the VAT of the parent item is to be ignored; otherwise "false".
subItems O Details of SubItems. See: DocumentPositionType [1] = SubItem
  [...]    
inHouse O Indicates an in-house sale or an out-of-house sale (true / false).
itemGroupId M*

Article group indicator

Country details:
  • Denmark: mandatory information ("artGroupID" in SAF-T)
itemGroupCaption O Article group designation
costPrice O  
itemDateOfEntry M*

Time of article creation.

Country details:
  • Denmark: mandatory information ("dateOfEntry" in SAF-T). The fields represent the time when the item was first created in the system (master data creation). If this information is not available in the POS system, the following values must be used: dateOfEntry: 0001-01-01, timeOfEntry: 00:00:00 and UTC-offset: +00:00 
    • "itemDateOfEntry": "0001-01-01T00:00:00+00:00"
quantity M Quantity information for the article
quantityUnit M*  
  id M*

Indication of the unit of measure.

Country details:
  • Romania: Mandatory information
itemId M ID of the article
itemType M*

Describes the type of item: goods or services.

  • [0] = Article
  • [1] = Service
Country details:
  • France: Mandatory information
baseNetValue M*

Net total (excl. VAT) before discount or surcharge

Attention: (Net) sum of the line/position, NOT of the article. If quantity = 2, then the baseNetValue is also item price x 2!
baseGrossValue M*

Gross total (incl. VAT) before discount or surcharge

Attention: (Gross) sum of the line/position, NOT of the article. If quantity = 2, then the baseGrossValue is also item price x 2!
baseTaxValue M*

VAT total (or sum of the first tax rate) before discount or surcharge

Attention: (VAT) sum of the line/position, NOT of the article. If quantity = 2, then the baseTaxValue is also item price x 2!
Country details:
  • Québec (Canada): Federal Tax GST
baseTaxValue2 M*

Sum of the second tax rate of the position before discount / surcharge.

Country details:
  • Québec (Canada): Provincial Tax QST
gtin O Global Trade Item Number (GTIN)
businessTransactionType M

Art des Geschäftsfalls.

Enum:

  • [0] = Revenue
  • [1] = Discount
  • [2] = DepositOnEmpties
  • [3] = SinglePurposeVoucher
  • [4] = MultiPurposeVoucher
  • [5] = Tip
  • [6] = CompanyTip
  • [7] = Deposit
  • [10] = PayOut
  • [11] = PayIn
  • [90] = MoneyTransfer
  • [91] = CashDifference
  • [92] = GrantGenuine
  • [93] = GrantUnreal
vatIdentification M

ID of the VAT rate.

Can be queried via GET /api/v1/information/client/ {clientId}/getVatIdentification, specifying the VAT rate of the respective country. rate of the respective country.
vatPercent M

VAT rate in percent or first tax rate applicable to the article in the respective country.

Country details:
  • Québec (Canada): Federal Tax GST
vatPercent2 M*

second tax rate applicable to the article, expressed in percent in the respective country.

Country details:
  • Québec (Canada): Provincial Tax QST
netValue M

Net total of the position (less any discounts / plus surcharges) - excl. VAT.

Must always be indicated.
grossValue M

Gross total of the position (less any discounts / plus surcharges) - incl. VAT.

Must always be indicated.
taxValue M

VAT total (or sum of the first tax rate) of the position (less any discounts / plus surcharges)

Must always be indicated.

Country details:
  • Québec (Canada): Federal Tax GST
taxValue2 M*

Sum of the second tax rate of the item after discount / surcharge.

Country details:
  • Québec (Canada): Provincial Tax QST
accountingIdentifier O Additional identifier for accounting purposes (accounting interface)
itemTaxType M*

Tax type of the position:

  • deliveries
  • services
Country details:
  • Spain: Must be set when invoicing non-Spanish customers.
positionNumber M Position number, starting with 0
positionReference O Specification of a position number to which reference is to be made
cancellationPosition O "true" if this position cancels a position of another document; otherwise "false"
createDate O Time of recording of the position

 

[1] = SubItem

"Sub-items" (DocumentPositionSubItem) create the possibility to explain the composition of sold products or product group descriptions at item level.

Example: Menu = Coke and hamburger.

SubItems have explanatory character and do not have to be used. They also have no effect with regard to price and sales / value added tax.

Note: the "SubItem" item corresponds to the "Item" item, but does not contain the elements "useSubItemVatCalculation" and "subItems".

 

[2] = Text

Used to convert a text or barcode position within the document.

Example DocumentPositionText:

positions": [
   {
      "type": 2,
      "text": "Example text",
      "barcodeType": code128,
      "barcode": "Example text",
      "positionNumber": 0,
      "positionReference": null,
      "cancellationPosition": false,
      "additionalFields": {},
      "createDate": null,
      "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": {}
   }
],

The DocumentPositionText 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
type M Positions-Typ (DocumentPositionType)
text O

Free-text field

Country details:
  • Italy EPSON printers: max. 38 characters per text position possible. Multi-line text must be divided into several positions.
barcodeType O

Barcode type indication

Enum:

  • ean8
  • ean13
  • code128
barcode O Barcode data
positionNumber M Position number, starting with 0

 

[3] = Booking

Bookings position (DocumentPositionBooking) are used for deposits, withdrawals as well as sales of multi-purpose vouchers (payIn, payOut, multiPurposeVoucher,...).

Example DocumentPositionBooking:

positions": [
   {
      "type": 3,
      "caption": "Depositg",
      "identifier": null,
      "businessTransactionType": 11,
      "payOutType": null,
      "vatIdentification": 4,
      "vatPercent": 0.00,
      "netValue": 20.00,
      "grossValue": 20.00,
      "taxValue": 0.00,
      "accountingIdentifier": null,
      "itemTaxType": null,
      "positionNumber": 0,
      "positionReference": null,
      "cancellationPosition": false,
      "additionalFields": {},
      "createDate": null,
      "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": {}
   }
],

The DocumentPositionBooking 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
type M Positions-Typ (DocumentPositionType)
caption M Description of the booking position
identifier O Additional ID indicator of the booking
businessTransactionType M

Type of business transaction.

Enum:

  • [0] = Revenue
  • [1] = Discount
  • [2] = DepositOnEmpties
  • [3] = SinglePurposeVoucher
  • [4] = MultiPurposeVoucher
  • [5] = Tip
  • [6] = CompanyTip
  • [7] = Deposit
  • [10] = PayOut
  • [11] = PayIn
  • [90] = MoneyTransfer
  • [91] = CashDifference
  • [92] = GrantGenuine
  • [93] = GrantUnreal
payOutType M*

Indicates the type of payout. Required in certain countries.

Country details:
  • Denmark: Mandatory information ("reportPayOut" "payOutType" in SAF-T). A string element (string36) used to designate the type of payout.
Note: New as of DOM v1.2.0 / Client v1.7.6
vatIdentification M

VAT rate-ID.

Can be queried via GET /api/v1/information/client/ {clientId}/getVatIdentification, specifying the VAT rate of the respective country.
vatPercent M VAT rate in percent
netValue M

Net total of the position (less any discounts) - excl. VAT.

Must always be indicated.
grossValue M

Gross total of the position (less any discounts) - incl. VAT.

Must always be indicated.
taxValue M

VAT total of the position (less any discounts)

Must always be indicated.
accountingIdentifier O Additional identifier for accounting purposes (accounting interface)
itemTaxType M*

Tax type of the position:

  • deliveries
  • services
Country details:
  • Spain: Must be set when invoicing non-Spanish customers.
positionNumber M Position number, starting with 0
positionReference O Specification of an item number to which reference is to be made
cancellationPosition O "true" if this position cancels a position of another document; otherwise "false".
createDate O Time of recording of the position

 

[9] = SubTotal

Subtotal position

Note: Position "SubTotal" corresponds to the position "Total".

 

[10] = Total

Total position. If DocumentPositionTotal is used, it must always be the last position in the document (highest positionNumber).

Example DocumentPositionTotal:

positions": [
   {
      "type": 10,
      "rounding": null,
      "baseValue": 200.00,
      "value": "200.00",
      "discounts": [
         {
            "discountValue": 1.6900,
            "caption": "Regulars discount",
            "discountOrder": 0,
            "type": 1,
            "typeValue": 10.00,
            "promotionKeys": [],
            "identifier": null
         }
      ],
      "caption": "Total",
      "positionNumber": 0,
      "positionReference": null,
      "cancellationPosition": false,
      "additionalFields": {},
      "createDate": null,
      "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": {}
   }
],

The DocumentPositionTotal 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
type M Positions-Typ (DocumentPositionType)
rounding O

rounding applied. If sum of positions (gross value) does notequal payment sum.

E.g. 0.01 would allow rounding differences of +/-0,01

Note: Please use carefully. High values will disable amount validation for payment amount / gross value of document
baseValue M* Base amount of the position before application of discounts (only if discounts are applied)
value M The position value including discounts.
discounts   Details of discounts, price reductions, etc.
  discountValue M

Discount sum / amount of the rebate

Attention: if discountType [1] = discount, the discount sum must be entered with 4 decimal places!
  caption O Designation of the discount
  discountOrder M*

Indicates the order in which the discount is calculated. The first discount taken into account has a value of 0.

Must be specified if multiple discounts are applied to an item.
  type M

Discount type

Enum:

  • [0] = Allowance - Summenrabatt
  • [1] = Discount - prozentueller Rabatt
  typeValue M

Rebate value (sum of the reduction)

bei [0] = Allowance: the discountValue

bei [1] = Discount: the percentage (e.g. 10% discount)
  promotionKeys O Promotion Keys - if used (e.g. voucher code)
  identifier O Additional identifier for the discount (can be used e.g. for grouping discounts into discount types).
caption O The designation of the position
positionNumber M Position number, starting with 0
positionReference O Specification of an position number to which reference is to be made
cancellationPosition O "true" if this position cancels a position of another document; otherwise "false".
createDate O Time of recording of the position

 

Related articles

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk