Objeto «positions» – RetailForce

Este artigo aborda o objeto «positions» no âmbito do objeto «Document» (objeto «Document»).

Pode encontrar uma descrição completa do RetailForce DOM (Document Object Model), bem como uma descrição dos elementos individuais, na área de downloads do RetailForce website (Documentação do modelo de objetos.pdf), no respetivo diretório de versões.

O objeto «positions» contém informações sobre a respetiva posição do documento.

O objeto «positions» é composto por:

DocumentPositionBase — contém informações básicas sobre a posição (independentemente do tipo da respetiva posição)
Informações específicas do tipo de posição — dependendo do «tipo» de posição (DocumentPositionType), devem ser especificados conteúdos diferentes (o tipo de posição define o conteúdo da posição).

DocumentPositionsBase

O objeto a seguir contém dados de exemplo.

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

O objeto DocumentPositionsBase contém as seguintes informações.

Informações na coluna «Tipo»:

M ... obrigatório / exigido
M* ... obrigatório / exigido em determinados países ou sob determinadas condições
R ... recomendado
O... opcional

Elementos		Tipo	Descrição
PositionNumber		M	Número de sequência da posição. Atenção: O número da primeira posição é sempre «0»!
positionReference		O	Referência a outra posição no documento. Equivalente a documentReference.
	{...}	O
cancellationPosition		M	«true» se esta posição anular uma posição de outro documento; caso contrário, «false».
DeletedPosition		O	«true» se esta posição tiver sido eliminada; caso contrário, «false».
type		M	especifica o tipo de posição «type» (DocumentPositionType). Enumeração: [0] = Item [1] = Subitem [2] = Texto [3] = Reserva [9] = Subtotal [10] = Total As explicações relativas aos tipos individuais (DocumentPositionTypes) encontram-se a seguir a esta tabela.
AdditionalFields		O
	{...}
CreateDate		M	Hora em que a posição foi criada.
ExternalIdentifier		O	ID externo (do sistema anterior), para fins internos, não relevante para efeitos de fiscalização.
user		O	Dados do utilizador (da caixa registadora) que introduziu o respetivo artigo.
	{...}
SalesPerson		O	Detalhes do funcionário de vendas do respetivo cargo.
	{...}
FiscalAdditionalFields		O

DocumentPositionType

[0] = Artigo

O tipo «artigo» (DocumentPositionItem) refere-se a um artigo de vendas específico (bens ou serviços).

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

O objeto DocumentPositionItem contém as seguintes informações.

Informações na coluna «Tipo»:

M ... obrigatório / exigido
M* ... obrigatório / exigido em determinados países ou sob determinadas condições
R ... recomendado
O... opcional

Elementos		Tipo	Descrição
ItemCaption		M	Designação do artigo, descrição do serviço
ItemShortCaption		O	Nome abreviado do item, utilizado, por exemplo, quando existem restrições quanto ao número de caracteres, como no caso das impressoras fiscais.
ItemSerialNumber		M*	Número de série do item. Detalhes do país: Portugal: Informações obrigatórias
descontos			Detalhes sobre descontos, reduções de preço, etc.
	DiscountValue	M	Valor do desconto / montante do abatimento Atenção: se DiscountType [1] = discount, o valor do desconto deve ser introduzido com 4 casas decimais!
	caption	R	Designação do desconto Detalhes do país: Itália: a designação «discounts.caption» é impressa no recibo como designação do desconto
	DiscountOrder	M*	Indica a ordem em que o desconto é calculado. O primeiro desconto tido em conta tem um valor de 0. Deve ser especificado se forem aplicados vários descontos a um artigo.
	type	M	Tipo de desconto Enumeração: [0] = Abatimento - Desconto de montante [1] = Desconto - desconto percentual
	TypeValue	M	Valor do desconto (soma da redução) no caso de [0] = Abatimento: o DiscountValue (=> DiscountValue = TypeValue) para [1] = Desconto: a percentagem (por exemplo, 10% de desconto)
	PromotionKeys	O	Chaves de promoção — se utilizadas (por exemplo, código de voucher)
	identificador	O	Identificador adicional para o desconto (pode ser utilizado, por exemplo, para agrupar descontos em tipos de desconto).
tipo		M	Tipo de posição (DocumentPositionType)
UseSubItemVatCalculation		O	«true» se o cálculo do Vat dos subitens (SubItems) tiver de ser adotado e o Vat do item pai tiver de ser ignorado; caso contrário, «false».
SubItems		O	Detalhes dos SubItems. Ver: DocumentPositionType [1] = SubItem
	[...]
inhouse		O	Indica uma venda interna ou uma venda externa (true / falso).
ItemGroupId		M*	Indicador do grupo de artigos Detalhes do país: Dinamarca: informação obrigatória («artGroupID» no SAF-T)
ItemGroupCaption		O	Designação do grupo de artigos
CostPrice		O/M*	Preço unitário do artigo Detalhes do país: Dinamarca: pode ser definido como o preço individual do item para subitens. Portugal: informação obrigatória (caso não seja definida, o CostPrice é calculado da seguinte forma: BaseGrossValue / Quantidade)
itemDateOfEntry		M*	Momento da criação do artigo. Detalhes por país: Dinamarca: informação obrigatória («dateOfEntry» no SAF-T). Estes campos representam a hora em que o item foi criado pela primeira vez no sistema (criação dos dados mestre). Caso esta informação não esteja disponível no sistema POS, devem ser utilizados os seguintes valores: dateOfEntry: 0001-01-01, timeOfEntry: 00:00:00 e UTC-offset: +00:00 `"itemDateOfEntry": "0001-01-01T00:00:00+00:00"`
quantidade		M	Informações sobre a quantidade do artigo
QuantityUnit		M*	Especificação da unidade de medida Detalhes do país: Portugal: Requer a especificação de uma unidade de medida («ID» ou «isoCode»)
	ID	M*	Indicação da unidade de medida. Detalhes do país: Roménia: Informação obrigatória
	isoCode	M*	Unidade de medida padrão de acordo com o código ISO/UCUM. Para mais informações, consulte o artigo indicado no link.
ItemId		M	ID do artigo
ItemType		M*	Descreve o tipo de item: bens ou serviços. [0] = Artigo [1] = Serviço Detalhes do país: França: Informações obrigatórias
BaseNetValue		M*	Total líquido (sem Vat) antes de descontos ou sobretaxas Atenção: soma (líquida) da linha/posição, NÃO do artigo. Se a quantidade for igual a 2, então o BaseNetValue é também o preço unitário multiplicado por 2!
BaseGrossValue		M*	Total bruto (Vat incluído) antes de descontos ou sobretaxas Atenção: soma (bruta) da linha/posição, NÃO do artigo. Se a quantidade for igual a 2, então o BaseGrossValue é também o preço do artigo multiplicado por 2!
BaseTaxValue		M*	Total do Vat (ou soma da primeira taxa de imposto) antes de descontos ou sobretaxas Atenção: soma (do Vat) da linha/posição, NÃO do artigo. Se a quantidade for igual a 2, então o «BaseTaxValue» é também o preço unitário multiplicado por 2! Detalhes do país: Québec (Canadá): Imposto federal GST
BaseTaxValue2		M*	Soma da segunda taxa de imposto da posição antes do desconto/sobretaxa. Detalhes do país: Québec (Canadá): Imposto provincial QST
GTIN		O	Número Global de Artigo Comercial (GTIN) Detalhes do país: Portugal: Recomenda-se que se especifique o GTIN para o artigo em questão. Em alternativa, utiliza-se a propriedade «ItemId» no SAF-T.
BusinessTransactionType		M	Tipo de transação comercial. Enumeração: [0] = Revenue [1] = Desconto [2] = Depósito por embalagens vazias [3] = Vale de uso único [4] = MultiPurposeVoucher [5] = Gorjeta [6] = Gorjeta da empresa [7] = Caução [10] = Pagamento [11] = PayIn [90] = MoneyTransfer [91] = Diferença de dinheiro [92] = Conceder autêntico [93] = Concessão Irreal
ItemTypeClassification			ItemTypeClassification pode ser utilizada para aplicar uma classificação adicional a um artigo. A «ItemTypeClassification» só pode ser definida se a propriedade «ItemType» tiver sido definida como «[0] - Artigo» ou «ItemType»: 0. Poderá encontrar informações detalhadas sobre a propriedade «ItemTypeClassification» no artigo associado. Estão disponíveis as seguintes classificações. [1] = BebidaAlcoólica [5] = Produtos de tabaco [10] = Gasolina [11] = Combustível de etanol para automóveis [12] = Combustível diesel [13] = Éster metílico de ácidos gordos [14] = Combustível diesel destinado à agricultura e à pesca [15] = Gás natural para transportes [16] = Gás de Petróleo Liquefeito para Transportes [17] = Combustível para transportes não classificado noutra rubrica Detalhes do país: FiscalCountryProperties: A exigência de definir a «ItemTypeClassification» é especificada nas «fiscalCountryProperties» através da propriedade «itemTypeClassificationRequired». Se o valor for «true», o item deve ser classificado – desde que se trate de um item especial (!). A propriedade «supportedItemTypeClassification» define para que tipo de produto a propriedade pode ser definida.
VatIdentification		M	ID da taxa de Vat. Pode ser consultado através de GET /api/v1/information/client/ {clientId}/getVatIdentification, especificando a taxa de Vat do respetivo país. taxa do respetivo país.
VatPercent		M	Taxa de Vat em percentagem ou primeira taxa fiscal aplicável ao artigo no respetivo país. Detalhes do país: Québec (Canadá): Imposto Federal GST
VatPercent2		M*	segunda taxa de imposto aplicável ao artigo, expressa em percentagem no respetivo país. Detalhes do país: Québec (Canadá): Imposto provincial QST
NetValue		M	Valor líquido total da posição (deduzidos eventuais descontos / acrescido de sobretaxas) — sem Vat. Deve ser sempre indicado.
GrossValue		M	Valor bruto total da posição (deduzidos eventuais descontos / acrescido de sobretaxas) — Vat incluído. Deve ser sempre indicado.
TaxValue		M	Total do Vat (ou soma da primeira taxa de imposto) da posição (deduzidos eventuais descontos / acrescido de sobretaxas) Deve ser sempre indicado. Detalhes do país: Québec (Canadá): Imposto federal GST
TaxValue2		M*	Soma da segunda taxa de imposto do artigo após desconto/sobretaxa. Detalhes do país: Québec (Canadá): Imposto provincial QST
AccountingIdentifier		O	Identificador adicional para efeitos contabilísticos (interface contabilística)
ItemTaxType		M*	Tipo de imposto da posição: entregas serviços Detalhes do país: Espanha: Deve ser definido ao faturar clientes não espanhóis.
PositionNumber		M	Número da posição, começando por 0
positionReference		O	Especificação de um número de posição ao qual se deve fazer referência
cancellationPosition		O	«true» se esta posição anular uma posição de outro documento; caso contrário, «false»
CreateDate		O	Hora do registo da posição

[1] = SubItem

Os «subitens» (DocumentPositionSubItem) permitem explicar a composição dos produtos vendidos ou as descrições dos grupos de produtos ao nível do item.

Exemplo: Menu = Coca-Cola e hambúrguer.

Os SubItems têm caráter explicativo e não têm de ser utilizados. Além disso, não têm qualquer efeito no que diz respeito ao preço e às vendas/imposto sobre o valor acrescentado.

Nota: o item «SubItem» corresponde ao item «Item», mas não contém os elementos «UseSubItemVatCalculation» e «SubItems».

[2] = Texto

Utilizado para definir a posição de um texto ou Barcode no documento.

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

O objeto DocumentPositionText contém as seguintes informações.

Informações na coluna «Type»:

M ... obrigatório / exigido
M* ... obrigatório / exigido em determinados países ou sob determinadas condições
R ... recomendado
O... opcional

Elementos	Tipo	Descrição
tipo	M	Tipo de posição (DocumentPositionType)
texto	O	Campo de texto livre Detalhes do país: Itália Impressoras EPSON: enviadas para a impressora como messageType="4" (Linhas do Corpo); são possíveis, no máximo, 38 caracteres por posição de texto. Após 25 caracteres, ocorre uma quebra de linha automática. O texto com várias linhas deve ser dividido em várias posições. Em alternativa, podem ser utilizados textos adicionais de header e Footer . Caso não ocorra uma quebra de linha após 25 caracteres, mas o texto seja, em vez disso, truncado, contacte o seu técnico de assistência da impressora (palavra-chave: «RT DESCR. OVERLAP»).
barcodeType	O	Indicação do tipo de Barcode Enumeração: ean8 ean13 code128
Barcode	O	Dados do Barcode
PositionNumber	M	Número da posição, começando por 0

[3] = Reserva

As posições de reserva (DocumentPositionBooking) são utilizadas para depósitos, levantamentos, bem como para a venda de vales multifuncionais (PayIn, payOut, MultiPurposeVoucher,...).

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

O objeto DocumentPositionBooking contém as seguintes informações.

Informações na coluna «Tipo»:

M ... obrigatório / exigido
M* ... obrigatório / exigido em determinados países ou sob determinadas condições
R ... recomendado
O... opcional

Elementos	Tipo	Descrição
tipo	M	Tipo de Posições (DocumentPositionType)
caption	M	Descrição da posição de reserva
identificador	O	Indicador de ID adicional da transação contabilística
BusinessTransactionType	M	Tipo de transação comercial. Enumeração: [0] = Revenue [1] = Desconto [2] = Depósito por embalagens vazias [3] = Vale de uso único [4] = MultiPurposeVoucher [5] = Gorjeta [6] = Gorjeta da empresa [7] = Caução [10] = Pagamento [11] = PayIn [90] = MoneyTransfer [91] = Diferença de dinheiro [92] = Conceder autêntico [93] = Conceder Irreal
PayOutType	M*	Indica o tipo de pagamento. Obrigatório em determinados países. Valores possíveis: [0] = Material de limpeza [1] = Material de escritório [2] = Taxa Postal [3] = Salário [4] = Remuneração [5] = Compra de mercadorias [6] = OutrosCustos Detalhes do país: Dinamarca: Informação obrigatória («reportPayOut» «PayOutType» no SAF-T). Um elemento de cadeia de caracteres (string36) utilizado para designar o tipo de pagamento. Nota: Novidade a partir da versão DOM v1.2.0 / Client v1.7.6
VatIdentification	M	ID da taxa de Vat. Pode ser consultado através de GET /api/v1/information/client/ {clientId}/getVatIdentification, especificando a taxa de Vat do respetivo país.
VatPercent	M	Taxa de Vat em percentagem
NetValue	M	Valor líquido total da posição (deduzidos eventuais descontos) — sem Vat. Deve ser sempre indicado.
GrossValue	M	Total bruto da posição (deduzidos eventuais descontos) — Vat incluído. Deve ser sempre indicado.
TaxValue	M	Total do Vat da posição (deduzidos eventuais descontos) Deve ser sempre indicado.
AccountingIdentifier	O	Identificador adicional para efeitos contabilísticos (interface contabilística)
ItemTaxType	M*	Tipo de imposto da posição: entregas serviços Detalhes do país: Espanha: Deve ser definido ao faturar clientes não espanhóis.
PositionNumber	M	Número da posição, começando por 0
positionReference	O	Especificação de um número de item ao qual se deve fazer referência
cancellationPosition	O	«true» se esta posição anular uma posição de outro documento; caso contrário, «false».
DeletedPosition	O	«true» se esta posição tiver sido eliminada; caso contrário, «false».
CreateDate	O	Hora do registo da posição

[9] = Subtotal

Posição «SubTotal»

Nota: A posição «SubTotal» corresponde à posição «Total».

[10] = Total

Posição «Total». Se for utilizada a posição «DocumentPositionTotal», esta deve ser sempre a última posição no documento (o PositionNumber mais elevado).

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

O objeto DocumentPositionTotal contém as seguintes informações.

Informações na coluna «Tipo»:

M ... obrigatório / exigido
M* ... obrigatório / exigido em determinados países ou sob determinadas condições
R ... recomendado
O... opcional

Elementos		Tipo	Descrição
tipo		M	Tipo de posições (DocumentPositionType)
arredondamento		O	arredondamento aplicado. Se a soma das posições (valor bruto) não for igual ao montante do pagamento. Por exemplo, 0,01 permitiria diferenças de arredondamento de +/-0,01 Nota: Utilize com cuidado. Valores elevados desativarão a validação do montante de pagamento / valor bruto do documento
BaseValue		M*	Montante base da posição antes da aplicação de descontos (apenas se forem aplicados descontos)
valor		M	O valor da posição, incluindo descontos.
descontos			Detalhes sobre descontos, reduções de preço, etc.
	DiscountValue	M	Valor do desconto / montante do abatimento Atenção: se DiscountType [1] = discount, o valor do desconto deve ser introduzido com 4 casas decimais!
	caption	O	Designação do desconto
	DiscountOrder	M*	Indica a ordem em que o desconto é calculado. O primeiro desconto tido em conta tem um valor de 0. Deve ser especificado caso sejam aplicados vários descontos a um artigo.
	type	M	Tipo de desconto Enumeração: [0] = Desconto global [1] = Desconto - desconto percentual
	TypeValue	M	Valor do desconto (soma da redução) no caso de [0] = Abatimento: o DiscountValue para [1] = Desconto: a percentagem (por exemplo, 10% de desconto)
	PromotionKeys	O	Chaves de promoção — se utilizadas (por exemplo, código de voucher)
	identificador	O	Identificador adicional para o desconto (pode ser utilizado, por exemplo, para agrupar descontos em tipos de desconto).
caption		O	A designação da posição
PositionNumber		M	Número da posição, começando por 0
positionReference		O	Especificação de um número de posição ao qual se deve fazer referência
cancellationPosition		O	«true» se esta posição anular uma posição de outro documento; caso contrário, «false».
DeletedPosition		O	«true» se esta posição tiver sido eliminada; caso contrário, «false».
CreateDate		O	Hora do registo da posição

Este artigo foi traduzido automaticamente.

DocumentPositionsBase

DocumentPositionType

[0] = Artigo

[1] = SubItem

[2] = Texto

[3] = Reserva

[9] = Subtotal

[10] = Total

Artigos relacionados