Zum Hauptinhalt gehen

Positions-Objekt "positions"

Harald Krondorfer
  • Aktualisiert

Dieser Artikel behandelt das Positions-Objekt ("positions") innerhalb des Dokumenten-Objekts
(Document object).

Eine vollständige Beschreibung des RetailForce DOM (Document Object Model), sowie eine Beschreibung der einzelnen Elemente, finden sie im Downloads-Bereich der RetailForce Website (Object model documentation.pdf) im jeweilige Versions-Verzeichnis.

Im Objekt "positions" finden sich Informationen zur jeweiligen Belegposition des Dokuments. 

Das Positions-Objekt besteht aus:

  • DocumentPositionBase - enthält Basisinformationen zur Position (unabhängig vom Typ der jeweiligen Position)
  • Positions-Typ spezifische Angaben - in Abhängigkeit vom Positions-Type "type" (DocumentPositionType) müssen unterschiedliche Inhalte angegeben werden (der Positions-Typ definiert den Inhalt der Position).

DocumentPositionsBase

Das nachfolgende Objekt enthält Beispieldaten.

  "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": {}
    }
  ],

Das DocumentPositionsBase-Objekt beinhaltet nachfolgende Angaben.

Informationen in der Spalte "Typ":

  • M ... erforderlich ("mandatory)
  • M* ... erforderlich in bestimmten Ländern, oder unter bestimmten Voraussetzungen
  • R ... empfohlen ("recommended")
  • O ... optional
Element Typ Beschreibung
positionNumber M

Laufende Nummer der Position. 

Achtung: Nummer der ersten Position ist immer "0"!
positionReference O Referenzierung auf eine andere Position innerhalb des Dokuments. Äquivalent zu documentReference.
  {...} O  
cancellationPosition M "true" (wahr), wenn diese Position eine Position eines anderen Dokuments storniert; andernfalls "false" (falsch).
type M

gibt den Positions-Type "type" (DocumentPositionType) an.

Enum: 

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

Erklärungen zu den einzelnen Typen (DocumentPositionTypes) finden sich nach der Tabelle.
additionalFields O  
  {...}    
createDate M Zeitpunkt, wann die Position erzeugt wurde.
externalIdentifier O Externe ID (aus dem Vorsystem), für interne Zwecke, nicht relevant für Fiskalisierung.
user O Angaben zum (Registrierkassen-) Benutzer welcher die jeweilige Position erfasst hat.
  {...}    
salesPerson O Angaben zum Verkaufspersonal der jeweiligen Position.
  {...}    
FiscalAdditionalFields O  

 

DocumentPositionType

[0] = Item

Beim Typ "item" (DocumentPositionItem) handelt es sich um einen bestimmten Verkaufsartikel (Waren oder Dienstleistung).

Beispiel DocumentPositionItem:

positions": [
   {
      "itemCaption": "Wiener Schnitzel",
      "itemShortCaption": "W.Schnitzel",
      "itemSerialNumber": "string",
      "discounts": [
         {
            "discountValue": 1.6900,
            "caption": "Stammkunden Rabatt",
            "discountOrder": 0,
            "type": 1,
            "typeValue": 10.00,
            "promotionKeys": [],
            "identifier": null
         }
      ],
      "type": 0,
      "useSubItemVatCalculation": false,
      "subItems": [],
      "inHouse": true,
      "itemGroupId": "1000",
      "itemGroupCaption": "Hauptspeisen",
      "costPrice": null,
      "itemDateOfEntry": null,
      "quantity": 1.0,
      "quantityUnit": {
         "id": null
      }
      "itemId": "1028",
      "baseNetValue": 14.08,
      "baseGrossValue": 16.90,
      "baseTaxValue": 2.82,
      "gtin": "8718274490558",
      "businessTransactionType": 0,
      "vatIdentification": 1,
      "vatPercent": 20.00,
      "netValue": 12.68,
      "grossValue": 15.21,
      "taxValue": 2.53,
      "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": {}
   }
],

Das DocumentPositionItem-Objekt beinhaltet nachfolgende Angaben.

Informationen in der Spalte "Typ":

  • M ... erforderlich ("mandatory)
  • M* ... erforderlich in bestimmten Ländern, oder unter bestimmten Voraussetzungen
  • R ... empfohlen ("recommended")
  • O ... optional
Element Typ Beschreibung
itemCaption M Artikelbezeichnung, Bezeichnung der Serviceleistung
itemShortCaption   Kurzbezeichnung des Artikels, wird z.B. verwendet, wenn Beschränkungen hinsichtlich der Zeichenlänge, etwa bei Fiskaldruckern, existieren.
itemSerialNumber   Seriennummer des Artikels
discounts   Angaben zu Rabatten, Preisnachlässen, etc.
  discountValue M

Rabattsumme / Summe des Preisnachlasses

Achtung: bei discountType [1] = discount ist die Rabattsumme mit 4 Nachkommastellen anzugeben!
  caption R

Bezeichnung des Rabattes

Länderinformation:
  • Italien: discounts.caption wird als Rabattbezeichnung am Beleg angedruckt
  discountOrder M*

Gibt die Reihenfolge der Rabattberechnung an. Der erste berücksichtigte Rabatt hat den Wert 0.

Muss angegeben werden, wenn mehrere Rabatte auf einen Artikel angewendet werden.
  type M

Art des Rabattes

Enum:

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

Rabattwert

bei [0] = Allowance: die Rabattsumme

bei [1] = Discount: der Prozentsatz (z.B. 10% Rabatt)
  promotionKeys O Promotion Keys - falls verwendet (z.B. Gutscheincode)
  identifier O Zusätzlicher Identifikator für den Rabatt (kann z. B. für die Gruppierung von Rabatten zu Rabattarten verwendet werden).
type M Positions-Typ (DocumentPositionType)
useSubItemVatCalculation O "true" (wahr), wenn die Mehrwertsteuerberechnung der Sub-Positionen (SubItems) übernommen und die Mehrwertsteuer der übergeordneten Position ignoriert werden soll; andernfalls "false" (falsch).
subItems O Angaben zu SubItems. Siehe: DocumentPositionType [1] = SubItem
  [...]    
inHouse O Kennzeichnet einen In-House Verkauf bzw. Außerhausverkauf (true / false)
itemGroupId M*

Kennzeichen der Artikelgruppe

Länderinformation:
  • Dänemark: Pflichtangabe ("artGroupID" in SAF-T)
itemGroupCaption O Bezeichnung der Artikelgruppe
costPrice O  
itemDateOfEntry M* Zeitpunkt der Artikelanlage.
Länderinformation:
  • Dänemark: Pflichtabgabe ("dateOfEntry" und "timeOfEntry" in SAF-T). Die Felder repräsentieren den Zeitpunkt, wann der Artikel zum ersten Mal im System angelegt wurde (Stammdatenanlage). Wenn diese Informationen im Kassensystem nicht vorhanden sind, müssen die folgenden Werte verwendet werden: dateOfEntry: 0001-01-01, timeOfEntry: 00:00:00 und UTC-Offset: +00:00 
    • "itemDateOfEntry": "0001-01-01T00:00:00+00:00"
quantity M Mengenangabe zum Artikel
quantityUnit O  
  id M*

Angabe zur Mengeneinheit.

Länderinformation:
  • Rumänien: Pflichtangabe
itemId M ID Kennzeichen des Artikels
baseNetValue M*

Netto-Summe (excl. MwSt.) der Position vor Rabatt / Aufschlag

Achtung: (Netto-)Summe der Position, NICHT des Artikels. Wenn Menge = 2, dann ist auch die baseNetValue Artikelpreis x 2!
baseGrossValue M*

Brutto-Summe (inkl. MwSt.) der Position vor Rabatt / Aufschlag

Achtung: (Brutto-)Summe der Position, NICHT des Artikels. Wenn Menge = 2, dann ist auch die baseGrossValue Artikelpreis x 2!
baseTaxValue M*

MwSt.-Summe der Position vor Rabatt / Aufschlag

Achtung: (MwSt.-)Summe der Position, NICHT des Artikels. Wenn Menge = 2, dann ist auch die baseTaxValue Artikelpreis x 2!
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 Kennzeichen des MwSt.-Satzes.

Kann mittels GET /api/v1/information/client/ {clientId}/getVatIdentification unter Angabe des MwSt. Satzes des jeweiligen Landes, abgerufen werden.
vatPercent M MwSt.-Satz in Prozent
netValue M

Netto-Summe der Position (abzüglich etwaiger Rabatte bzw. zuzüglich etwaiger Aufschläge) - exkl. MwSt.

Ist immer anzugeben.
grossValue M

Brutto-Summe der Position (abzüglich etwaiger Rabatte bzw. zuzüglich etwaiger Aufschläge) - inkl. MwSt.

Ist immer anzugeben.
taxValue M

MwSt.-Summe der Position (abzüglich etwaiger Rabatte bzw. zuzüglich etwaiger Aufschläge)

Ist immer anzugeben.
accountingIdentifier O Zusätzliche Kennung für Buchhaltungszwecke (Buchhaltungsschnittstelle)
itemTaxType M*

Steuerart der Position:

  • deliveries - Lieferung
  • services - Dienstleistung
Länderinformationen:
  • Spanien: Muss bei Rechnungserstellung an nicht-spanische Kunden gesetzt werden.
positionNumber M Positionsnummer, beginnend mit 0
positionReference O Angabe einer Positionsnummer auf welche verwiesen werden soll
cancellationPosition O "true" (wahr), wenn diese Position eine Position eines anderen Dokuments storniert; andernfalls "false" (falsch)
createDate O Zeitpunkt der Erfassung der Position

 

[1] = SubItem

Unterpositionen oder "Subpositionen" (DocumentPositionSubItem) schaffen die Möglichkeit, die Zusammensetzung von verkauften Produkten bzw. Warengruppenbezeichnungen auf Artikelebene zu erklären.

Beispiel: Menü = Cola und Hamburger.

SubItems haben erklärenden Charakter und müssen nicht verwendet werden. Auch haben sie keine Auswirkung hinsichtlich Preis und Umsatz- / Mehrwertsteuer.

Hinweis: die Position "SubItem" entspricht der "Item"-Position, enthält allerdings die Elemente "useSubItemVatCalculation" und "subItems" nicht.

 

[2] = Text

Wird verwendet, für die Umsetzung einer Text- oder Bar-Code-Position innerhalb des Dokuments.

Beispiel DocumentPositionText:

positions": [
   {
      "type": 2,
      "text": "Beispieltext",
      "barcodeType": code128,
      "barcode": "Beispieltext",
      "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": {}
   }
],

Das DocumentPositionText-Objekt beinhaltet nachfolgende Angaben.

Informationen in der Spalte "Typ":

  • M ... erforderlich ("mandatory)
  • M* ... erforderlich in bestimmten Ländern, oder unter bestimmten Voraussetzungen
  • R ... empfohlen ("recommended")
  • O ... optional
Element Typ Beschreibung
type M Positions-Typ (DocumentPositionType)
text O

Freitextfeld

Länderinformation:
  • Italien EPSON-Drucker: max. 38 Zeichen  je Textposition möglich. Mehrzeiliger Text muss auf mehrere Positionen aufgeteilt werden.
barcodeType O

Angabe zum Barcode-Typ

Enum:

  • ean8
  • ean13
  • code128
barcode O Daten des Barcodes
positionNumber M Positionsnummer, beginnend mit 0

 

[3] = Booking

Buchungspositionen (DocumentPositionBooking) werden für Ein-, Auszahlungen sowie Verkäufe von Mehrzweckgutscheinen (payIn, payOut, multiPurposeVoucher,...) verwendet.

Beispiel DocumentPositionBooking:

positions": [
   {
      "type": 3,
      "caption": "Einzahlung",
      "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": {}
   }
],

Das DocumentPositionBooking-Objekt beinhaltet nachfolgende Angaben.

Informationen in der Spalte "Typ":

  • M ... erforderlich ("mandatory)
  • M* ... erforderlich in bestimmten Ländern, oder unter bestimmten Voraussetzungen
  • R ... empfohlen ("recommended")
  • O ... optional
Element Typ Beschreibung
type M Positions-Typ (DocumentPositionType)
caption M Bezeichnung der Buchungsposition
identifier O Zusätzliches ID-Kennzeichen der Buchung
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
payOutType M*

Gibt die Art der Auszahlung an. Notwendig in bestimmten Ländern.

Länderinformation:
  • Dänemark: Pflichtabgabe ("reportPayOut" > "payOutType" in SAF-T). Ist ein String Element  (string36) welches zur Bezeichnung der Art der Auszahlung dient.
Hinweis: Neu mit DOM v1.2.0 / Client v1.7.6
vatIdentification M

ID Kennzeichen des MwSt.-Satzes.

Kann mittels GET /api/v1/information/client/ {clientId}/getVatIdentification unter Angabe des MwSt. Satzes des jeweiligen Landes, abgerufen werden.
vatPercent M MwSt.-Satz in Prozent
netValue M

Netto-Summe der Position (abzüglich etwaiger Rabatte) - exkl. MwSt.

Ist immer anzugeben.
grossValue M

Brutto-Summe der Position (abzüglich etwaiger Rabatte) - inkl. MwSt.

Ist immer anzugeben.
taxValue M

MwSt.-Summe der Position (abzüglich etwaiger Rabatte)

Ist immer anzugeben.
accountingIdentifier O Zusätzliche Kennung für Buchhaltungszwecke (Buchhaltungsschnittstelle)
itemTaxType M*

Steuerart der Position:

  • deliveries - Lieferung
  • services - Dienstleistung
Länderinformation:
  • Spanien: Muss bei Rechnungserstellung an Nicht-Spanische Kunden gesetzt werden.
positionNumber M Positionsnummer, beginnend mit 0
positionReference O Angabe einer Positionsnummer auf welche verwiesen werden soll
cancellationPosition O "true" (wahr), wenn diese Position eine Position eines anderen Dokuments storniert; andernfalls "false" (falsch)
createDate O Zeitpunkt der Erfassung der Position

 

[9] = SubTotal

Zwischensummen-Position.

Hinweis: Position "SubTotal" entspricht der Position "Total".

 

[10] = Total

Summen-Position. Wird DocumentPositionTotal verwendet, so muss sie immer die letzte Position im Dokument sein (höchste positionNumber).

Beispiel DocumentPositionTotal:

positions": [
   {
      "type": 10,
      "rounding": null,
      "baseValue": 200.00,
      "value": "200.00",
      "discounts": [
         {
            "discountValue": 1.6900,
            "caption": "Stammkunden Rabatt",
            "discountOrder": 0,
            "type": 1,
            "typeValue": 10.00,
            "promotionKeys": [],
            "identifier": null
         }
      ],
      "caption": "Summe",
      "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": {}
   }
],

Das DocumentPositionTotal-Objekt beinhaltet nachfolgende Angaben.

Informationen in der Spalte "Typ":

  • M ... erforderlich ("mandatory)
  • M* ... erforderlich in bestimmten Ländern, oder unter bestimmten Voraussetzungen
  • R ... empfohlen ("recommended")
  • O ... optional
Element Typ Beschreibung
type M Positions-Typ (DocumentPositionType)
rounding O

Erlaubte Rundungen bei Summenberechnung. Wenn die Summe der Positionen (Bruttowert) nicht gleich der Zahlungssumme ist.

Z.B. 0,01 würde Rundungsdifferenzen von +/-0,01 erlauben.

Hinweis: Bitte mit Vorsicht verwenden. Hohe Werte deaktivieren die Betragsprüfung für den Zahlungsbetrag/Bruttowert des Dokuments.
baseValue O Basisbetrag der Position vor Anwendung von Rabatten
value M Summe / Zwischensumme nach Rabatten
discounts   Angaben zu Rabatten, Preisnachlässen, etc.
  discountValue M

Rabattsumme / Summe des Preisnachlasses

Achtung: bei discountType [1] = discount ist die Rabattsumme mit 4 Nachkommastellen anzugeben!
  caption O Bezeichnung des Rabattes
  discountOrder M*

Gibt die Reihenfolge der Rabattberechnung an. Der erste berücksichtigte Rabatt hat den Wert 0.

Muss angegeben werden, wenn mehrere Rabatte auf einen Artikel angewendet werden.
  type M

Art des Rabattes

Enum:

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

Rabattwert

bei [0] = Allowance: die Rabattsumme

bei [1] = Discount: der Prozentsatz (z.B. 10% Rabatt)
  promotionKeys O Promotion Keys - falls verwendet (z.B. Gutscheincode)
  identifier O Zusätzlicher Identifikator für den Rabatt (kann z. B. für die Gruppierung von Rabatten zu Rabattarten verwendet werden).
caption O Bezeichnung der Position
positionNumber M Positionsnummer, beginnend mit 0
positionReference O Angabe einer Positionsnummer auf welche verwiesen werden soll
cancellationPosition O "true" (wahr), wenn diese Position eine Position eines anderen Dokuments storniert; andernfalls "false" (falsch)
createDate O Zeitpunkt der Erfassung der Position

 

 

Verwandte Beiträge

Kommentare

0 Kommentare

Bitte melden Sie sich an, um einen Kommentar zu hinterlassen.

Powered by Zendesk