Module de fourniture d'articles annexes

Un module de fourniture d’articles annexes permet à StockTicket de proposer, pré-réserver et réserver des articles complémentaires pendant la constitution d’un panier.

Il est possible de développer son propre module compatible avec StockTicket, puis de le déclarer dans l’environnement StockTicket en tant que module de type AncillaryItemsProvider.

Le module doit implémenter et exposer les 3 méthodes suivantes :

GetAncillaries(GetAncillariesRequestModel request, CancellationToken cancellationToken) retourne un GetAncillariesResponseModel
Cette méthode est appelée par StockTicket pour obtenir les propositions d’articles annexes en fonction du contexte courant (panier, catalogue, représentation).
SetAncillariesSelection(SetAncillariesSelectionRequestModel request, CancellationToken cancellationToken) retourne un SetAncillariesSelectionResponseModel
Cette méthode est appelée par StockTicket lorsqu’un utilisateur sélectionne ou désélectionne un article annexe dans le panier.
Elle permet au module de gérer la pré-réservation ou la libération de l’article annexe côté fournisseur.
BookAncillaries(BookAncillariesRequestModel request, CancellationToken cancellationToken) retourne un BookAncillariesResponseModel Cette méthode est appelée par StockTicket lors de la validation finale du panier pour confirmer définitivement les réservations côté fournisseur.

StockTicket utilise ces méthodes lorsqu’un module de vente est configuré pour utiliser un ou plusieurs fournisseurs d’articles annexes.

Principe d’appel des méthodes

Lorsqu’une opération de panier ou de catalogue nécessite des propositions d’articles annexes, StockTicket interroge les modules de type AncillaryItemsProvider associés au module de vente courant.

sequenceDiagram
Application cliente-->>API StockTicket: Appel API panier / catalogue
API StockTicket-->>Module de vente: Résolution du contexte courant
API StockTicket-->>Module AncillaryItemsProvider: GetAncillaries(...)
Module AncillaryItemsProvider-->>API StockTicket: GetAncillariesResponseModel
API StockTicket-->>Application cliente: Panier + ancillaries

Lorsqu’un utilisateur sélectionne un article annexe, StockTicket appelle SetAncillariesSelection(...) afin d’informer le module fournisseur de la sélection ou de la désélection.

sequenceDiagram
Application cliente-->>API StockTicket: Sélection d'un article annexe
API StockTicket-->>Module AncillaryItemsProvider: SetAncillariesSelection(...)
Module AncillaryItemsProvider-->>API StockTicket: SetAncillariesSelectionResponseModel
API StockTicket-->>Application cliente: Panier mis à jour

Lors de la validation finale du panier, StockTicket appelle BookAncillaries(...) pour confirmer définitivement les réservations côté fournisseur.

sequenceDiagram
Application cliente-->>API StockTicket: Validation du panier
API StockTicket-->>Module AncillaryItemsProvider: BookAncillaries(...)
Module AncillaryItemsProvider-->>API StockTicket: BookAncillariesResponseModel
API StockTicket-->>Application cliente: Confirmation

Contrat de façade à implémenter

`GetAncillaries(GetAncillariesRequestModel, CancellationToken)`

Cette méthode retourne les ancillaires proposés en fonction du contexte courant.

`GetAncillariesRequestModel`

ModuleDefinitionId (string)
Identifiant de la définition du module cible.
ModuleInstanceId (string)
Identifiant de l’instance du module cible.
EventDateId (string?)
Identifiant d’une représentation si la demande porte sur une représentation spécifique.
BasketDetail (BasketDetailModel?)
Détail du panier courant.

`GetAncillariesResponseModel`

AncillariesSuggestions (List<AncillarySupplierInfosModel>)
Liste des suggestions retournées par le module.

AncillarySupplierInfosModel contient :

ModuleDefinitionIdSupplier (string)
Identifiant de la définition du fournisseur.
ModuleInstanceIdSupplier (string)
Identifiant de l’instance du fournisseur.
AncillaryItems (List<AncillaryItemModel>)
Liste des articles annexes proposés.

`SetAncillariesSelection(SetAncillariesSelectionRequestModel, CancellationToken)`

Cette méthode informe le module d’une modification de sélection d’article annexe.

Elle peut correspondre à : - un ajout, - une modification de quantité, - une suppression, - ou une libération de pré-réservation.

`SetAncillariesSelectionRequestModel`

ModuleDefinitionId (string)
Identifiant de la définition du module cible.
ModuleInstanceId (string)
Identifiant de l’instance du module cible.
BasketId (string)
Identifiant du panier concerné.
AncillaryItemId (string)
Identifiant StockTicket de l’article annexe.
ExternalItemId (string?)
Identifiant externe côté fournisseur, si applicable.
Quantity (int)
Quantité à pré-réserver ou à libérer.
Attachment (AncillaryAttachmentEnum)
Niveau de rattachement de l’article annexe.
ParentId (string?)
Identifiant du parent si l’article annexe est rattaché à un élément spécifique.
BasketDetail (BasketDetailModel?)
Détail du panier courant.

`SetAncillariesSelectionResponseModel`

IsSuccess (bool)
Indique si l’appel a réussi.
ErrorMessage (string?)
Message d’erreur en cas d’échec.
HoldId (string)
Identifiant de pré-réservation côté fournisseur.
BasketActions (List<AncillaryBasketActionModel>)
Actions complémentaires à appliquer au panier.

AncillaryBasketActionModel :

Action (AncillaryBasketActionEnum)
Action à exécuter.
ActionDataJson (string)
Données JSON associées à l’action.

Valeurs supportées actuellement :

AddEventDateItem
RemoveItem

`BookAncillaries(BookAncillariesRequestModel, CancellationToken)`

Cette méthode confirme définitivement les ancillaires pré-réservés lors de la validation du panier.

`BookAncillariesRequestModel`

ModuleDefinitionId (string)
Identifiant de la définition du module cible.
ModuleInstanceId (string)
Identifiant de l’instance du module cible.

`BookAncillariesResponseModel`

ExternalOrderId (string)
Identifiant de commande côté fournisseur externe.

Recommandations d’implémentation

Implémenter la façade via AbstractClientSideAncillariesModuleFacade.
Retourner des identifiants stables pour les pré-réservations et les réservations.
Gérer l’idempotence des appels de sélection.
Respecter le rattachement fonctionnel des articles annexes via attachment et parentId.
Prévoir la libération des pré-réservations non confirmées en cas d’annulation de panier.
Recalculer les suggestions après chaque modification significative du panier.