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:
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:
|
|
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:
|
|
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:
|
|
itemGroupCaption | O | Bezeichnung der Artikelgruppe | |
costPrice | O | ||
itemDateOfEntry | M* |
Zeitpunkt der Artikelanlage.
Länderinformation:
|
|
quantity | M | Mengenangabe zum Artikel | |
quantityUnit | O | ||
id | M* |
Angabe zur Mengeneinheit.
Länderinformation:
|
|
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:
|
|
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:
Länderinformationen:
|
|
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.
[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:
|
|
barcodeType | O |
Angabe zum Barcode-Typ Enum:
|
|
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:
|
|
payOutType | M* |
Gibt die Art der Auszahlung an. Notwendig in bestimmten Ländern.
Länderinformation:
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:
Länderinformation:
|
|
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.
[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:
|
|
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 |
Kommentare
0 Kommentare
Bitte melden Sie sich an, um einen Kommentar zu hinterlassen.