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 informazioni di base sulla posizione (indipendentemente dal tipo della posizione in questione)
- 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 stessa).
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 «Tipo»:
- 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 pari a "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:
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 relativi all’utente (del registratore di cassa) che ha inserito la rispettiva voce. | |
| {...} | |||
| SalesPerson | O | Dettagli relativi all’operatore addetto alla 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": "Quantity"
},
"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 riportate 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 Dettagli sul Paese:
|
|
| ItemShortCaption | O | Denominazione abbreviata dell’articolo, utilizzata 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:
|
|
| 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:
|
|
| DiscountOrder | M* |
Indica l’ordine di calcolo dello sconto. 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:
|
|
| 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 | Promotion Keys – se applicate (ad 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 voce (DocumentPositionType) | |
| UseSubItemVatCalculation | O | "true" se si desidera riprendere il calcolo dell’IVA delle sottovoci (SubItems) e ignorare l’IVA della voce principale; in caso contrario "false". Impostazione predefinita (se non specificata): "true". Se impostato su "true", ogni sottovoce deve essere dotata di VatIdentification e la somma dei valori lordi, netti e fiscali delle sottovoci deve corrispondere ai valori baseGrossValue, BaseNetValue e BaseTaxValue della voce principale; in caso contrario, il documento viene rifiutato. | |
| SubItems | O | Dettagli delle 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 relativi al Paese:
|
|
| ItemGroupCaption | O |
Designazione del gruppo di articoli Dettagli per paese:
|
|
| CostPrice | O/M* |
Costo unitario dell’articolo Dettagli per paese:
|
|
| itemDateOfEntry | M* |
Data e ora di creazione dell’articolo. Dettagli per paese:
|
|
| quantità | M |
Informazioni sulla quantità relative all’articolo Dettagli relativi al Paese:
|
|
| QuantityUnit | M* |
Specificazione dell’unità di misura Dettagli per paese:
|
|
| ID | M* |
Indicazione dell’unità di misura. Dettagli per paese:
|
|
| isoCode | M* |
Unità di misura standard, trasmessa come denominazione di un valore QuantityUnitIsoCode (ad es. «Quantity» per i pezzi, «Kilogram»), e non come codice ISO/UCUM effettivo. Il modulo converte tale denominazione nel corrispondente codice ISO/UCUM (ad es. «Quantity» = «1»). Un valore numerico viene interpretato come l’identificativo numerico dell’enum, pertanto “1” corrisponde a “Percent”. Per ulteriori dettagli, si rinvia all’articolo collegato. Dettagli sul Paese:
|
|
| ItemId | M |
ID dell’articolo Dettagli sul Paese:
|
|
| ItemType | M* |
Descrive la tipologia di voce: beni o servizi.
Dettagli sul Paese:
|
|
| BaseNetValue | M* |
Totale netto (IVA esclusa) prima di sconti o supplementi
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
Si tratta
della somma lorda della riga/posizione, 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:
|
|
| BaseTaxValue2 | M* |
Somma della seconda aliquota fiscale della posizione al lordo di sconti/maggiorazioni. Dettagli sul Paese:
|
|
| GTIN | O/R |
Codice globale dell’articolo commerciale (GTIN) Dettagli sul Paese:
|
|
| BusinessTransactionType | M |
Tipo di transazione commerciale. Enum:
|
|
| ItemTypeClassification | O/M* |
La proprietà «ItemTypeClassification» può essere utilizzata per applicare un’ulteriore classificazione a un articolo. La proprietà «ItemTypeClassification» può essere impostata solo se la proprietà «ItemType» è stata impostata su «[0] - Articolo» o su «ItemType»: 0. Informazioni dettagliate sulla proprietà "ItemTypeClassification" sono disponibili nell’articolo collegato. Sono disponibili le seguenti classificazioni.
Dettagli relativi al Paese:
|
|
| VatIdentification | M |
ID dell’aliquota Vat. Può essere interrogato tramite GET /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:
|
|
| VatPercent2 | M* |
seconda aliquota fiscale applicabile all’articolo, espressa in percentuale nel rispettivo Paese. Dettagli sul Paese:
|
|
| NetValue | M |
Valore netto della voce (al netto di eventuali sconti / al lordo di eventuali supplementi) – IVA esclusa. Tale valore deve essere sempre riportato. |
|
| GrossValue | M |
Valore lordo della posizione (al netto di eventuali sconti / al lordo di eventuali maggiorazioni) – IVA inclusa. Deve essere sempre indicato. |
|
| TaxValue | M |
Totale IVA (o somma della prima aliquota fiscale) della posizione (al netto di eventuali sconti / al lordo di eventuali maggiorazioni) Deve essere sempre indicato. Dettagli sul Paese:
|
|
| TaxValue2 | M* |
Somma dell’aliquota fiscale secondaria dell’articolo al netto di sconti/supplementi. Dettagli sul Paese:
|
|
| AccountingIdentifier | O | Identificatore aggiuntivo a fini contabili (interfaccia contabile) | |
| ItemTaxType | M* |
Tipo di imposta della posizione:
Dettagli sul Paese:
|
|
| 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/M* | "true" se questa posizione annulla una posizione di un altro documento; altrimenti "false" | |
| CreateDate | O | Ora di registrazione della posizione | |
[1] = Sottovoce
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.
L’utilizzo dei SubItems non è obbligatorio. Se la voce principale presenta la proprietà “UseSubItemVatCalculation”: true (impostazione predefinita), viene applicata l’IVA dei SubItems anziché quella della voce principale e i loro valori devono sommarsi ai valori di base della voce principale. Con “UseSubItemVatCalculation”: false, si applica l’IVA della voce principale e i SubItems servono esclusivamente a descrivere la composizione della voce.
[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:
|
|
| barcodeType | O |
Indicazione del tipo di Barcode Enum:
|
|
| 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": "Deposit",
"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 registrazione | |
| BusinessTransactionType | M |
Tipo di transazione commerciale. Enum:
|
|
| PayOutType | M* |
Indica la modalità di pagamento. Obbligatorio in alcuni paesi. Valori possibili:
Dettagli sul Paese:
Nota:
Novità a partire dalla versione DOM v1.2.0 / Client v1.7.6
|
|
| VatIdentification | M |
ID dell’aliquota VAT. È possibile recuperarlo tramite GET /api/v1/information/client/{clientId}/getVatIdentification, specificando l’aliquota VAT del rispettivo Paese. |
|
| VatPercent | M | Aliquota VAT in percentuale | |
| NetValue | M |
Valore netto della voce (al netto di eventuali sconti) – IVA esclusa. Tale valore deve essere sempre riportato. |
|
| GrossValue | M |
Valore lordo della posizione (al netto di eventuali sconti) – IVA inclusa. Deve essere sempre indicato. |
|
| TaxValue | M |
Imponibile 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:
Dettagli sul Paese:
|
|
| 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 | Ora di registrazione della posizione | |
[9] = Totale parziale
Posizione "SubTotal"
[10] = Totale
Posizione "Totale". Se si impiega DocumentPositionTotal, tale posizione deve sempre essere l’ultima nel documento (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.
Informazioni nella colonna «Type»:
- 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) | |
| arrotondamento | O |
arrotondamento applicato. Se la somma delle posizioni (valore lordo) non corrisponde all’importo del pagamento. L’arrotondamento viene aggiunto alla somma dei valori lordi delle voci e delle posizioni contabili, e la somma dei pagamenti deve corrispondere esattamente al risultato. Si tratta di un importo con segno, non di una tolleranza: ad esempio, -0,02 significa che i pagamenti sono inferiori di 0,02 rispetto alla somma lorda delle posizioni, mentre 0,01 significa che sono esattamente superiori di 0,01. Nota: si raccomanda di utilizzare con attenzione. Se i pagamenti e le voci non differiscono esattamente di questo valore, il documento viene rifiutato. |
|
| BaseValue | M* | Importo base della posizione prima dell’applicazione degli sconti (solo se vengono applicati sconti) | |
| valore | M | Valore della posizione comprensivo degli sconti. | |
| sconti | Dettagli relativi a sconti, riduzioni di prezzo, ecc. | ||
| DiscountValue | M |
Importo dello sconto / importo del rimborso
Attenzione:
se DiscountType [1] = discount, l’importo dello sconto deve essere inserito con 4 cifre decimali.
|
|
| caption | O | 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:
|
|
| TypeValue | M |
Valore dello sconto (somma della riduzione) nel caso di [0] = Sconto: il DiscountValue 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). | |
| didascalia | O | La denominazione della posizione | |
| PositionNumber | M | Numero della 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". | |
| DeletedPosition | O | "true" se questa posizione è stata eliminata; altrimenti "false". | |
| CreateDate | O | Timestamp di creazione della posizione | |
Questo articolo è stato tradotto automaticamente.
Commenti
0 commenti
Accedi per aggiungere un commento.