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» da 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:
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, sem relevância para efeitos de fiscalização. | |
| utilizador | 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": "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": {}
}
],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 Dados do país:
|
|
| 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:
|
|
| 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:
|
|
| 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:
|
|
| TypeValue | M |
Valor do abatimento (soma da redução) no caso de [0] = Abatimento: o DiscountValue (=> DiscountValue = TypeValue) no caso de [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 assumido e o Vat do item pai tiver de ser ignorado; caso contrário, «false». Valor por defeito (se não for indicado): «true». Com «true», cada subitem necessita de uma VatIdentification e a soma dos valores brutos, líquidos e de imposto dos subitens deve ser igual aos valores BaseGrossValue, BaseNetValue e BaseTaxValue do item pai; caso contrário, o documento é recusado. | |
| 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:
|
|
| ItemGroupCaption | O |
Designação do grupo de artigos Detalhes do país:
|
|
| CostPrice | O/M* |
Preço unitário do artigo Detalhes do país:
|
|
| itemDateOfEntry | M* |
Hora de criação do artigo. Detalhes do país:
|
|
| quantidade | M |
Informações sobre a quantidade do artigo Detalhes do país:
|
|
| QuantityUnit | M* |
Especificação da unidade de medida Detalhes do país:
|
|
| ID | M* |
Indicação da unidade de medida. Detalhes do país:
|
|
| isoCode | M* |
Unidade de medida padrão, enviada como o nome de um valor QuantityUnitIsoCode (por exemplo, «Quantity» para peças, «Kilogram»), e não como o próprio código ISO/UCUM. O módulo converte o nome no código ISO/UCUM (por exemplo, «Quantity» = «1»). Um número é interpretado como o valor numérico da enumeração, pelo que «1» significa «Percent». Para mais informações, consulte o artigo indicado na ligação. Detalhes por país:
|
|
| ItemId | M |
ID do artigo Detalhes do país:
|
|
| ItemType | M* |
Descreve o tipo de item: bens ou serviços.
Detalhes do país:
|
|
| BaseNetValue | M* |
Total líquido (excl. 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 (incl. Vat) 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 da unidade 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:
|
|
| BaseTaxValue2 | M* |
Soma da segunda taxa de imposto da posição antes do desconto/sobretaxa. Detalhes do país:
|
|
| GTIN | O/R |
Número Global de Artigo Comercial (GTIN) Detalhes do país:
|
|
| BusinessTransactionType | M |
Tipo de transação comercial. Enumeração:
|
|
| ItemTypeClassification | O/M* |
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.
Detalhes do país:
|
|
| VatIdentification | M |
ID da taxa de IVA. 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:
|
|
| VatPercent2 | M* |
segunda taxa de imposto aplicável ao artigo, expressa em percentagem no respetivo país. Detalhes do país:
|
|
| NetValue | M |
Valor líquido total da posição (deduzidos eventuais descontos / acrescidos de sobretaxas) — sem Vat. Deve ser sempre indicado. |
|
| GrossValue | M |
Total bruto 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:
|
|
| TaxValue2 | M* |
Soma da segunda taxa de imposto do artigo após desconto/sobretaxa. Detalhes do país:
|
|
| AccountingIdentifier | O | Identificador adicional para efeitos contabilísticos (interface contabilística) | |
| ItemTaxType | M* |
Tipo de imposto da posição:
Detalhes do país:
|
|
| 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/M* | «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.
Não é obrigatório utilizar SubItems. Se o item pai tiver «UseSubItemVatCalculation»: true (o valor predefinido), aplica-se o Vat dos SubItems em vez do Vat do item pai, e os seus valores devem somar-se aos valores base do item pai. Com «UseSubItemVatCalculation»: false, aplica-se o Vat do item pai e os SubItems servem apenas para explicar a composição do item.
[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ções (DocumentPositionType) | |
| texto | O |
Campo de texto livre Detalhes do país:
|
|
| barcodeType | O |
Indicação do tipo de Barcode Enumeração:
|
|
| 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 MultiPurposeVouchers (PayIn, payOut, MultiPurposeVoucher,...).
Exemplo de 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": {}
}
],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:
|
|
| PayOutType | M* |
Indica o tipo de pagamento. Obrigatório em determinados países. Valores possíveis:
Detalhes do país:
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) — com 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:
Detalhes do país:
|
|
| 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
Subtotal da posição
[10] = Total
Posição total. Se for utilizada a DocumentPositionTotal, esta deve ser sempre a última posição no documento (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. Caso a soma das posições (valor bruto) não seja igual ao montante do pagamento. O arredondamento é adicionado à soma dos valores brutos das posições de item e de lançamento, e a soma dos pagamentos deve ser exatamente igual ao resultado. Trata-se de um montante com sinal, não de uma tolerância: por exemplo, -0,02 significa que os pagamentos são 0,02 inferiores à soma bruta das posições; 0,01 significa que são exatamente 0,01 superiores. Nota: Utilize com cuidado. Se os pagamentos e as posições não diferirem exatamente deste valor, o documento será recusado. |
|
| 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 |
Montante do desconto / valor 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:
|
|
| TypeValue | M |
Valor do desconto (montante 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 — caso sejam 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.
Comentários
0 comentários
iniciar sessão para comentar.