Positionsobjektet ”positions” – RetailForce

Denna artikel behandlar objektet positions inom dokumentobjektet (Document-objektet).

En fullständig beskrivning av RetailForce DOM (Document Object Model), samt en beskrivning av de enskilda elementen, finns i nedladdningsområdet på RetailForce website (Object model documentation.pdf) i respektive versionskatalog.

Objektet ”positions” innehåller information om dokumentets respektive position.

Positionsobjektet består av:

DocumentPositionBase – innehåller grundläggande information om positionen (oberoende av typen av respektive position)
Positionsspecifik information – beroende på positions typ ”type” (DocumentPositionType) måste olika innehåll anges (positionstypen definierar positionens innehåll).

DocumentPositionsBase

Följande objekt innehåller exempeldata.

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

DocumentPositionsBase-objektet innehåller följande information.

Information i kolumnen ”Type”:

M … obligatoriskt / krävs
M* ... obligatoriskt / krävs i vissa länder eller under vissa förutsättningar
R ... rekommenderat
O... valfritt

Element		Typ	Beskrivning
PositionNumber		M	Positionens löpnummer. Observera: Nummeret för den första positionen är alltid "0"!
positionReference		O	Hänvisning till en annan position i dokumentet. Motsvarar documentReference.
	{...}	O
cancellationPosition		M	"true" om denna position upphäver en position i ett annat dokument; annars "false".
DeletedPosition		O	"true" om denna position har raderats; annars "false".
typ		M	anger positionstypen "type" (DocumentPositionType). Enum: [0] = Item [1] = SubItem [2] = Text [3] = Bokning [9] = Delsumma [10] = Totalsumma Förklaringar av de enskilda typerna (DocumentPositionTypes) finns efter denna tabell.
AdditionalFields		O
	{...}
CreateDate		M	Tidpunkt då positionen skapades.
ExternalIdentifierare		O	Externt ID (från det tidigare systemet), för interna ändamål, inte relevant för skattehantering.
användare		O	Uppgifter om den (kassaregister-)användare som lagt in respektive artikel.
	{...}
SalesPerson		O	Uppgifter om försäljaren på respektive position.
	{...}
FiscalAdditionalFields		O

DocumentPositionType

[0] = Artikel

Typen ”artikel” (DocumentPositionItem) är en specifik försäljningsartikel (vara eller tjänst).

Exempel på 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,
         "isoCode": "1"
      }
      "itemId": "1028",
      "itemType": "[0] = Article",
      "baseNetValue": 14.08,
      "baseGrossValue": 16.90,
      "baseTaxValue": 2.82,
      "baseTaxValue2": 0,
      "gtin": "8718274490558",
      "businessTransactionType": 0,
      "itemTypeClassification": "[1] = AlcoholicBeverage",
      "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,
      "deletedPosition": 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": {}
   }
],

Objektet DocumentPositionItem innehåller följande information.

Information i kolumnen ”Typ”:

M ... obligatoriskt / krävs
M* ... obligatoriskt i vissa länder eller under vissa förutsättningar
R ... rekommenderat
O... valfritt

Element		Typ	Beskrivning
ItemCaption		M	Artikelbeteckning, beskrivning av tjänsten
ItemShortCaption		O	Kortnamn på posten, används t.ex. när det finns begränsningar för teckenlängden, såsom vid användning av kvittoskrivare.
ItemSerialNumber		M*	Artikelns serienummer. Landspecifika uppgifter: Portugal: Obligatorisk information
rabatter			Uppgifter om rabatter, prisnedsättningar m.m.
	DiscountValue	M	Rabattbelopp / rabattens storlek Observera: om DiscountType [1] = discount måste rabattbeloppet anges med 4 decimaler!
	caption	R	Beteckning på rabatten Landspecifika uppgifter: Italien: discounts.caption skrivs ut på kvittot som rabattbeteckning
	DiscountOrder	M*	Anger i vilken ordning rabatten beräknas. Den första rabatten som beaktas har värdet 0. Måste anges om flera rabatter tillämpas på en artikel.
	typ	M	Rabattyp Enum: [0] = Rabatt – Summa rabatt [1] = Rabatt – procentuell rabatt
	TypeValue	M	Rabattvärde (summan av avdraget) vid [0] = Rabatt: DiscountValue (=> DiscountValue = TypeValue) vid [1] = Rabatt: procenttalet (t.ex. 10 % rabatt)
	PromotionKeys	O	Kampanjnycklar – om sådana används (t.ex. kupongkod)
	identifier	O	Ytterligare identifierare för rabatten (kan t.ex. användas för att gruppera rabatter i rabatttyper).
typ		M	Positions-Typ (DocumentPositionType)
UseSubItemVatCalculation		O	"true" om momsberäkningen för underposterna (SubItems) ska övertas och momsen för överordnad post ska ignoreras; annars "false".
SubItems		O	Detaljer om underposterna (SubItems). Se: DocumentPositionType [1] = SubItem
	[...]
inhouse		O	Anger en intern försäljning eller en extern försäljning (true/falskt).
ItemGroupId		M*	Artikelgruppindikator Landspecifika uppgifter: Danmark: obligatorisk uppgift (”artGroupID” i SAF-T)
ItemGroupCaption		O	Artikelgruppsbeteckning
CostPrice		O/M*	Enhetspris för artikeln Landspecifika uppgifter: Danmark: kan anges som pris per enskild artikel för underartiklar. Portugal: obligatorisk uppgift (om inget anges beräknas CostPrice enligt: BaseGrossValue / antal)
itemDateOfEntry		M*	Tidpunkt för artikelns skapande. Landspecifika uppgifter: Danmark: obligatorisk information (”dateOfEntry” i SAF-T). Fälten anger tidpunkten då posten först skapades i systemet (skapande av stamdata). Om denna information inte finns tillgänglig i kassasystemet måste följande värden användas: dateOfEntry: 0001-01-01, timeOfEntry: 00:00:00 och UTC-offset: +00:00 `"itemDateOfEntry": "0001-01-01T00:00:00+00:00"`
kvantitet		M	Antal för artikeln
QuantityUnit		M*	Angivelse av måttenheten Landspecifikationer: Portugal: Kräver angivande av en måttenhet (”ID” eller ”isoCode”)
	ID	M*	Angivelse av måttenhet. Landsspecifikationer: Rumänien: Obligatorisk information
	isoCode	M*	Standardmåttenhet enligt ISO/UCUM-koden. För mer information, se den länkade artikeln.
ItemId		M	Artikelns ID
ItemType		M*	Beskriver typen av artikel: varor eller tjänster. [0] = Artikel [1] = Tjänst Landspecifika uppgifter: Frankrike: Obligatorisk information
BaseNetValue		M*	Nettototal (exkl. Vat) före rabatt eller tillägg Observera: (Netto)summan för raden/positionen, INTE för artikeln. Om kvantiteten = 2, är BaseNetValue också artikelpriset x 2!
BaseGrossValue		M*	Bruttosumma (inkl. Vat) före rabatt eller tillägg Observera: (Brutto) summan för raden/positionen, INTE för artikeln. Om antal = 2, är BaseGrossValue också artikelpriset x 2!
BaseTaxValue		M*	Vat-belopp (eller summan av den första skattesatsen) före rabatt eller tillägg Observera: (Vat) summan för raden/positionen, INTE för artikeln. Om antal = 2, är BaseTaxValue också artikelpriset x 2! Landspecifikationer: Québec (Kanada): Federal skatt GST
BaseTaxValue2		M*	Summan av den andra skattesatsen för positionen före rabatt/tillägg. Landsinformation: Québec (Kanada): Provinsskatt QST
GTIN		O	Globalt varunummer (GTIN) Landsspecifikationer: Portugal: Det rekommenderas att ange GTIN för den aktuella artikeln. Alternativt används egenskapen ”ItemId” i SAF-T.
BusinessTransactionType		M	Typ av affärstransaktion. Enum: [0] = Revenue [1] = Rabatt [2] = Pant på tomförpackningar [3] = Enkelbrukskupong [4] = MultiPurposeVoucher [5] = Dricks [6] = Företagspåslag [7] = Pant [10] = Utbetalning [11] = PayIn [90] = MoneyTransfer [91] = Kontantskillnad [92] = Bevilja äkta [93] = Bevilja icke-verkligt
ItemTypeClassification			ItemTypeClassification kan användas för att tillämpa en ytterligare klassificering på en artikel. ItemTypeClassification kan endast anges om egenskapen ”ItemType” har angetts till ”[0] – Artikel” eller ”ItemType”: 0. Detaljerad information om egenskapen ”ItemTypeClassification” finns i den länkade artikeln. Följande klassificeringar finns tillgängliga. [1] = Alkoholhaltig dryck [5] = Tobaksprodukter [10] = Bensin [11] = etanolbränsle för fordon [12] = dieselbränsle [13] = Fettsyrametylester [14] = Dieselbränsle avsett för jordbruks- och fiskerianvändning [15] = Naturgas för transport [16] = Flytande petroleumgas för transport [17] = Bränsle för transport som inte klassificeras någon annanstans Landspecifikationer: FiscalCountryProperties: Kravet på att definiera ItemTypeClassification anges i fiscalCountryProperties via egenskapen itemTypeClassificationRequired. Om värdet är ”true” måste posten klassificeras – förutsatt att det är en specialpost (!). supportedItemTypeClassification definierar för vilken typ av produkt egenskapen kan ställas in.
VatIdentification		M	ID för mervärdesskattesatsen. Kan hämtas via GET /api/v1/information/client/ {clientId}/getVatIdentification, där man anger momssatsen för respektive land.
VatPercent		M	Vat i procent eller den första skattesatsen som gäller för artikeln i respektive land. Landsinformation: Québec (Kanada): Federal skatt GST
VatPercent2		M*	Andra skattesatsen som gäller för artikeln, uttryckt i procent i respektive land. Landuppgifter: Québec (Kanada): Provinsskatt QST
NetValue		M	Nettototal för positionen (minus eventuella rabatter / plus tillägg) – exkl. Vat. Måste alltid anges.
GrossValue		M	Positionens bruttosumma (minus eventuella rabatter / plus eventuella tillägg) – inkl. Vat. Måste alltid anges.
TaxValue		M	Vat-belopp (eller summan av den första skattesatsen) för positionen (minus eventuella rabatter / plus tillägg) Måste alltid anges. Landuppgifter: Québec (Kanada): Federal skatt GST
TaxValue2		M*	Summan av den andra skattesatsen för varan efter rabatt/tillägg. Landsinformation: Québec (Kanada): Provinsskatt QST
AccountingIdentifier		O	Ytterligare identifierare för redovisningsändamål (redovisningsgränssnitt)
ItemTaxType		M*	Skattetyp för positionen: leveranser tjänster Landuppgifter: Spanien: Måste anges vid fakturering till kunder utanför Spanien.
PositionNumber		M	Positionsnummer, börjar med 0
positionReference		O	Angivelse av ett positionsnummer som ska hänvisas till
cancellationPosition		O	"true" om denna position upphäver en position i ett annat dokument; i annat fall "false"
CreateDate		O	Tidpunkt för registrering av positionen

[1] = SubItem

"Underposter" (DocumentPositionSubItem) gör det möjligt att förklara sammansättningen av sålda produkter eller produktgruppsbeskrivningar på artikelnivå.

Exempel: Meny = Cola och hamburgare.

SubItems har en förklarande karaktär och behöver inte användas. De har heller ingen inverkan på pris, försäljning eller mervärdesskatt.

Observera: posten ”SubItem” motsvarar posten ”Item”, men innehåller inte elementen ”UseSubItemVatCalculation” och ”SubItems”.

[2] = Text

Används för att ange en text- eller Barcode-position i dokumentet.

Exempel på DocumentPositionText:

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

Objektet DocumentPositionText innehåller följande information.

Information i kolumnen ”Type”:

M ... obligatoriskt / krävs
M* ... obligatoriskt / krävs i vissa länder eller under vissa förhållanden
R ... rekommenderat
O... valfritt

Element	Typ	Beskrivning
typ	M	Positions-Typ (DocumentPositionType)
text	O	Fält för fritext Landspecifika uppgifter: Italien EPSON-skrivare: skickas till skrivaren som messageType="4" (Body Lines); max. 38 tecken per textposition möjligt. Efter 25 tecken sker ett automatiskt radbryt. Flerradig text måste delas upp i flera positioner. Alternativt kan ytterligare header- och Footer-texter användas. Om det inte sker något radbryt efter 25 tecken, utan texten istället avkortas, vänligen kontakta din skrivarservicetekniker (nyckelord: ”RT DESCR. OVERLAP”).
barcodeType	O	Angivelse av Barcode-typ Enum: ean8 ean13 code128
Barcode	O	Barcode-data
PositionNumber	M	Positionsnummer, börjar med 0

[3] = Bokning

Bokningspositioner (DocumentPositionBooking) används för insättningar, uttag samt försäljning av MultiPurposeVoucher (PayIn, payOut, MultiPurposeVoucher, ...).

Exempel på 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,
      "deletedPosition": 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": {}
   }
],

Objektet DocumentPositionBooking innehåller följande information.

Information i kolumnen ”Typ”:

M ... obligatoriskt / krävs
M* ... obligatoriskt/krävs i vissa länder eller under vissa förutsättningar
R ... rekommenderat
O... valfritt

Element	Typ	Beskrivning
typ	M	Positions-Typ (DocumentPositionType)
caption	M	Beskrivning av bokningspositionen
identifierare	O	Indikator för ytterligare ID för bokningen
BusinessTransactionType	M	Typ av affärstransaktion. Enum: [0] = Revenue [1] = Rabatt [2] = Pant [3] = Enkelspårig kupong [4] = MultiPurposeVoucher [5] = Dricks [6] = Företagspåslag [7] = Pant [10] = Utbetalning [11] = PayIn [90] = MoneyTransfer [91] = Kontantskillnad [92] = Bevilja äkta [93] = Bevilja icke-verkligt
PayOutType	M*	Anger typen av utbetalning. Krävs i vissa länder. Möjliga värden: [0] = CleaningMaterial [1] = Kontorsmaterial [2] = PostalFee [3] = Lön [4] = Löner [5] = Inköp av varor [6] = Övriga kostnader Landspecifika uppgifter: Danmark: Obligatorisk information (”reportPayOut” ”PayOutType” i SAF-T). Ett strängelement (string36) som används för att ange typen av utbetalning. Obs! Nytt från och med DOM v1.2.0 / Client v1.7.6
VatIdentification	M	Moms-ID. Kan hämtas via GET /api/v1/information/client/ {clientId}/getVatIdentification, där man anger momsatsen för respektive land.
VatPercent	M	Vat rate in percent
NetValue	M	Nettosumman för positionen (efter eventuella rabatter) – exkl. Vat. Måste alltid anges.
GrossValue	M	Positionens bruttosumma (minus eventuella rabatter) – inkl. Vat. Måste alltid anges.
TaxValue	M	Posterens Vat-belopp (minus eventuella rabatter) Måste alltid anges.
AccountingIdentifier	O	Ytterligare identifierare för redovisningsändamål (redovisningsgränssnitt)
ItemTaxType	M*	Skattetyp för positionen: leveranser tjänster Landuppgifter: Spanien: Måste anges vid fakturering till kunder utanför Spanien.
PositionNumber	M	Positionsnummer, börjar med 0
positionReference	O	Angivelse av ett artikelnummer som ska hänvisas till
cancellationPosition	O	”true” om denna position upphäver en position i ett annat dokument; i annat fall ”false”.
DeletedPosition	O	"true" om denna position har raderats; annars "false".
CreateDate	O	Tidpunkt för registrering av positionen

[9] = Delsumma

Delsumma för posten

Obs: Positionen ”SubTotal” motsvarar positionen ”Total”.

[10] = Total

Totalposition. Om DocumentPositionTotal används måste den alltid vara den sista positionen i dokumentet (högsta PositionNumber).

Exempel på 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,
      "deletedPosition": 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": {}
   }
],

Objektet DocumentPositionTotal innehåller följande information.

Information i kolumnen ”Type”:

M ... obligatoriskt / krävs
M* ... obligatoriskt/krävs i vissa länder eller under vissa förutsättningar
R ... rekommenderat
O... valfritt

Element		Typ	Beskrivning
typ		M	Positions-Typ (DocumentPositionType)
avrundning		O	avrundning tillämpas. Om summan av positionerna (bruttovärdet) inte är lika med betalningssumman. T.ex. 0,01 tillåter avrundningsskillnader på +/-0,01 Obs! Använd med försiktighet. Höga värden inaktiverar beloppsvalideringen för betalningsbeloppet/dokumentets bruttovärde
BaseValue		M*	Positionens basbelopp före tillämpning av rabatter (endast om rabatter tillämpas)
value		M	Positionens värde inklusive rabatter.
rabatter			Uppgifter om rabatter, prisnedsättningar m.m.
	DiscountValue	M	Rabattbelopp / rabattens storlek Observera: om DiscountType [1] = discount måste rabattbeloppet anges med 4 decimaler!
	caption	O	Beteckning på rabatten
	DiscountOrder	M*	Anger i vilken ordning rabatten beräknas. Den första rabatten som beaktas har värdet 0. Måste anges om flera rabatter tillämpas på en artikel.
	typ	M	Rabattyp Enum: [0] = Rabatt – summarabatt [1] = Rabatt – procentuell rabatt
	TypeValue	M	Rabattvärde (summan av rabatten) vid [0] = Rabatt: DiscountValue vid [1] = Rabatt: procenttalet (t.ex. 10 % rabatt)
	PromotionKeys	O	Kampanjnycklar – om sådana används (t.ex. kupongkod)
	identifier	O	Ytterligare identifierare för rabatten (kan t.ex. användas för att gruppera rabatter i rabatttyper).
caption		O	Beteckningen på positionen
PositionNumber		M	Tjänstenummer, börjar med 0
positionReference		O	Angivelse av ett positionsnummer som ska hänvisas till
cancellationPosition		O	"true" om denna position upphäver en position i ett annat dokument; i annat fall "false".
DeletedPosition		O	"true" om denna position har raderats; annars "false".
CreateDate		O	Tidpunkt för registrering av positionen

Den här artikeln har översatts automatiskt.

DocumentPositionsBase

DocumentPositionType

[0] = Artikel

[1] = SubItem

[2] = Text

[3] = Bokning

[9] = Delsumma

[10] = Total

Relaterade artiklar