Positions-objektet »positions« – RetailForce

Denne artikel omhandler positionsobjektet inden for dokumentobjektet (Document-objektet).

En fuldstændig beskrivelse af RetailForce DOM (Document Object Model) samt en beskrivelse af de enkelte elementer findes i downloadområdet på RetailForce website (Object model documentation.pdf) i det respektive versionsbibliotek.

Objektet »positions« indeholder oplysninger om dokumentets respektive position.

Positionsobjektet består af:

DocumentPositionBase – indeholder grundlæggende oplysninger om positionen (uafhængigt af den pågældende positions type)
Positionsspecifikke oplysninger – afhængigt af positionstypen "type" (DocumentPositionType) skal der angives forskellige indholdselementer (positionstypen definerer indholdet af positionen).

DocumentPositionsBase

Følgende objekt indeholder eksempeldata.

  "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 indeholder følgende oplysninger.

Oplysninger i kolonnen "Type":

M ... obligatorisk / påkrævet
M* ... obligatorisk / påkrævet i visse lande eller under visse betingelser
R ... anbefalet
O... valgfrit

Elementer		Type	Beskrivelse
PositionNumber		M	Sekvensnummer for positionen. Bemærk: Nummeret på den første position er altid "0"!
positionReference		O	Henvisning til en anden position i dokumentet. Svarer til documentReference.
	{...}	O
cancellationPosition		M	"true", hvis denne position annullerer en position i et andet dokument; ellers "false".
DeletedPosition		O	"true", hvis denne position blev slettet; ellers "false".
type		M	angiver positionstypen "type" (DocumentPositionType). Enum: [0] = Item [1] = Underelement [2] = Tekst [3] = Booking [9] = Subtotal [10] = Total Forklaringer til de enkelte typer (DocumentPositionTypes) findes efter denne tabel.
AdditionalFields		O
	{...}
CreateDate		M	Tidspunktet, hvor positionen blev oprettet.
ExternalIdentifier		O	Eksternt ID (fra det tidligere system) til interne formål, ikke relevant for skatteopgørelsen.
bruger		O	Oplysninger om den (kasseapparat-)bruger, der har indtastet den pågældende vare.
	{...}
SalesPerson		O	Oplysninger om den pågældende salgsmedarbejder.
	{...}
FiscalAdditionalFields		O

DocumentPositionType

[0] = Vare

Typen "vare" (DocumentPositionItem) er en specifik salgsvare (vare eller tjenesteydelse).

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

DocumentPositionItem-objektet indeholder følgende oplysninger.

Oplysninger i kolonnen "Type":

M ... obligatorisk / påkrævet
M* ... obligatorisk / påkrævet i visse lande eller under visse betingelser
R ... anbefalet
O... valgfrit

Elementer		Type	Beskrivelse
ItemCaption		M	Artikelbetegnelse, beskrivelse af tjenesten
ItemShortCaption		O	Kort navn på varen, der f.eks. anvendes, når der er begrænsninger på tegnlængden, som f.eks. ved regnskabsprintere.
ItemSerialNumber		M*	Varenummeret. Landespecifikke oplysninger: Portugal: Obligatoriske oplysninger
rabatter			Oplysninger om rabatter, prisnedsættelser osv.
	DiscountValue	M	Rabatsum / rabatbeløb Bemærk: hvis DiscountType [1] = discount, skal rabatbeløbet indtastes med 4 decimaler!
	caption	R	Betegnelse for rabatten Landespecifikke oplysninger: Italien: discounts.caption udskrives på kvitteringen som betegnelse for rabatten
	DiscountOrder	M*	Angiver den rækkefølge, hvori rabatten beregnes. Den første rabat, der tages i betragtning, har værdien 0. Skal angives, hvis der anvendes flere rabatter på en vare.
	type	M	Rabattype Enum: [0] = Rabat - Samlet rabat [1] = Rabat – procentvis rabat
	TypeValue	M	Rabatværdi (summen af nedsættelsen) ved [0] = Rabat: DiscountValue (=> DiscountValue = TypeValue) ved [1] = Rabat: procentdelen (f.eks. 10 % rabat)
	PromotionKeys	O	Kampagnenøgler – hvis de anvendes (f.eks. kuponkode)
	identifikator	O	Yderligere identifikator for rabatten (kan f.eks. bruges til at gruppere rabatter i rabat-typer).
type		M	Positions-Typ (DocumentPositionType)
UseSubItemVatCalculation		O	"true", hvis momsberegningen for underposterne (SubItems) skal overtages, og momsen for overordnede post skal ignoreres; ellers "false".
SubItems		O	Detaljer om SubItems. Se: DocumentPositionType [1] = SubItem
	[...]
inhouse		O	Angiver et internt salg eller et eksternt salg (true / false).
ItemGroupId		M*	Artikelgruppeindikator Landespecifikke oplysninger: Danmark: obligatorisk oplysning ("artGroupID" i SAF-T)
ItemGroupCaption		O	Artikelgruppebetegnelse
CostPrice		O/M*	Enhedspris for varen Landespecifikationer: Danmark: kan angives som den enkelte varepris for undervarer. Portugal: obligatorisk oplysning (hvis CostPrice ikke er angivet, beregnes den som: BaseGrossValue / Antal)
itemDateOfEntry		M*	Tidspunkt for oprettelse af varen. Landespecifikke oplysninger: Danmark: obligatoriske oplysninger ("dateOfEntry" i SAF-T). Felterne angiver det tidspunkt, hvor varen først blev oprettet i systemet (oprettelse af stamdata). Hvis disse oplysninger ikke er tilgængelige i POS-systemet, skal følgende værdier anvendes: dateOfEntry: 0001-01-01, timeOfEntry: 00:00:00 og UTC-offset: +00:00 `"itemDateOfEntry": "0001-01-01T00:00:00+00:00"`
mængde		M	Mængdeoplysninger for varen
QuantityUnit		M*	Angivelse af måleenheden Landespecifikationer: Portugal: Kræver angivelse af en måleenhed (“ID” eller “isoCode”)
	ID	M*	Angivelse af måleenheden. Landespecifikationer: Rumænien: Obligatoriske oplysninger
	isoCode	M*	Standardmåleenhed i henhold til ISO/UCUM-koden. Se den linkede artikel for yderligere oplysninger.
ItemId		M	Artiklens ID
ItemType		M*	Beskriver varetypen: varer eller tjenesteydelser. [0] = Vare [1] = Tjenesteydelse Landespecifikke oplysninger: Frankrig: Obligatoriske oplysninger
BaseNetValue		M*	Nettobeløb (ekskl. Vat) før rabat eller tillæg Bemærk: (Netto)summen for linjen/positionen, IKKE for varen. Hvis mængden = 2, er BaseNetValue også vareprisen x 2!
BaseGrossValue		M*	Bruttotal (inkl. Vat) før rabat eller tillæg Bemærk: (Brutto)summen for linjen/positionen, IKKE for varen. Hvis mængden = 2, er BaseGrossValue også vareprisen x 2!
BaseTaxValue		M*	Vat-beløb (eller summen af den første Vat-sats) før rabat eller tillæg Bemærk: (Vat) summen af linjen/positionen, IKKE af varen. Hvis antallet = 2, er BaseTaxValue også vareprisen x 2! Landespecifikationer: Québec (Canada): Føderal afgift GST
BaseTaxValue2		M*	Summen af den anden skattesats for positionen før rabat/tillæg. Landedetaljer: Québec (Canada): Provinsafgift QST
GTIN		O	Global varenummer (GTIN) Landespecifikationer: Portugal: Det anbefales at angive GTIN for den relevante vare. Alternativt anvendes egenskaben "ItemId" i SAF-T.
BusinessTransactionType		M	Type af forretningstransaktion. Enum: [0] = Revenue [1] = Rabat [2] = Pant på tomme flasker [3] = Kupon til ét formål [4] = MultiPurposeVoucher [5] = Drikkepenge [6] = Firmadrikkepenge [7] = Depositum [10] = Udbetaling [11] = PayIn [90] = MoneyTransfer [91] = Kontantforskel [92] = Godkend ægte [93] = Bevilling urealistisk
ItemTypeClassification			ItemTypeClassification kan bruges til at anvende en yderligere klassificering på en vare. ItemTypeClassification kan kun angives, hvis egenskaben ‘ItemType’ er sat til "[0] - Artikel" eller “ItemType”: 0. Detaljerede oplysninger om egenskaben "ItemTypeClassification" findes i den linkede artikel. Følgende klassifikationer er tilgængelige. [1] = Alkoholholdig drik [5] = TobaccoProducts [10] = Benzin [11] = Ethanolbrændstof til biler [12] = dieselbrændstof [13] = fedtsyremethylester [14] = Dieselbrændstof til landbrugs- og fiskeribrug [15] = Naturgas til transport [16] = Flydende gas til transport [17] = Brændstof til transport, ikke andetsteds klassificeret Landespecifikationer: FiscalCountryProperties: Kravet om at definere ItemTypeClassification er angivet i fiscalCountryProperties via egenskaben itemTypeClassificationRequired. Hvis værdien er “true”, skal varen klassificeres – forudsat at det er en særlig vare (!). supportedItemTypeClassification definerer, for hvilken type produkt egenskaben kan indstilles.
VatIdentification		M	ID for Vat. Kan hentes via GET /api/v1/information/client/ {clientId}/getVatIdentification ved at angive momssatsen for det pågældende land.
VatPercent		M	Vat i procent eller den første skattesats, der gælder for varen i det pågældende land. Landespecifikke oplysninger: Québec (Canada): Føderal afgift GST
VatPercent2		M*	Den anden skattesats, der gælder for varen, udtrykt i procent i det pågældende land. Landedetaljer: Québec (Canada): Provinsafgift QST
NetValue		M	Nettotal for positionen (fratrukket eventuelle rabatter / plus tillæg) – ekskl. Vat. Skal altid angives.
GrossValue		M	Bruttotal for positionen (minus eventuelle rabatter / plus tillæg) – inkl. Vat. Skal altid angives.
TaxValue		M	Vat-beløb (eller summen af den første Vat-sats) for varen (fratrukket eventuelle rabatter / tillagt eventuelle tillæg) Skal altid angives. Landespecifikke oplysninger: Québec (Canada): Føderal afgift GST
TaxValue2		M*	Summen af varens anden skattesats efter rabat/tillæg. Landespecifikationer: Québec (Canada): Provinsafgift QST
AccountingIdentifier		O	Yderligere identifikator til regnskabsmæssige formål (regnskabsgrænseflade)
ItemTaxType		M*	Skatteklasse for posten: leverancer tjenesteydelser Landoplysninger: Spanien: Skal angives ved fakturering til ikke-spanske kunder.
PositionNumber		M	Positionsnummer, der starter med 0
positionReference		O	Angivelse af et positionsnummer, der skal henvises til
cancellationPosition		O	"true", hvis denne position annullerer en position i et andet dokument; ellers "false"
CreateDate		O	Tidspunkt for registrering af positionen

[1] = SubItem

"Underposter" (DocumentPositionSubItem) giver mulighed for at beskrive sammensætningen af solgte produkter eller produktgruppebeskrivelser på vareniveau.

Eksempel: Menu = Cola og hamburger.

SubItems har en forklarende karakter og behøver ikke at blive brugt. De har heller ingen indflydelse på pris, salg eller moms.

Bemærk: "SubItem"-posten svarer til "Item"-posten, men indeholder ikke elementerne "UseSubItemVatCalculation" og "SubItems".

[2] = Tekst

Bruges til at angive placeringen af en tekst eller en Barcode i dokumentet.

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

DocumentPositionText-objektet indeholder følgende oplysninger.

Oplysninger i kolonnen "Type":

M ... obligatorisk / påkrævet
M* ... obligatorisk / påkrævet i visse lande eller under visse betingelser
R ... anbefalet
O... valgfrit

Elementer	Type	Beskrivelse
type	M	Positions-type (DocumentPositionType)
tekst	O	Felt til fritekst Landespecifikationer: Italien EPSON-printere: sendes til printeren som messageType="4" (Body Lines); maks. 38 tegn pr. tekstposition er muligt. Efter 25 tegn sker der et automatisk linjeskift. Tekst på flere linjer skal opdeles i flere positioner. Alternativt kan der anvendes yderligere header- og Footer-tekster . Hvis der ikke sker et linjeskift efter 25 tegn, men teksten i stedet afkortes, bedes du kontakte din printertekniker (søgeord: ‘RT DESCR. OVERLAP’).
barcodeType	O	Angivelse af Barcode-type Enum: ean8 ean13 code128
Barcode	O	Barcode-data
PositionNumber	M	Positionsnummer, der starter med 0

[3] = Booking

Reservationspositioner (DocumentPositionBooking) bruges til indbetalinger, udbetalinger samt salg af multifunktionelle kuponer (PayIn, payOut, MultiPurposeVoucher, ...).

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

DocumentPositionBooking-objektet indeholder følgende oplysninger.

Oplysninger i kolonnen "Type":

M ... obligatorisk / påkrævet
M* ... obligatorisk / påkrævet i visse lande eller under visse betingelser
R ... anbefalet
O... valgfrit

Elementer	Type	Beskrivelse
type	M	Positions-type (DocumentPositionType)
caption	M	Beskrivelse af reservationspositionen
identifikator	O	Indikator for yderligere ID for bogføringen
BusinessTransactionType	M	Type forretningstransaktion. Enum: [0] = Revenue [1] = Rabat [2] = Pant på tomme flasker [3] = Kupon til ét formål [4] = MultiPurposeVoucher [5] = Drikkepenge [6] = Firmadrikkepenge [7] = Depositum [10] = Udbetaling [11] = PayIn [90] = MoneyTransfer [91] = Kontantforskel [92] = Godkend ægte [93] = Bevilling uægte
PayOutType	M*	Angiver udbetalingstypen. Påkrævet i visse lande. Mulige værdier: [0] = Rengøringsmateriale [1] = Kontorartikler [2] = PostalFee [3] = Løn [4] = Løn [5] = Indkøb af varer [6] = Andre omkostninger Landespecifikke oplysninger: Danmark: Obligatorisk oplysning ("reportPayOut" "PayOutType" i SAF-T). Et stringelement (string36), der bruges til at angive udbetalingstypen. Bemærk: Nyt fra DOM v1.2.0 / Client v1.7.6
VatIdentification	M	Vat-ID. Kan hentes via GET /api/v1/information/client/ {clientId}/getVatIdentification ved angivelse af det pågældende lands momssats.
VatPercent	M	Vat in percent
NetValue	M	Nettotal for positionen (fratrukket eventuelle rabatter) – ekskl. Vat. Skal altid angives.
GrossValue	M	Bruttotal for positionen (fratrukket eventuelle rabatter) – inkl. Vat. Skal altid angives.
TaxValue	M	Vat-beløb for varen (fratrukket eventuelle rabatter) Skal altid angives.
AccountingIdentifier	O	Yderligere identifikator til regnskabsmæssige formål (regnskabsgrænseflade)
ItemTaxType	M*	Skatteklasse for positionen: leverancer tjenesteydelser Landoplysninger: Spanien: Skal angives ved fakturering til ikke-spanske kunder.
PositionNumber	M	Positionsnummer, der starter med 0
positionReference	O	Angivelse af et varenummer, der skal henvises til
cancellationPosition	O	"true", hvis denne position annullerer en position i et andet dokument; ellers "false".
DeletedPosition	O	"true", hvis denne position blev slettet; ellers "false".
CreateDate	O	Tidspunkt for registrering af positionen

[9] = SubTotal

Subtotal-position

Bemærk: Positionen "SubTotal" svarer til positionen "Total".

[10] = Total

Totalposition. Hvis DocumentPositionTotal anvendes, skal den altid være den sidste position i dokumentet (højeste PositionNumber).

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

DocumentPositionTotal-objektet indeholder følgende oplysninger.

Oplysninger i kolonnen "Type":

M ... obligatorisk / påkrævet
M* ... obligatorisk / påkrævet i visse lande eller under visse betingelser
R ... anbefalet
O... valgfrit

Elementer		Type	Beskrivelse
type		M	Positions-type (DocumentPositionType)
afrunding		O	Afrunding anvendes. Hvis summen af positioner (bruttoværdi) ikke svarer til betalingssummen. F.eks. vil 0,01 tillade afrundingsforskelle på +/-0,01 Bemærk: Brug denne funktion med forsigtighed. Høje værdier vil deaktivere beløbsvalidering for betalingsbeløb / dokumentets bruttoværdi
BaseValue		M*	Postens basisbeløb før anvendelse af rabatter (kun hvis der anvendes rabatter)
value		M	Positionsværdien inklusive rabatter.
rabatter			Oplysninger om rabatter, prisnedsættelser osv.
	DiscountValue	M	Rabatsum / rabatbeløb Bemærk: hvis DiscountType [1] = rabat, skal rabatbeløbet indtastes med 4 decimaler!
	caption	O	Betegnelse for rabatten
	DiscountOrder	M*	Angiver den rækkefølge, hvori rabatten beregnes. Den første rabat, der tages i betragtning, har værdien 0. Skal angives, hvis der anvendes flere rabatter på en vare.
	type	M	Rabattype Enum: [0] = Rabat – samlet rabat [1] = Rabat - procentvis rabat
	TypeValue	M	Rabatværdi (summen af nedsættelsen) ved [0] = Rabat: DiscountValue ved [1] = Rabat: procentdelen (f.eks. 10 % rabat)
	PromotionKeys	O	Kampagnenøgler – hvis de anvendes (f.eks. kuponkode)
	identifikator	O	Yderligere identifikator for rabatten (kan f.eks. bruges til at gruppere rabatter i rabat-typer).
caption		O	Betegnelsen for positionen
PositionNumber		M	Stillingsnummer, der starter med 0
positionReference		O	Angivelse af et positionsnummer, der skal henvises til
cancellationPosition		O	"true", hvis denne position annullerer en position i et andet dokument; ellers "false".
DeletedPosition		O	"true", hvis denne position blev slettet; ellers "false".
CreateDate		O	Tidspunkt for registrering af positionen

Denne artikel er oversat automatisk.

DocumentPositionsBase

DocumentPositionType

[0] = Vare

[1] = SubItem

[2] = Tekst

[3] = Booking

[9] = SubTotal

[10] = Total

Relaterede artikler