Objeto «positions» – RetailForce

Este artículo trata sobre el objeto «positions» dentro del objeto «Document» (objeto «Document»).

En la sección de descargas de la RetailForce website (Documentación del modelo de objetos.pdf), dentro del directorio de la versión correspondiente, encontrará una descripción completa del RetailForce DOM (Modelo de Objetos de Documento), así como una descripción de los elementos individuales.

El objeto «positions» contiene información sobre la posición correspondiente del documento.

El objeto «positions» consta de:

DocumentPositionBase: almacena los datos básicos de la posición, con independencia de su tipo.
Información específica del tipo de posición: en función del «tipo» de posición (DocumentPositionType), deben especificarse contenidos diferentes (el tipo de posición define el contenido de la misma).

DocumentPositionsBase

El siguiente objeto contiene datos de ejemplo.

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

El objeto DocumentPositionsBase contiene la siguiente información.

Información de la columna «Type»:

M ... obligatorio / requerido
M* ... obligatorio / requerido en determinados países o bajo determinadas condiciones
R ... recomendado
O... opcional

Elementos		Tipo	Descripción
PositionNumber		M	Número de secuencia de la posición. Nota: El número de la primera posición es siempre «0».
positionReference		O	Referencia a otra posición dentro del documento. Equivalente a «documentReference».
	{...}	O
cancellationPosition		M	«true» si esta posición anula una posición de otro documento; en caso contrario, «false».
DeletedPosition		O	«true» si esta posición se ha eliminado; en caso contrario, «false».
tipo		M	especifica el tipo de posición «type» (DocumentPositionType). Enum: [0] = Elemento [1] = Subelemento [2] = Texto [3] = Reserva [9] = Subtotal [10] = Total Las explicaciones de los distintos tipos (DocumentPositionTypes) se encuentran a continuación de esta tabla.
AdditionalFields		O
	{...}
CreateDate		M	Hora en la que se creó la posición.
ExternalIdentifier		O	Identificador externo (procedente del sistema anterior), destinado a uso interno, no relevante a efectos de fiscalización.
usuario		O	Datos del usuario (de la caja registradora) que introdujo el artículo correspondiente.
	{...}
SalesPerson		O	Datos del personal de ventas del puesto correspondiente.
	{...}
FiscalAdditionalFields		O

DocumentPositionType

[0] = Artículo

El tipo «artículo» (DocumentPositionItem) representa un ítem de venta específico (bien o servicio).

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

El objeto DocumentPositionItem contiene la siguiente información.

Información de la columna «Tipo»:

M ... obligatorio / requerido
M* ... obligatorio / requerido en determinados países o bajo determinadas condiciones
R ... recomendado
O... opcional

Elementos		Tipo	Descripción
ItemCaption		M	Denominación del artículo, descripción del servicio
ItemShortCaption		O	Nombre abreviado del artículo, utilizado, por ejemplo, cuando existen restricciones en la longitud de los caracteres, como en el caso de las impresoras fiscales.
ItemSerialNumber		M*	Número de serie del artículo. Datos del país: Portugal: Información obligatoria
descuentos			Detalles de descuentos, reducciones de precio, etc.
	DiscountValue	M	Importe del descuento / cuantía de la rebaja Advertencia: si DiscountType [1] = discount, el importe del descuento debe introducirse con 4 decimales.
	caption	R	Denominación del descuento Datos del país: Italia: «discounts.caption» aparece impreso en el recibo como denominación del descuento
	DiscountOrder	M*	Indica el orden en el que se calcula el descuento. El primer descuento que se tiene en cuenta tiene un valor de 0. Debe especificarse si se aplican varios descuentos a un artículo.
	tipo	M	Tipo de descuento Enum: [0] = Descuento fijo: descuento total [1] = Descuento: descuento porcentual
	TypeValue	M	Valor del descuento (suma de la reducción) en el caso de [0] = Descuento: el DiscountValue (=> DiscountValue = TypeValue) si [1] = Descuento: el porcentaje (p. ej., descuento del 10 %)
	PromotionKeys	O	Claves de promoción: si se utilizan (p. ej., código de cupón)
	identificador	O	Identificador adicional para el descuento (puede utilizarse, por ejemplo, para agrupar descuentos en tipos de descuento).
tipo		M	Tipo de posición (DocumentPositionType)
UseSubItemVatCalculation		O	«true» si se debe aplicar el cálculo del Vat de las subpartidas (SubItems) y se debe ignorar el Vat de la partida principal; en caso contrario, «false».
SubItems		O	Detalles de los SubItems. Véase: DocumentPositionType [1] = SubItem
	[...]
inhouse		O	Indica si se trata de una venta interna o externa (true/false).
ItemGroupId		M*	Indicador de grupo de artículos Datos del país: Dinamarca: información obligatoria («artGroupID» en SAF-T)
ItemGroupCaption		O	Denominación del grupo de artículos
CostPrice		O/M*	Precio unitario del artículo Datos del país: Dinamarca: puede definirse como el precio unitario de cada subartículo. Portugal: información obligatoria (si no se especifica, el «CostPrice» se calcula como «BaseGrossValue» / «Quantity»)
itemDateOfEntry		M*	Hora de creación del artículo. Detalles por país: Dinamarca: información obligatoria («dateOfEntry» en SAF-T). Estos campos indican el instante en que el artículo se creó por primera vez en el sistema (creación de datos maestros). Si esta información no está disponible en el sistema TPV, deben utilizarse los siguientes valores: «dateOfEntry»: 0001-01-01, «timeOfEntry»: 00:00:00 y «UTC-offset»: +00:00 `"itemDateOfEntry": "0001-01-01T00:00:00+00:00"`
cantidad		M	Información sobre la cantidad del artículo
QuantityUnit		M*	Especificación de la unidad de medida Datos del país: Portugal: Requiere la especificación de una unidad de medida («ID» o «isoCode»)
	ID	M*	Indicación de la unidad de medida. Datos del país: Rumanía: Información obligatoria
	isoCode	M*	Unidad de medida estándar según el código ISO/UCUM. Para obtener más información, consulte el artículo enlazado.
ItemId		M	ID del artículo
ItemType		M*	Describe el tipo de artículo: bienes o servicios. [0] = Artículo [1] = Servicio Datos del país: Francia: Información obligatoria
BaseNetValue		M*	Total neto (sin VAT) antes de descuentos o recargos Importante: se trata de la suma (neta) de la línea o posición, NO del artículo. Si la cantidad es 2, ¡el BaseNetValue también equivale al precio unitario multiplicado por 2!
BaseGrossValue		M*	Total bruto (IVA incluido) antes de descuentos o recargos Atención: suma (bruta) de la línea o posición, NO del artículo. Si la cantidad es 2, ¡el «BaseGrossValue» también es el precio de la unidad multiplicado por 2!
BaseTaxValue		M*	Total del IVA (o suma del primer tipo impositivo) antes de aplicar descuentos o recargos Atención: suma (del Vat) de la línea o posición, NO del artículo. Si la cantidad es 2, ¡el «BaseTaxValue» también es el precio unitario multiplicado por 2! Datos del país: Québec (Canadá): Impuesto federal GST
BaseTaxValue2		M*	Suma del segundo tipo impositivo de la posición antes del descuento o recargo. Datos del país: Québec (Canadá): Impuesto provincial QST
GTIN		O	Número global de artículo comercial (GTIN) Datos del país: Portugal: Se recomienda especificar el GTIN del artículo correspondiente. Como alternativa, en SAF-T se utiliza la propiedad «ItemId».
BusinessTransactionType		M	Tipo de operación comercial. Enum: [0] = Ingresos [1] = Descuento [2] = Depósito por envases vacíos [3] = Vale de uso único [4] = MultiPurposeVoucher [5] = Propina [6] = Propina de la empresa [7] = Depósito [10] = Pago [11] = PayIn [90] = MoneyTransfer [91] = Diferencia de efectivo [92] = Conceder auténtico [93] = Subvención no real
ItemTypeClassification			La clasificación de tipo de artículo (ItemTypeClassification) puede utilizarse para aplicar una clasificación adicional a un artículo. «ItemTypeClassification» solo puede establecerse si la propiedad «ItemType» se ha fijado en «[0] - Artículo» o en «ItemType»: 0. En el artículo enlazado encontrará información detallada sobre la propiedad «ItemTypeClassification». Las clasificaciones disponibles son las siguientes. [1] = BebidaAlcohólica [5] = Productos de tabaco [10] = Gasolina [11] = Combustible de etanol para automóviles [12] = Combustible diésel [13] = Éster metílico de ácidos grasos [14] = Combustible diésel destinado a usos agrícolas y pesqueros [15] = Gas natural para el transporte [16] = Gas de petróleo licuado para el transporte [17] = Combustible para el transporte no clasificado en otra parte Detalles del país: FiscalCountryProperties: El requisito de definir ItemTypeClassification se especifica en FiscalCountryProperties a través de la propiedad itemTypeClassificationRequired. Si el valor es «true», el artículo debe clasificarse, siempre que se trate de un artículo especial (!). supportedItemTypeClassification define para qué tipo de producto puede establecerse la propiedad.
VatIdentification		M	ID del tipo de Vat. Se puede consultar mediante GET /api/v1/information/client/{clientId}/getVatIdentification, especificando el tipo de IVA del país correspondiente.
VatPercent		M	Tipo de Vat en porcentaje o primer tipo impositivo aplicable al artículo en el país correspondiente. Datos del país: Québec (Canadá): Impuesto federal GST
VatPercent2		M*	segundo tipo impositivo aplicable al artículo, expresado en porcentaje en el país correspondiente. Datos del país: Québec (Canadá): Impuesto provincial QST
NetValue		M	Importe neto total de la partida (menos los descuentos y más los recargos), sin Vat. Debe indicarse siempre.
GrossValue		M	Importe bruto de la partida (menos los descuentos y más los recargos), IVA incluido. Debe indicarse siempre.
TaxValue		M	Total del IVA (o suma del primer tipo impositivo) de la partida (menos los descuentos / más los recargos) Debe indicarse siempre. Datos del país: Québec (Canadá): Impuesto federal GST
TaxValue2		M*	Suma del segundo tipo impositivo del artículo tras aplicar el descuento o el recargo. Datos del país: Québec (Canadá): Impuesto provincial QST
AccountingIdentifier		O	Identificador adicional con fines contables (interfaz contable)
ItemTaxType		M*	Tipo de impuesto de la partida: entregas servicios Datos del país: España: Debe indicarse al facturar a clientes no españoles.
PositionNumber		M	Número de posición, comenzando por 0
positionReference		O	Especificación de un número de posición al que se debe hacer referencia
cancellationPosition		O	«true» si esta posición anula una posición de otro documento; en caso contrario, «false»
CreateDate		O	Hora de registro de la posición

[1] = SubItem

Los «subelementos» (DocumentPositionSubItem) permiten detallar la composición de los productos vendidos o las descripciones de los grupos de productos a nivel de artículo.

Ejemplo: Menú = Coca-Cola y hamburguesa.

Los SubItems tienen carácter meramente explicativo y su uso no es obligatorio. Tampoco ejercen efecto alguno sobre el precio, las ventas ni el impuesto sobre el valor añadido.

Nota: la partida «SubItem» se corresponde con la partida «Item», pero no contiene los elementos «UseSubItemVatCalculation» y «SubItems».

[2] = Texto

Se emplea para definir la posición de un texto o un Barcode dentro del documento.

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

El objeto DocumentPositionText contiene la siguiente información.

Información de la columna «Type»:

M ... obligatorio / requerido
M* ... obligatorio / requerido en determinados países o bajo determinadas condiciones
R ... recomendado
O... opcional

Elementos	Tipo	Descripción
tipo	M	Tipo de posición (DocumentPositionType)
texto	O	Campo de texto libre Datos del país: Impresoras EPSON en Italia: se envían a la impresora como messageType="4" (líneas de cuerpo); se admiten un máximo de 38 caracteres por posición de texto. A partir de los 25 caracteres, se produce un salto de línea automático. El texto de varias líneas debe dividirse en varias posiciones. Como alternativa, pueden utilizarse textos adicionales de Header y Footer . Si no se produce un salto de línea tras 25 caracteres, sino que el texto se trunca, póngase en contacto con su técnico de servicio de impresoras (palabra clave: «RT DESCR. OVERLAP»).
barcodeType	O	Indicación del tipo de Barcode Enum: EAN8 EAN13 code128
Código de barras	O	Datos del Barcode
PositionNumber	M	Número de posición, comenzando por 0

[3] = Reserva

Las posiciones de reserva (DocumentPositionBooking) se emplean para ingresos, reintegros y ventas de vales multiuso (PayIn, payOut, MultiPurposeVoucher, etc.).

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

El objeto DocumentPositionBooking contiene la siguiente información.

Información de la columna «Tipo»:

M ... obligatorio / requerido
M* ... obligatorio / requerido en determinados países o bajo ciertas condiciones
R ... recomendado
O... opcional

Elementos	Tipo	Descripción
tipo	M	Tipo de posiciones (DocumentPositionType)
legenda	M	Descripción de la posición de reserva
identificador	O	Indicador de ID adicional de la operación contable
BusinessTransactionType	M	Tipo de transacción comercial. Enum: [0] = Ingresos [1] = Descuento [2] = Depósito por envases vacíos [3] = Vale de uso único [4] = MultiPurposeVoucher [5] = Propina [6] = Propina de la empresa [7] = Depósito [10] = Pago [11] = PayIn [90] = MoneyTransfer [91] = Diferencia de efectivo [92] = Conceder auténtico [93] = Concesión ficticia
PayOutType	M*	Indica el tipo de pago. Obligatorio en determinados países. Valores posibles: [0] = Material de limpieza [1] = Material de oficina [2] = Gastos postales [3] = Salario [4] = Sueldos [5] = Adquisición de Mercancías [6] = Otros gastos Datos del país: Dinamarca: Información obligatoria («reportPayOut» y «PayOutType» en SAF-T). Un elemento de cadena (string36) que se utiliza para designar el tipo de pago. Nota: Novedad a partir de DOM v1.2.0 / Client v1.7.6
VatIdentification	M	ID del tipo impositivo del Vat. Se puede consultar mediante GET /api/v1/information/client/{clientId}/getVatIdentification, especificando el tipo de Vat del país correspondiente.
VatPercent	M	Tipo de Vat en porcentaje
NetValue	M	Importe neto total de la partida (tras la aplicación de los descuentos), sin Vat. Debe indicarse siempre.
GrossValue	M	Importe bruto total de la partida (menos los descuentos que correspondan), IVA incluido. Debe indicarse siempre.
TaxValue	M	Importe del Vat de la posición (menos los descuentos que correspondan) Debe indicarse siempre.
AccountingIdentifier	O	Identificador adicional con fines contables (interfaz contable)
ItemTaxType	M*	Tipo de impuesto de la partida: entregas servicios Datos del país: España: Debe indicarse al facturar a clientes no españoles.
PositionNumber	M	Número de posición, comenzando por 0
positionReference	O	Especificación del número de partida al que se debe hacer referencia
cancellationPosition	O	«true» si esta posición anula una posición de otro documento; en caso contrario, «falso».
DeletedPosition	O	«true» si esta posición se ha eliminado; en caso contrario, «false».
CreateDate	O	Hora de registro de la posición

[9] = Subtotal

Posición «Subtotal»

Nota: La posición «SubTotal» se corresponde con la posición «Total».

[10] = Total

Posición «Total». Si se emplea «DocumentPositionTotal», debe configurarse siempre como la última posición del documento (el PositionNumber más alto).

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

El objeto DocumentPositionTotal contiene la siguiente información.

Información de la columna «Tipo»:

M ... obligatorio / requerido
M* ... obligatorio / requerido en determinados países o bajo determinadas condiciones
R ... recomendado
O... opcional

Elementos		Tipo	Descripción
tipo		M	Tipo de posiciones (DocumentPositionType)
redondeo		O	Se aplica el redondeo. Si la suma de las posiciones (valor bruto) no es igual a la suma del pago. Por ejemplo, un valor de 0,01 permitiría diferencias de redondeo de ±0,01. Nota: utilícelo con precaución. Los valores elevados desactivarán la validación del importe del pago y del valor bruto del documento
BaseValue		M*	Importe base de la partida antes de aplicar los descuentos (solo si se aplican descuentos)
valor		M	El valor de la posición, incluidos los descuentos.
descuentos			Detalles de los descuentos, reducciones de precio, etc.
	DiscountValue	M	Importe del descuento / cuantía de la rebaja Advertencia: si DiscountType [1] = discount, el importe del descuento debe introducirse con 4 decimales.
	caption	O	Denominación del descuento
	DiscountOrder	M*	Indica el orden en el que se calcula el descuento. El primer descuento que se tiene en cuenta tiene un valor de 0. Debe especificarse cuando se aplican múltiples descuentos a un artículo.
	tipo	M	Tipo de descuento Enum: [0] = Descuento global [1] = Descuento – descuento porcentual
	TypeValue	M	Valor del descuento (suma de la reducción) en el caso de [0] = Descuento: el DiscountValue si [1] = Descuento: el porcentaje (p. ej., descuento del 10 %)
	PromotionKeys	O	PromotionKeys: si se emplean (p. ej., código de cupón)
	identificador	O	Identificador adicional para el descuento (puede utilizarse, por ejemplo, para agrupar descuentos en tipos de descuento).
legenda		O	La designación de la posición
PositionNumber		M	Número de puesto, a partir del 0
positionReference		O	Especificación de un número de posición al que se debe hacer referencia
cancellationPosition		O	«true» si esta posición anula una posición de otro documento; en caso contrario, «falso».
DeletedPosition		O	«true» si esta posición se ha eliminado; en caso contrario, «false».
CreateDate		O	Hora de registro de la posición

Este artículo ha sido traducido automáticamente.

DocumentPositionsBase

DocumentPositionType

[0] = Artículo

[1] = SubItem

[2] = Texto

[3] = Reserva

[9] = Subtotal

[10] = Total

Artículos relacionados