Articles annexes

La plateforme et l'API Stockticket incluent la possibilité de proposer des articles annexes lors de la constitution du panier. Les propositions sont basées sur les articles déjà présents dans le panier et sur les règles de proposition d'articles annexes définies dans les modules de fourniture d'articles annexes associés au module de vente concerné.

Toutes les méthodes de gestion de panier retournant le détail du panier avec le modèle BasketDetailModel (ex: AddEventDate, GetDetail, RemoveItem, Validate, SetCustomFields,... ) incluent potientiellement des informations sur les articles annexes qui pourraient être ajouté au panier.
La méthode /Catalog/GetEventDateDetail permet également d'obtenir des propositions d'articles annexes basées sur une représentation d'événement spécifique.

Si des articles annexes sont disponibles, ils seront retournés dans la propriété ancillaries de la réponse.
La propriété ancillaries sera absente si aucune proposition n'est disponible.

Chaque article annexe inclut des détails tels que son nom, sa description, son prix, et d'autres informations pertinentes.

Configuration préalable

Afin de pouvoir obtenir des propositions d'articles annexes, le module de vente utilisé doit être configuré pour déclarer les modules qui fourniront les informations sur les articles annexes.
Il est nécessaire d'avoir associé au moins une instance de module de fourniture d'articles annexes au module de vente concerné dans le back-office StockTicket, dans le champ "Proposition d'articles annexes".

Screenshot

Tip

Afin de pouvoir sélectionner un module de fourniture dans la liste des "Proposition d'articles annexes",
vous devez au préalable avoir souscrit à une instance publique ou avoir créé votre propre instance d'un
module de type "Fourniture d'articles annexes" (AncillaryItemsProvider).

Info

Il est possible de sélectionner et d'associer plusieurs modules de fourniture d'articles annexes à un module de vente.
Les méthodes d'API fourniront alors les informations sur les articles annexes fournies par chacun des modules fournisseurs associés.

Principe de fonctionnement

Lorsqu'une méthode de gestion de panier ou la méthode GetEventDateDetail est appelée, la plateforme Stockticket identifie les modules de fourniture d'articles annexes associés au module de vente concerné.
Elle les interroge ensuite pour obtenir les propositions d'articles annexes basées sur le contenu du panier ou la représentation d'événement spécifique.

Chaque module de fourniture d'articles annexes peut appliquer ses propres règles de proposition pour déterminer quels articles annexes proposer. Les propositions d'articles annexes retournées par les modules fournisseurs sont ensuite agrégées et incluses dans la réponse de l'API, permettant ainsi au client de les présenter à l'utilisateur final.

La methode d'API SetAncillaryItem permet ensuite d'ajouter (ou de modifier) un article annexe proposé au panier, en précisant l'article annexe à ajouter et la quantité (ou les autres informations attendues selon le type d'articles).

Modification du panier

La sélection d'un article annexe et son ajout au panier via la méthode SetAncillaryItem peuvent entraîner une modification d'autres éléments du panier (ex: ajout d'éléments, suppression d'éléments, modification d'éléments, etc...). Pour cette raison, la méthode SetAncillaryItem retourne le détail du panier mis à jour après l'ajout de l'article annexe, incluant les nouvelles propositions d'articles annexes basées sur le nouveau contenu du panier. Il est donc recommandé de relire les données du panier après chaque ajout d'article annexe.

Plus généralement, toute modification du panier peut entraîner la modification des propositions d'articles annexes. Il est donc conseillé de s'assurer que l'article que l'on souhaite sélectionner est toujours disponible dans la dernière réponse de panier reçue.

La méthode permet également de supprimer un article annexe déjà ajouté au panier en précisant une quantité nulle pour cet article annexe, ou en utilisant une valeur booléenne négative selon le type d'article annexe.

Types d'articles annexes

Il existe différents types d'articles annexes qui peuvent être proposés, tels que des produits physiques, des services, etc...

Les principaux types fonctionnels d'articles annexes sont les suivants :

Produit physique
Service
Réduction
Assurance
Combiné

Vous pouvez trouver plus d'informations sur les différents types d'articles annexes en vous référant à la description du type AncillaryItemTypeEnum dans la documentation dynamique de l'API (L'url de la documentation dynamique est fournie dans la rubrique "Prise en main").

Organisation des articles annexes

Les articles peuvent être rattachés à un parent à différents niveaux :

Globalement, pour tout le panier (la commande : Order)
Au niveau d'un 'produit' particulier (ex: "Le concert du 3 avril à 20h") : Items.
Au niveau d'un 'produit' à un 'tarif' particulier (ex: "Le concert du 3 avri à 20h" en "tarif réduit") : Items/Lines.
Au niveau d'un élément spécifique du panier (ex: un billet particulier) : `Items/Lines/Items'.

S'il y a un rattachement à un élément parent spécifique, l'identifiant de ce parent est précisé dans la propriété parentId de l'article annexe, et le niveau de rattachement est précisé dans la propriété attachment de l'article annexe.
Les niveaux de rattachement possibles sont décrits dans le type AncillaryAttachmentEnum.

Description des propriétés d'un article annexe (`AncillaryItemModel`)

Le type AncillaryItemModel représente un article annexe proposable au client (ex: parking, assurance, vestiaire, goodies, etc.).

Propriété	Type	Description
`id`	`string`	Identifiant unique de l’article annexe.
`label`	`string`	Libellé de l’article (ex: `Parking`, `Vestiaire`).
`description`	`string?`	Description complémentaire affichable côté client.
`currency`	`string`	Code devise (par défaut `EUR`).
`unitPrice`	`TaxableAmount`	Prix unitaire de l’article (HT/TVA/TTC).
`discount`	`TaxableAmount`	Remise appliquée à l’article (HT/TVA/TTC).
`unitLabel`	`string?`	Libellé singulier de l’unité (ex: `t-shirt`).
`unitLabelPlural`	`string?`	Libellé pluriel de l’unité (ex: `t-shirts`).
`ancillaryItemType`	`AncillaryItemTypeEnum`	Type fonctionnel de l’article annexe.
`promptMode`	`AncillaryItemPromptModeEnum`	Mode d’affichage/saisie côté UI client.
`attachment`	`AncillaryAttachmentEnum`	Niveau de rattachement (représentation, catégorie tarifaire, unité), si appliacble.
`parentId`	`string?`	Identifiant de l’élément parent auquel l’article est lié, si applicable.
`minQuantity`	`int?`	Quantité minimale autorisée/suggérée.
`maxQuantity`	`int?`	Non

Sous-types attachés

`AncillaryItemTypeEnum`

Définit la nature fonctionnelle de l’article annexe :

Valeur	Signification
`Undefined` (`0`)	Type non défini.
`PhysicalProduct` (`1`)	Produit physique.
`Service` (`2`)	Service.
`Discount` (`3`)	Réduction.
`Insurance` (`4`)	Assurance.
`Package` (`5`)	Offre combinée / package.

Remarques : les articles de type Discount affichent un prix négatif et sont destinés à être utilisés pour appliquer des remises au panier.

`AncillaryItemPromptModeEnum`

Définit le comportement attendu de l’interface utilisateur pour la sélection :

Valeur	Signification
`Auto`	Mode déterminé automatiquement par le fournisseur selon le contexte.
`ActionButton`	Bouton d’action simple (ajout direct, sans quantité).
`SingleQuantityInput`	Saisie d’une quantité globale.
`SingleBooleanInput`	Saisie booléenne (case à cocher).
`PerParentQuantityInput`	Saisie de quantité par élément parent.
`PerParentBooleanInput`	Saisie booléenne par élément parent.

Remarques :

Le mode ActionButton est utilisé pour les articles annexes qui peuvent être sélectionnés directement au panier sans saisie de quantité. Leur sélection entraine les modifications du panier associées à l’article annexe et ne tient pas compte du paramètre "quantity".
Les modes SingleQuantityInput et SingleBooleanInput sont utilisés pour les articles annexes qui ne nécessitent pas d’identification d’élément parent spécifique. Leur sélection entraine l'ajout ou la modification de l’article annexe dans le panier avec la quantité ou la valeur booléenne saisie, dans un groupe indépendant dans le panier.
Les modes PerParentQuantityInput et PerParentBooleanInput sont utilisés pour les articles annexes liés à un élément parent spécifique (ex: tarif, représentation,...) et nécessitent l’identification de ces éléments via le paramètre parentId.

Les modes de saisie de type xxBooleanInput attendent une valeur booléenne (ex: true/false) qui devra être renseignée dans la propriété boolValue de la méthode SetAncillaryItem,
tandis que les autres modes attendent une valeur numérique pour la quantité qui sera renseignée dans la propriété quantity.

`AncillaryAttachmentEnum`

Définit le niveau de rattachement de l’article annexe :

Valeur	Signification	Note
`Product` (`10`)	Rattaché à la représentation/produit global.	Groupe dans le panier
`ProductPriceType` (`15`)	Rattaché à la catégorie tarifaire.	Ligne dans le panier
`ProductUnit` (`20`)	Rattaché à l’unité (ex: par billet).	Elément item dans le panier

`TaxableAmount`

Structure monétaire utilisée par unitPrice et discount :

Propriété	Type	Description
`excVAT`	`double`	Montant HT.
`vatRate`	`double`	Taux de TVA (ex: `0.20`).
`vat`	`double`	Montant de TVA calculé (`excVAT * vatRate`).
`incVAT`	`double`	Montant TTC calculé (`excVAT * (1 + vatRate)`).

Recommandations d’implémentation côté client

Toujours relire les données de ancillaries après chaque modification du panier.
Respecter minQuantity / maxQuantity lors de la saisie.
Adapter l’UI au promptMode reçu.
Interpréter la portée fonctionnelle via attachment avant l’ajout via la méthode SetAncillaryItem.