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 RetailForce website (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 :
Vous trouverez les explications relatives à chaque type (DocumentPositionType) à la suite de ce tableau. |
|
| AdditionalFields | O | ||
| {...} | |||
| CreateDate | M | Date et heure de création de la position. | |
| ExternalIdentifier | O | Identifiant externe (provenant du système précédent), à des fins internes, 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) désigne 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": "Quantity"
},
"itemId": "1028",
"itemType": "[0] = Article",
"baseNetValue": 14.08,
"baseGrossValue": 16.90,
"baseTaxValue": 2.82,
"baseTaxValue2": 0,
"gtin": "8718274490558",
"businessTransactionType": 0,
"itemTypeClassification": "[1] = AlcoholicBeverage",
"vatIdentification": 1,
"vatPercent": 20.00,
"vatPercent2": 5,
"additionalTax": {
"additionalTaxType": "alcohol",
"additionalTaxTypeIdentification": "string",
"taxPercent": 0,
"taxValue": 0
},
"netValue": 12.68,
"grossValue": 15.21,
"taxValue": 2.53,
"taxValue2": 0,
"accountingIdentifier": null,
"itemTaxType": null,
"positionNumber": 0,
"positionReference": null,
"cancellationPosition": false,
"deletedPosition": false,
"additionalFields": {},
"createDate": null,
"externalIdentifier": [
"string"
],
"user": {
"id": "string",
"caption": "string",
"firstName": "string",
"lastName": "string",
"taxNumber": "string"
},
"salesPerson": {
"id": "string",
"caption": "string",
"firstName": "string",
"lastName": "string",
"taxNumber": "string"
},
"FiscalAdditionalFields": {}
}
],L'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 Informations sur le pays :
|
|
| ItemShortCaption | O | Désignation abrégée de l’article, utilisée notamment en présence de contraintes sur la longueur des chaînes de caractères, telles que celles imposées par les imprimantes fiscales. | |
| ItemSerialNumber | M* |
Numéro de série de l'article. Informations spécifiques au pays :
|
|
| 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 :
|
|
| DiscountOrder | M* |
Il indique l’ordre de calcul de la remise. La première remise prise en compte porte la valeur 0. Doit être spécifié si plusieurs remises sont appliquées à un article. |
|
| type | M |
Type de remise Énumération :
|
|
| TypeValue | M |
Valeur de la remise (montant total de la réduction) pour [0] = Remise : la DiscountValue (=> DiscountValue = TypeValue) pour [1] = Remise : le taux (par ex. 10 % de remise) |
|
| PromotionKeys | O | Clés de promotion – le cas échéant (par ex. 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-articles (SubItems) doit être repris et si la TVA de l’article parent doit être ignorée ; sinon « false ». Valeur par défaut (si non transmise) : « true ». Si la valeur est « true », chaque sous-poste doit comporter un VatIdentification et la somme des valeurs brutes, nettes et fiscales des sous-postes doit être égale aux valeurs BaseGrossValue, BaseNetValue et BaseTaxValue du poste parent ; dans le cas contraire, le document est refusé. | |
| SubItems | O | Détails des SubItems. Voir : DocumentPositionType [1] = SubItem | |
| [...] | |||
| inhouse | O | Indique s'il s'agit d'une vente interne ou externe (true / faux). | |
| ItemGroupId | M* |
Indicateur de groupe d'articles Informations par pays :
|
|
| ItemGroupCaption | O |
Désignation du groupe d'articles Détails par pays :
|
|
| CostPrice | O/M* |
Prix unitaire de l'article Détails par pays :
|
|
| itemDateOfEntry | M* |
Date et heure de création de l'article. Détails par pays :
|
|
| quantité | M |
Informations relatives à la quantité de l’article Détails par pays :
|
|
| QuantityUnit | M* |
Spécification de l'unité de mesure Détails par pays :
|
|
| ID | M* |
Indication de l'unité de mesure. Détails par pays :
|
|
| isoCode | M* |
Unité de mesure standard, transmise sous la forme du nom d’une valeur QuantityUnitIsoCode (par exemple « Quantity » pour les pièces, « Kilogram »), et non sous la forme du code ISO/UCUM lui-même. Le module convertit le nom en code ISO/UCUM (par exemple « Quantity » = « 1 »). Un nombre est interprété comme la valeur numérique de l’enum ; ainsi, « 1 » signifie « Pourcentage ». Pour plus d’informations, consultez l’article lié. Informations par pays :
|
|
| ItemId | M |
ID de l'article Informations sur le pays :
|
|
| ItemType | M* |
Décrit le type d'élément : biens ou services.
Informations relatives au pays :
|
|
| BaseNetValue | M* |
Total net (hors TVA) avant remise ou majoration
Remarque : 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
Attention :
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 :
|
|
| BaseTaxValue2 | M* |
Somme du deuxième taux de taxe applicable à la ligne avant remise ou supplément. Détails du pays :
|
|
| GTIN | O/R |
Numéro d'article commercial mondial (GTIN) Informations sur le pays :
|
|
| BusinessTransactionType | M |
Type de transaction commerciale. Énumération :
|
|
| ItemTypeClassification | O/M* |
La propriété « ItemTypeClassification » permet d’appliquer une classification supplémentaire à un article. La propriété « ItemTypeClassification » ne peut être définie que si la propriété « ItemType » a été configurée sur la valeur « [0] - Article » ou « ItemType » : 0. Pour des informations détaillées sur la propriété « ItemTypeClassification », veuillez consulter l’article lié. Les classifications suivantes sont disponibles.
Détails par pays :
|
|
| VatIdentification | M |
ID du taux de Vat. Il peut être interrogé via la requête GET /api/v1/information/client/{clientId}/getVatIdentification, en précisant le taux de TVA du 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 :
|
|
| VatPercent2 | M* |
Deuxième taux d'imposition applicable à l'article, exprimé en pourcentage dans le pays concerné. Détails du pays :
|
|
| 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 taxe (ou somme du premier taux d’imposition) du poste (déduction faite des remises / majoré des suppléments) Doit toujours être indiqué. Informations sur le pays :
|
|
| TaxValue2 | M* |
Somme du deuxième taux d'imposition de l'article après remise / majoration. Détails du pays :
|
|
| AccountingIdentifier | O | Identifiant supplémentaire à des fins comptables (interface comptable) | |
| ItemTaxType | M* |
Type de taxe de la position :
Informations sur le pays :
|
|
| PositionNumber | M | Numéro de poste, commençant par 0 | |
| positionReference | O | Spécification d’un numéro de position de référence | |
| cancellationPosition | O/M* | « true » si cette position annule une position d’un autre document ; sinon « false » | |
| CreateDate | O | Date et 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 la description des groupes de produits au niveau de chaque article.
Exemple : Menu = Coca-Cola et hamburger.
L’utilisation des SubItems n’est pas obligatoire. Si l’article parent présente la valeur « UseSubItemVatCalculation » : true (valeur par défaut), la TVA des SubItems s’applique à la place de celle de l’article parent et leurs valeurs doivent correspondre à la somme des valeurs de base de l’article parent. Avec « UseSubItemVatCalculation » : false, la TVA de l’article parent s’applique et les SubItems servent uniquement à détailler la composition de l’article.
[2] = Texte
Permet de définir la position d’un texte ou d’un Barcode au sein du 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 :
|
|
| barcodeType | O |
Indication du type de Barcode Énumération :
|
|
| Code-barres | O | Données du code-barres | |
| 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 (PayIn), les retraits (PayOut) ainsi que pour la vente de bons d’achat polyvalents (MultiPurposeVoucher, etc.).
Exemple 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": {}
}
],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 :
|
|
| PayOutType | M* |
Indique le type de versement. Obligatoire dans certains pays. Valeurs possibles :
Informations par pays :
Remarque :
Nouveauté à partir de la version DOM v1.2.0 / Client v1.7.6
|
|
| VatIdentification | M |
ID du taux de TVA. Cette ressource peut être interrogée via une requête GET sur l’URL /api/v1/information/client/{clientId}/getVatIdentification, en précisant le taux de VAT applicable au 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 taxe sur la valeur ajoutée (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 :
Informations sur le pays :
|
|
| 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
[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. L’arrondi est ajouté à la somme des valeurs brutes des postes de l’opération et des postes comptables, et la somme des paiements doit correspondre exactement à ce résultat. Il s’agit d’un montant signé, et non d’une tolérance : par exemple, -0,02 signifie que les paiements sont inférieurs de 0,02 à la somme brute des postes, tandis que 0,01 signifie qu’ils sont exactement supérieurs de 0,01. Remarque : veuillez utiliser cette option avec précaution. Si l’écart entre les paiements et les postes ne correspond pas exactement à cette valeur, le document est refusé. |
|
| BaseValue | M* | Montant de base de la position 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 de calcul de la remise. La première remise prise en compte porte la valeur 0. Doit être spécifié si plusieurs remises sont appliquées à un article. |
|
| type | M |
Type de remise Énumération :
|
|
| TypeValue | M |
Valeur de la remise (montant total de la réduction) pour [0] = Remise : la DiscountValue si [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). | |
| légende | O | Désignation de la position | |
| PositionNumber | M | Numéro de position, commençant à 0 | |
| positionReference | O | Spécification d'un numéro de position 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 | |
Cet article a été traduit automatiquement.
Commentaires
0 commentaire
Vous devez vous connecter pour laisser un commentaire.