Oggetto «positions» – RetailForce

Il presente articolo tratta dell’oggetto «positions» all’interno dell’oggetto «Document» (oggetto «Document»).

Una descrizione completa del RetailForce DOM (Document Object Model), nonché una descrizione dei singoli elementi, è disponibile nell’area download del sito web di RetailForce (Documentazione sul modello a oggetti.pdf) nella rispettiva directory delle versioni.

L’oggetto «positions» contiene informazioni relative alla rispettiva posizione del documento.

L’oggetto «positions» è costituito da:

DocumentPositionBase – contiene le informazioni di base sulla posizione (indipendentemente dal tipo della rispettiva posizione)
Informazioni specifiche relative al tipo di posizione: a seconda del «tipo» di posizione (DocumentPositionType), è necessario specificare contenuti diversi (il tipo di posizione definisce il contenuto della posizione).

DocumentPositionsBase

L’oggetto seguente contiene dati di esempio.

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

L’oggetto DocumentPositionsBase contiene le seguenti informazioni.

Informazioni nella colonna «Type»:

M ... obbligatorio / richiesto
M* ... obbligatorio / richiesto in determinati paesi o a determinate condizioni
R ... raccomandato
O... facoltativo

Elementi		Tipo	Descrizione
PositionNumber		M	Numero progressivo della posizione. Si noti che il numero della prima posizione è sempre "0".
positionReference		O	Riferimento a un’altra posizione all’interno del documento. Equivalente a documentReference.
	{...}	O
cancellationPosition		M	"true" se questa posizione annulla una posizione di un altro documento; altrimenti "false".
DeletedPosition		O	"true" se questa posizione è stata eliminata; altrimenti "false".
tipo		M	specifica il tipo di posizione "type" (DocumentPositionType). Enum: [0] = Item [1] = Sottoelemento [2] = Testo [3] = Prenotazione [9] = Totale parziale [10] = Totale Le spiegazioni relative ai singoli tipi (DocumentPositionTypes) sono riportate dopo questa tabella.
AdditionalFields		O
	{...}
CreateDate		M	Ora di creazione della posizione.
ExternalIdentifier		O	ID esterno (proveniente dal sistema precedente), a fini interni, non rilevante ai fini fiscali.
utente		O	Dettagli dell’utente (del registratore di cassa) che ha inserito la rispettiva voce.
	{...}
SalesPerson		O	Dettagli relativi al personale di vendita della rispettiva posizione.
	{...}
FiscalAdditionalFields		O

DocumentPositionType

[0] = Articolo

Il tipo "voce" (DocumentPositionItem) indica una voce di vendita specifica (bene o servizio).

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

L’oggetto DocumentPositionItem contiene le seguenti informazioni.

Informazioni nella colonna «Tipo»:

M ... obbligatorio / richiesto
M* ... obbligatorio / richiesto in determinati paesi o a determinate condizioni
R ... raccomandato
O... facoltativo

Elementi		Tipo	Descrizione
ItemCaption		M	Denominazione della voce, descrizione del servizio
ItemShortCaption		O	Nome abbreviato della voce, utilizzato ad esempio in caso di limitazioni relative alla lunghezza dei caratteri, come nel caso delle stampanti fiscali.
ItemSerialNumber		M*	Numero di serie dell’articolo. Dettagli relativi al Paese: Portogallo: Informazioni obbligatorie
sconti			Dettagli relativi a sconti, riduzioni di prezzo, ecc.
	DiscountValue	M	Importo dello sconto / importo del ribasso Attenzione: se DiscountType [1] = discount, l’importo dello sconto deve essere inserito con 4 cifre decimali!
	caption	R	Denominazione dello sconto Dettagli per paese: Italia: sullo scontrino viene stampata la dicitura «sconti.caption» come denominazione dello sconto
	DiscountOrder	M*	Indica l’ordine di calcolo degli sconti. Il primo sconto preso in considerazione ha valore 0. Tale parametro deve essere specificato qualora a un articolo vengano applicati più sconti.
	tipo	M	Tipo di sconto Enum: [0] = Sconto forfettario - Sconto cumulativo [1] = Sconto - Sconto percentuale
	TypeValue	M	Valore dello sconto (somma della riduzione) nel caso di [0] = Sconto: il DiscountValue (=> DiscountValue = TypeValue) se [1] = Sconto: la percentuale (ad es. sconto del 10%)
	PromotionKeys	O	PromotionKeys – se applicate (es. codice promozionale)
	identificatore	O	Identificatore aggiuntivo per lo sconto (utilizzabile, ad esempio, per raggruppare gli sconti in tipologie di sconto).
tipo		M	Tipo di posizione (DocumentPositionType)
UseSubItemVatCalculation		O	"true" se si desidera riprendere il calcolo dell'IVA delle voci secondarie (SubItems) e ignorare l'IVA della voce principale; in caso contrario, "false".
SubItems		O	Dettagli relativi ai SubItems. Vedi: DocumentPositionType [1] = SubItem
	[...]
inHouse		O	Indica una vendita interna o una vendita esterna (true / false).
ItemGroupId		M*	Indicatore del gruppo di articoli Dettagli sul Paese: Danimarca: informazione obbligatoria («artGroupID» in SAF-T)
ItemGroupCaption		O	Denominazione del gruppo di articoli
CostPrice		O/M*	Prezzo unitario dell’articolo Dettagli sul Paese: Danimarca: può essere configurato come prezzo unitario per le sottovoci. Portogallo: informazione obbligatoria (se non specificato, il CostPrice viene calcolato come segue: BaseGrossValue / Quantità)
itemDateOfEntry		M*	Data e ora di creazione dell’articolo. Dettagli per paese: Danimarca: informazioni obbligatorie (“dateOfEntry” in SAF-T). I campi indicano il momento in cui la voce è stata creata per la prima volta nel sistema (creazione dei dati anagrafici). Se tali informazioni non sono disponibili nel sistema POS, è necessario utilizzare i seguenti valori: dateOfEntry: 0001-01-01, timeOfEntry: 00:00:00 e UTC-offset: +00:00 `"itemDateOfEntry": "0001-01-01T00:00:00+00:00"`
quantità		M	Informazioni sulla quantità relative all’articolo
QuantityUnit		M*	Specificazione dell’unità di misura Dettagli sul Paese: Portogallo: richiede la specificazione di un'unità di misura (“ID” o “isoCode”)
	ID	M*	Indicazione dell’unità di misura. Dettagli sul Paese: Romania: Informazioni obbligatorie
	isoCode	M*	Unità di misura standard secondo il codice ISO/UCUM. Per ulteriori informazioni, si rimanda all’articolo collegato.
ID articolo		M	ID dell'articolo
ItemType		M*	Descrive la categoria dell'articolo: beni o servizi. [0] = Articolo [1] = Servizio Dettagli sul Paese: Francia: Informazioni obbligatorie
BaseNetValue		M*	Totale netto (IVA esclusa) prima di sconti o maggiorazioni Attenzione: si tratta della somma (netta) della riga/voce, NON dell’articolo. Se la quantità è pari a 2, anche il valore BaseNetValue corrisponde al prezzo unitario moltiplicato per 2.
BaseGrossValue		M*	Totale lordo (IVA inclusa) prima di sconti o maggiorazioni Attenzione: si tratta della somma (lorda) della riga/voce, NON dell’articolo. Se la quantità è pari a 2, anche il valore lordo di base (BaseGrossValue) è pari al prezzo unitario moltiplicato per 2!
BaseTaxValue		M*	Totale IVA (o somma della prima aliquota fiscale) al lordo di sconti o maggiorazioni Attenzione: somma (del Vat) della riga/posizione, NON dell’articolo. Se la quantità è pari a 2, anche il BaseTaxValue è pari al prezzo unitario moltiplicato per 2! Dettagli sul Paese: Québec (Canada): imposta federale GST
BaseTaxValue2		M*	Somma della seconda aliquota fiscale della posizione al lordo di sconti/supplementi. Dettagli sul Paese: Québec (Canada): Imposta provinciale QST
GTIN		O	Codice globale dell’articolo (GTIN) Dettagli sul Paese: Portogallo: Si raccomanda di specificare il GTIN relativo all’articolo in questione. In alternativa, nel file SAF-T si utilizza la proprietà “ItemId”.
BusinessTransactionType		M	Tipo di transazione commerciale. Enum: [0] = Revenue [1] = Sconto [2] = Deposito sui vuoti [3] = Buono monouso [4] = MultiPurposeVoucher [5] = Mancia [6] = Mancia aziendale [7] = Cauzione [10] = Pagamento [11] = PayIn [90] = MoneyTransfer [91] = Differenza di contanti [92] = Concessione autentica [93] = Concessione irreale
ItemTypeClassification			La proprietà «ItemTypeClassification» può essere utilizzata per applicare un’ulteriore classificazione a un articolo. ItemTypeClassification può essere impostata solo se la proprietà «ItemType» è stata configurata su «[0] - Articolo» o «ItemType»: 0. Informazioni dettagliate sulla proprietà "ItemTypeClassification" sono disponibili nell’articolo collegato. Sono disponibili le seguenti classificazioni. [1] = Bevanda alcolica [5] = Prodotti del tabacco [10] = Benzina [11] = Carburante a base di etanolo per autoveicoli [12] = Carburante diesel [13] = Estere metilico di acidi grassi [14] = Carburante diesel destinato all’uso agricolo e ittico [15] = Gas naturale per autotrazione [16] = Gas di petrolio liquefatto per il trasporto [17] = Carburante per i trasporti non classificato altrove Dettagli relativi al Paese: FiscalCountryProperties: L’obbligo di definire la classificazione ItemTypeClassification è specificato nelle FiscalCountryProperties tramite la proprietà itemTypeClassificationRequired. Se il valore è “true”, la voce deve essere classificata – a condizione che si tratti di una voce speciale (!). La proprietà supportedItemTypeClassification definisce per quale tipo di prodotto è possibile impostare tale proprietà.
VatIdentification		M	ID dell’aliquota Vat. Può essere recuperato tramite una richiesta GET a /api/v1/information/client/{clientId}/getVatIdentification, specificando l’aliquota VAT del rispettivo Paese.
VatPercent		M	Aliquota IVA in percentuale o prima aliquota fiscale applicabile all’articolo nel rispettivo paese. Dettagli sul Paese: Québec (Canada): imposta federale GST
VatPercent2		M*	seconda aliquota fiscale applicabile all’articolo, espressa in percentuale nel rispettivo Paese. Dettagli sul Paese: Québec (Canada): imposta provinciale QST
NetValue		M	Totale netto della voce (al netto di eventuali sconti / al lordo di eventuali supplementi) – IVA esclusa. Deve essere sempre indicato.
GrossValue		M	Totale lordo della posizione (al netto di eventuali sconti / al lordo di eventuali supplementi) – IVA inclusa. Deve essere sempre indicato.
TaxValue		M	Totale IVA (o somma della prima aliquota fiscale) della voce (al netto di eventuali sconti / al lordo di eventuali maggiorazioni) Deve essere sempre indicato. Dettagli sul Paese: Québec (Canada): imposta federale GST
TaxValue2		M*	Somma della seconda aliquota fiscale della voce al netto di sconti/supplementi. Dettagli sul Paese: Québec (Canada): Imposta provinciale QST
AccountingIdentifier		O	Identificatore aggiuntivo a fini contabili (interfaccia contabile)
ItemTaxType		M*	Tipo di imposta della posizione: consegne servizi Dettagli sul Paese: Spagna: deve essere specificato in caso di fatturazione a clienti non spagnoli.
PositionNumber		M	Numero di posizione, a partire da 0
positionReference		O	Specificazione di un numero di posizione a cui si deve fare riferimento
cancellationPosition		O	"true" se questa posizione annulla una posizione di un altro documento; altrimenti "false"
CreateDate		O	Ora di registrazione della posizione

[1] = SubItem

I "sottoelementi" (DocumentPositionSubItem) consentono di specificare la composizione dei prodotti venduti o le descrizioni dei gruppi di prodotti a livello di articolo.

Esempio: Menu = Coca-Cola e hamburger.

SubItems hanno carattere esplicativo e non è obbligatorio utilizzarli. Inoltre, non hanno alcun effetto in relazione al prezzo, alle vendite o all’imposta sul valore aggiunto.

Nota: la voce «SubItem» corrisponde alla voce «Item», ma non include gli elementi «UseSubItemVatCalculation» e «SubItems».

[2] = Testo

Utilizzato per specificare la posizione di un testo o di un Barcode all’interno del documento.

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

L’oggetto DocumentPositionText contiene le seguenti informazioni.

Informazioni nella colonna "Type":

M ... obbligatorio / richiesto
M* ... obbligatorio / richiesto in determinati paesi o in determinate condizioni
R ... raccomandato
O... facoltativo

Elementi	Tipo	Descrizione
tipo	M	Tipo di posizione (DocumentPositionType)
testo	O	Campo di testo libero Dettagli sul Paese: Stampanti EPSON in Italia: inviate alla stampante come messageType="4" (righe del corpo); sono possibili al massimo 38 caratteri per ogni posizione di testo. Dopo 25 caratteri, si verifica un'interruzione di riga automatica. Il testo su più righe deve essere suddiviso in più posizioni. In alternativa, è possibile utilizzare testi aggiuntivi di header e Footer . Se dopo 25 caratteri non si verifica un'interruzione di riga, ma il testo viene invece troncato, si prega di contattare il tecnico dell'assistenza della stampante (parola chiave: «RT DESCR. OVERLAP»).
barcodeType	O	Indicazione del tipo di Barcode Enum: EAN8 EAN13 code128
Barcode	O	Dati del Barcode
PositionNumber	M	Numero di posizione, a partire da 0

[3] = Prenotazione

Le posizioni relative alle prenotazioni (DocumentPositionBooking) vengono utilizzate per depositi, prelievi e vendite di buoni multiuso (PayIn, payOut, MultiPurposeVoucher, ...).

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

L’oggetto DocumentPositionBooking contiene le seguenti informazioni.

Informazioni nella colonna «Tipo»:

M ... obbligatorio / richiesto
M* ... obbligatorio / richiesto in determinati paesi o a determinate condizioni
R ... raccomandato
O... facoltativo

Elementi	Tipo	Descrizione
tipo	M	Tipo di posizione (DocumentPositionType)
didascalia	M	Descrizione della posizione di prenotazione
identificatore	O	Indicatore di ID aggiuntivo della prenotazione
BusinessTransactionType	M	Tipo di transazione commerciale. Enum: [0] = Revenue [1] = Sconto [2] = Deposito sui vuoti [3] = Buono monouso [4] = MultiPurposeVoucher [5] = Mancia [6] = Mancia aziendale [7] = Cauzione [10] = Pagamento [11] = PayIn [90] = MoneyTransfer [91] = Differenza di contanti [92] = Concessione autentica [93] = Concessione irreale
PayOutType	M*	Indica il tipo di pagamento. Obbligatorio in alcuni paesi. Valori possibili: [0] = CleaningMaterial [1] = Forniture per ufficio [2] = Spese postali [3] = Stipendio [4] = Retribuzione [5] = Acquisto di merci [6] = Altri costi Dettagli sul Paese: Danimarca: Informazioni obbligatorie ("reportPayOut" "PayOutType" in SAF-T). Un elemento di tipo stringa (string36) utilizzato per indicare il tipo di pagamento. Nota: Novità a partire dalla versione DOM v1.2.0 / Client v1.7.6
VatIdentification	M	ID dell’aliquota VAT. Può essere recuperato tramite una richiesta GET su /api/v1/information/client/{clientId}/getVatIdentification, specificando l’aliquota VAT del Paese di interesse.
VatPercent	M	Aliquota VAT in percentuale
NetValue	M	Totale netto della voce (al netto di eventuali sconti) – IVA esclusa. Deve essere sempre indicato.
GrossValue	M	Totale lordo della posizione (al netto di eventuali sconti) – IVA inclusa. Deve essere sempre indicato.
TaxValue	M	Totale IVA della posizione (al netto di eventuali sconti) Deve essere sempre indicato.
AccountingIdentifier	O	Identificatore aggiuntivo a fini contabili (interfaccia contabile)
ItemTaxType	M*	Tipo di imposta della posizione: consegne servizi Dettagli sul Paese: Spagna: deve essere specificato in caso di fatturazione a clienti non spagnoli.
PositionNumber	M	Numero di posizione, a partire da 0
positionReference	O	Specificazione del numero di una voce a cui si deve fare riferimento
cancellationPosition	O	"true" se questa posizione annulla una posizione di un altro documento; altrimenti "false".
DeletedPosition	O	"true" se questa posizione è stata eliminata; altrimenti "false".
CreateDate	O	Timestamp di creazione della posizione

[9] = Totale parziale

Posizione "SubTotal"

Nota: la voce «Totale parziale» corrisponde alla voce «Totale».

[10] = Totale

Posizione "Totale". Se si impiega DocumentPositionTotal, questa deve sempre essere l'ultima posizione nel documento (il PositionNumber più alto).

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

L’oggetto DocumentPositionTotal contiene le seguenti informazioni.