Aller au contenu principal

Objet « positions »

Harald Krondorfer
  • Mise à jour

Cet article traite de l’objet « positions » au sein de l’objet « Document » (objet Document).

Une description complète du RetailForce DOM (Document Object Model), ainsi qu’une description des différents éléments, sont disponibles dans la section « Téléchargements » du site Web RetailForce (Documentation sur le modèle d’objet.pdf) dans le répertoire correspondant à la version concernée.

L’objet « positions » contient des informations sur la position correspondante du document.

L’objet « positions » se compose de :

  • DocumentPositionBase – contient des informations de base sur la position (indépendamment du type de la position concernée)
  • Informations spécifiques au type de position — en fonction du « type » de position (DocumentPositionType), différents contenus doivent être spécifiés (le type de position définit le contenu de la position).

DocumentPositionsBase

L'objet suivant contient des exemples de données.

  "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’objet DocumentPositionsBase contient les informations suivantes.

Informations dans la colonne « Type » :

  • M … obligatoire / requis
  • M* ... obligatoire / requis dans certains pays ou sous certaines conditions
  • R ... recommandé
  • O... facultatif
Éléments Type Description
PositionNumber M

Numéro d'ordre de la position. 

Remarque : le numéro de la première position est toujours « 0 ».
positionReference O Référence à une autre position au sein du document. Équivalent à documentReference.
  {...} O  
cancellationPosition M « true » si cette position annule une position d’un autre document ; sinon « false ».
DeletedPosition O « true » si cette position a été supprimée ; sinon « false ».
type M

spécifie le type de position « type » (DocumentPositionType).

Énumération : 

  • [0] = Élément
  • [1] = Sous-élément
  • [2] = Texte
  • [3] = Réservation
  • [9] = Sous-total
  • [10] = Total

Vous trouverez les explications relatives à chaque type (DocumentPositionType) à la suite de ce tableau.
AdditionalFields O  
  {...}    
CreateDate M Heure à laquelle la position a été créée.
ExternalIdentifier O ID externe (provenant du système précédent), à usage interne, sans incidence sur la fiscalisation.
utilisateur O Informations relatives à l’utilisateur (de la caisse enregistreuse) qui a saisi l’article en question.
  {...}    
SalesPerson O Informations relatives au vendeur occupant le poste en question.
  {...}    
FiscalAdditionalFields O  

 

DocumentPositionType

[0] = Article

Le type « article » (DocumentPositionItem) correspond à un article de vente spécifique (bien ou service).

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

L'objet DocumentPositionItem contient les informations suivantes.

Informations dans la colonne « Type » :

  • M … obligatoire / requis
  • M* … obligatoire / requis dans certains pays ou sous certaines conditions
  • R ... recommandé
  • O... facultatif
Éléments Type Description
ItemCaption M Désignation de l’article, description du service
ItemShortCaption O Désignation abrégée de l’article, utilisée notamment lorsque la longueur des caractères est limitée, par exemple avec les imprimantes fiscales.
ItemSerialNumber M*

Numéro de série de l'article.

Informations spécifiques au pays :

  • Portugal : informations obligatoires
remises   Détails des remises, réductions de prix, etc.
  DiscountValue M

Montant de la remise / montant du rabais

Attention : si DiscountType [1] = discount, le montant de la remise doit être saisi avec 4 décimales !
  caption R

Désignation de la remise

Informations par pays :

  • Italie : « discounts.caption » est imprimé sur le ticket de caisse en tant que libellé de la remise
  DiscountOrder M*

Il indique l’ordre de calcul de la remise. La première remise prise en compte porte la valeur 0.

Ce paramètre doit être défini lorsque plusieurs remises sont appliquées à un article.
  type M

Type de remise

Énumération :

  • [0] = Remise forfaitaire – Remise globale
  • [1] = Remise – remise en pourcentage
  TypeValue M

Valeur de la remise (montant total de la réduction)

pour [0] = Remise : la DiscountValue (=> DiscountValue = TypeValue)

pour [1] = Remise : le pourcentage (par ex. 10 % de remise)
  PromotionKeys O Clés de promotion – le cas échéant (par exemple, code promotionnel)
  identifiant O Identifiant supplémentaire pour la remise (pouvant servir, par exemple, à regrouper les remises par type).
type M Type de poste (DocumentPositionType)
UseSubItemVatCalculation O « true » si le calcul de la TVA des sous-postes (SubItems) doit être repris et si la TVA du poste parent doit être ignorée ; sinon « false ».
SubItems O Détails des SubItems. Voir : DocumentPositionType [1] = SubItem
  [...]    
inhouse O Indique s’il s’agit d’une vente interne ou d’une vente externe (true / false).
ItemGroupId M*

Indicateur de groupe d'articles

Informations par pays :

  • Danemark : information obligatoire (« artGroupID » dans SAF-T)
ItemGroupCaption O Désignation du groupe d'articles
CostPrice O/M*

Prix unitaire de l'article

Informations spécifiques au pays :

  • Danemark : peut être défini comme le prix unitaire des sous-articles.
  • Portugal : information obligatoire (si elle n’est pas définie, le « CostPrice » est calculé comme suit : « BaseGrossValue » / « Quantity »)
itemDateOfEntry M*

Date et heure de création de l'article.

Détails par pays :

  • Danemark : informations obligatoires (« dateOfEntry » dans SAF-T). Ces champs indiquent l’heure à laquelle l’article a été créé pour la première fois dans le système (création des données de base). Si ces informations ne sont pas disponibles dans le système de point de vente, les valeurs suivantes doivent être utilisées : dateOfEntry : 0001-01-01, timeOfEntry : 00:00:00 et décalage UTC : +00:00
    • "itemDateOfEntry": "0001-01-01T00:00:00+00:00"
quantité M Informations relatives à la quantité de l'article
QuantityUnit M*

Spécification de l'unité de mesure

Informations relatives au pays :

  • Portugal : la spécification d’une unité de mesure (« ID » ou « isoCode ») est obligatoire
  ID M*

Indication de l'unité de mesure.

Informations spécifiques au pays :

  • Roumanie : informations obligatoires
  isoCode

M*

 Unité de mesure standard selon le code ISO/UCUM. Pour plus d’informations, consultez l’article lié.
ItemId M ID de l'article
ItemType M*

Décrit le type d'élément : biens ou services.

  • [0] = Article
  • [1] = Service

Informations relatives au pays :

  • France : informations obligatoires
BaseNetValue M*

Total net (hors TVA) avant remise ou majoration

Attention : il s’agit de la somme (nette) de la ligne/du poste, et NON de celle de l’article. Si la quantité est égale à 2, la BaseNetValue correspond alors également au prix unitaire multiplié par 2 !
BaseGrossValue M*

Total brut (TVA comprise) avant remise ou majoration

Remarque : somme (brute) de la ligne/du poste, et NON de l'article. Si la quantité est égale à 2, la BaseGrossValue correspond également au prix unitaire multiplié par 2 !
BaseTaxValue M*

Total de la TVA (ou somme du premier taux d'imposition) avant remise ou majoration

Attention : somme (du VAT) de la ligne/du poste, et NON de l’article. Si la quantité est égale à 2, la BaseTaxValue correspond également au prix unitaire multiplié par 2 !

Informations par pays :

  • Québec (Canada) : Taxe fédérale (GST)
BaseTaxValue2 M*

Somme du deuxième taux d’imposition applicable à la ligne avant remise ou majoration.

Détails du pays :

  • Québec (Canada) : Taxe provinciale (QST)
GTIN O

Numéro d'identification commercial mondial (GTIN)

Informations sur le pays :

  • Portugal : il est recommandé de préciser le GTIN de l'article concerné. À défaut, la propriété « ItemId » est utilisée dans le format SAF-T.
BusinessTransactionType M

Type de transaction commerciale.

Énumération :

  • [0] = Revenue
  • [1] = Remise
  • [2] = Consigne sur les emballages vides
  • [3] = Bon d'achat à usage unique
  • [4] = MultiPurposeVoucher
  • [5] = Pourboire
  • [6] = Pourboire de l'entreprise
  • [7] = Consigne
  • [10] = Versement
  • [11] = PayIn
  • [90] = MoneyTransfer
  • [91] = Différence de trésorerie
  • [92] = Octroi d’une subvention
  • [93] = Subvention non réelle
ItemTypeClassification  

La propriété « ItemTypeClassification » permet d’appliquer une classification supplémentaire à un élément.

La propriété « ItemTypeClassification » ne peut être définie que si la propriété « ItemType » a été configurée sur « [0] - Article » ou « ItemType » : 0.

Pour des informations détaillées sur la propriété « ItemTypeClassification », veuillez consulter l’article associé.

Les classifications suivantes sont disponibles.

  • [1] = BoissonAlcoolique
  • [5] = Produits du tabac
  • [10] = Essence
  • [11] = Carburant à l'éthanol pour véhicules
  • [12] = Carburant diesel
  • [13] = Esters méthyliques d’acides gras
  • [14] = Carburant diesel destiné à l’agriculture et à la pêche
  • [15] = Gaz naturel pour véhicules
  • [16] = Gaz de pétrole liquéfié (GPL) destiné au transport
  • [17] = Carburant destiné aux transports non classé ailleurs

Détails par pays :

  • FiscalCountryProperties : L’obligation de définir la classification des types d’éléments (ItemTypeClassification) est spécifiée dans les fiscalCountryProperties via la propriété itemTypeClassificationRequired. Si la valeur est « true », l’élément doit être classé – à condition qu’il s’agisse d’un élément spécial (!). La propriété supportedItemTypeClassification définit pour quels types de produits cette propriété peut être définie.
VatIdentification M

ID du taux de Vat.

Il peut être interrogé via une requête GET sur l’URL /api/v1/information/client/{clientId}/getVatIdentification, en précisant le taux de TVA applicable au pays concerné.
VatPercent M

Taux de TVA en pourcentage ou premier taux d’imposition applicable à l’article dans le pays concerné.

Informations sur le pays :

  • Québec (Canada) : Taxe fédérale (GST)
VatPercent2 M*

Deuxième taux d'imposition applicable à l'article, exprimé en pourcentage dans le pays concerné.

Informations sur le pays :

  • Québec (Canada) : Taxe provinciale (QST)
NetValue M

Montant net total de la ligne (déduction faite des remises / majoré des suppléments) – hors Vat.

Doit toujours être indiqué.
GrossValue M

Montant total brut de la ligne (déduction faite des remises / majoré des suppléments) – TVA comprise.

Doit toujours être indiqué.
TaxValue M

Montant total de la TVA (ou somme du premier taux d’imposition) de la ligne (déduction faite des remises / majoré des suppléments)

Doit toujours être indiqué.

Informations sur le pays :

  • Québec (Canada) : Taxe fédérale (GST)
TaxValue2 M*

Somme du deuxième taux de taxe applicable à l'article après remise ou majoration.

Détails du pays :

  • Québec (Canada) : Taxe provinciale (QST)
AccountingIdentifier O Identifiant supplémentaire à des fins comptables (interface comptable)
ItemTaxType M*

Type de taxe de la position :

  • livraisons
  • services

Informations sur le pays :

  • Espagne : doit être sélectionné lors de la facturation de clients non espagnols.
PositionNumber M Numéro de poste, commençant par 0
positionReference O Spécification d’un numéro de position auquel il convient de se référer
cancellationPosition O « true » si cette position annule une position d’un autre document ; sinon « false »
CreateDate O Heure d'enregistrement de la position

 

[1] = Sous-élément

Les « sous-éléments » (DocumentPositionSubItem) permettent de détailler la composition des produits vendus ou les descriptions des groupes de produits au niveau de chaque article.

Exemple : Menu = Coca-Cola et hamburger.

Les SubItems ont un caractère explicatif et leur utilisation n’est pas obligatoire. Ils n’ont par ailleurs aucune incidence sur le prix, les ventes ou la TVA.

Remarque : l’élément « SubItem » est équivalent à l’élément « Item », mais ne contient pas les éléments « UseSubItemVatCalculation » et « SubItems ».

 

[2] = Texte

Permet de définir l’emplacement d’un texte ou d’un Barcode dans le document.

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

L’objet DocumentPositionText contient les informations suivantes.

Informations de la colonne « Type » :

  • M … obligatoire / requis
  • M* … obligatoire / requis dans certains pays ou sous certaines conditions
  • R ... recommandé
  • O... facultatif
Éléments Type Description
type M Type de position (DocumentPositionType)
texte O

Champ de texte libre

Informations sur le pays :

  • Imprimantes EPSON en Italie : envoyé à l’imprimante sous la forme messageType="4" (lignes de corps) ; 38 caractères maximum par position de texte. Un saut de ligne automatique intervient après 25 caractères. Le texte multiligne doit être segmenté en plusieurs positions. Il est également possible d’utiliser des textes d’en-tête et de Footer supplémentaires . Si aucun saut de ligne ne s’effectue après 25 caractères et que le texte est tronqué, veuillez contacter votre technicien de maintenance d’imprimante (mot-clé : « RT DESCR. OVERLAP »).
barcodeType O

Indication du type de Barcode

Énumération :

  • EAN8
  • EAN13
  • code128
Code-barres O Données du Barcode
PositionNumber M Numéro de position, commençant par 0

 

[3] = Réservation

Les positions de réservation (DocumentPositionBooking) sont utilisées pour les dépôts, les retraits ainsi que pour la vente de bons d’achat polyvalents (PayIn, payOut, MultiPurposeVoucher, etc.).

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

L'objet DocumentPositionBooking contient les informations suivantes.

Informations dans la colonne « Type » :

  • M … obligatoire / requis
  • M* … obligatoire / requis dans certains pays ou sous certaines conditions
  • R ... recommandé
  • O... facultatif
Éléments Type Description
type M Type de position (DocumentPositionType)
légende M Description de la position comptable
identifiant O Indicateur d’ID supplémentaire de l’écriture comptable
BusinessTransactionType M

Type de transaction commerciale.

Énumération :

  • [0] = Recette
  • [1] = Remise
  • [2] = Consigne sur les emballages vides
  • [3] = Bon d'achat à usage unique
  • [4] = MultiPurposeVoucher
  • [5] = Pourboire
  • [6] = Pourboire de l'entreprise
  • [7] = Consigne
  • [10] = Versement
  • [11] = PayIn
  • [90] = MoneyTransfer
  • [91] = Différence de trésorerie
  • [92] = Octroi d’une subvention
  • [93] = Octroi fictif
PayOutType M*

Indique le type de versement. Obligatoire dans certains pays.

Valeurs possibles :

  • [0] = Matériel de nettoyage
  • [1] = Fournitures de bureau
  • [2] = Frais postaux
  • [3] = Salaire
  • [4] = Rémunération
  • [5] = Achat de marchandises
  • [6] = AutresCoûts

Informations sur le pays :

  • Danemark : Informations obligatoires (« reportPayOut » et « PayOutType » dans SAF-T). Élément de type chaîne de caractères (string36) utilisé pour désigner le type de paiement.
Remarque : Nouveauté à partir de la version 1.2.0 de DOM / version 1.7.6 du client
VatIdentification M

ID du taux de VAT.

Peut être interrogé via GET /api/v1/information/client/{clientId}/getVatIdentification, en précisant le taux de Vat du pays concerné.
VatPercent M Taux de TVA en pourcentage
NetValue M

Montant net total de la ligne (déduction faite des remises) – hors Vat.

Doit toujours être indiqué.
GrossValue M

Montant total brut de la ligne (déduction faite des remises éventuelles) – TVA comprise.

Doit toujours être indiqué.
TaxValue M

Montant de la TVA de la ligne (déduction faite des remises éventuelles)

Doit toujours être indiqué.
AccountingIdentifier O Identifiant supplémentaire à des fins comptables (interface comptable)
ItemTaxType M*

Type de taxe de la position :

  • livraisons
  • services

Informations sur le pays :

  • Espagne : doit être sélectionné lors de la facturation de clients non espagnols.
PositionNumber M Numéro de poste, commençant par 0
positionReference O Spécification d’un numéro d’article de référence
cancellationPosition O « true » si cette position annule une position d’un autre document ; sinon « false ».
DeletedPosition O « true » si cette position a été supprimée ; sinon « false ».
CreateDate O Heure d'enregistrement de la position

 

[9] = Sous-total

Sous-total de la position

Remarque : la position « Sous-total » correspond à la position « Total ».

 

[10] = Total

Position « Total ». Si la position « DocumentPositionTotal » est utilisée, elle doit toujours être la dernière position du document (PositionNumber le plus élevé).

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

L'objet DocumentPositionTotal contient les informations suivantes.

Informations de la colonne « Type » :

  • M … obligatoire / requis
  • M* … obligatoire / requis dans certains pays ou sous certaines conditions
  • R ... recommandé
  • O... facultatif
Éléments Type Description
type M Type de position (DocumentPositionType)
arrondi O

arrondi appliqué. Si la somme des positions (valeur brute) n’est pas égale au montant du paiement.

Par exemple, la valeur 0,01 autoriserait des écarts d’arrondi de +/- 0,01

Remarque : veuillez utiliser cette option avec prudence. Des valeurs élevées désactiveront la validation du montant du paiement / de la valeur brute du document
BaseValue M* Montant de base du poste avant application des remises (uniquement si des remises sont appliquées)
valeur M Valeur de la position, remises comprises.
remises   Détails des remises, réductions de prix, etc.
  DiscountValue M

Montant de la remise / montant du rabais

Attention : si DiscountType [1] = discount, le montant de la remise doit être saisi avec 4 décimales !
  caption O Désignation de la remise
  DiscountOrder M*

Indique l'ordre dans lequel la remise est calculée. La première remise prise en compte a une valeur de 0.

Doit être spécifié si plusieurs remises sont appliquées à un article.
  type M

Type de remise

Énumération :

  • [0] = Remise forfaitaire – Remise sur le montant total
  • [1] = Remise – remise en pourcentage
  TypeValue M

Valeur de la remise (montant total de la réduction)

pour [0] = Remise : la DiscountValue

pour [1] = Remise : le pourcentage (par exemple, 10 % de remise)
  PromotionKeys O Clés de promotion – le cas échéant (par exemple, code promotionnel)
  identifiant O Identifiant supplémentaire pour la remise (pouvant servir, par exemple, à regrouper les remises par type).
légende O Désignation de la position
PositionNumber M Numéro de poste, commençant par 0
positionReference O Spécification d’un numéro de position auquel il convient de se référer
cancellationPosition O « true » si cette position annule une position d’un autre document ; sinon « false ».
DeletedPosition O « true » si cette position a été supprimée ; sinon « false ».
CreateDate O Heure d'enregistrement de la position

 

Cet article a été traduit automatiquement.

Articles associés

Commentaires

0 commentaire

Vous devez vous connecter pour laisser un commentaire.

Réalisé par Zendesk