Medusa Extend · Cas pratique
Gérer le dépôt-vente avec Medusa
Des produits confiés à des boutiques. Des ventes, des retours, des écarts de stock. Comment organiser un système commercial de dépôt-vente dans Medusa ?
Une boutique souhaite vendre les produits d'une marque sans les acheter à l'avance. La marque lui confie donc des produits, qui restent sa propriété jusqu'à leur vente. La boutique paie à la marque les produits vendus, selon ce qu'elles ont convenu. Les invendus peuvent être renvoyés à la marque : c'est le principe du dépôt-vente.
Le principe du dépôt-vente
La marque confie des produits à la boutique ; la boutique déclare ses ventes à la marque.
Marque
Boutique
Pour gérer cette activité avec plusieurs boutiques, l'outil dans Medusa doit permettre à la marque de :
- préparer avec chaque boutique une demande de mise en dépôt, en révisant les références et les quantités, puis la valider ou l'annuler ;
- suivre les envois et leur réception, ainsi que les quantités en transit et celles présentes dans chaque boutique ;
- enregistrer les relevés de ventes que les boutiques déclarent pour chaque période ;
- organiser et suivre les retours d'invendus, même lorsqu'ils regroupent des produits arrivés par plusieurs envois ;
- conserver les inventaires transmis par les boutiques, les comparer au stock attendu et examiner les écarts avant de valider tout ajustement.
Ce suivi permet à la marque de consulter la situation de chaque boutique et d'avoir une vue d'ensemble pour piloter son activité de dépôt-vente.
S'appuyer sur les modules de Medusa
Medusa est un moteur e-commerce organisé en modules prêts à l'emploi. Chaque module gère les informations et les opérations d'un domaine du commerce. Plutôt que de réécrire la gestion du catalogue, des stocks et de la logistique, nous construisons notre système à partir de ces modules.
Notre système de dépôt-vente va s'appuyer sur cinq de ces modules :
- Product gère le catalogue. Chaque variante correspond à une référence que la marque peut envoyer, vendre ou compter.
- Stock Location référence les lieux de stockage, dont l'entrepôt de la marque et le lieu de chaque boutique partenaire.
- Inventory tient, pour chaque référence et chaque lieu, la quantité en stock et les quantités réservées. Pour une boutique, la quantité en stock enregistrée forme son stock attendu : ce qu'elle devrait avoir d'après les envois, ventes et retours déjà saisis.
- Fulfillment enregistre les envois, les références et quantités qu'ils contiennent, ainsi que les dates de préparation, d'expédition et de livraison.
- Order enregistre les ventes, ici celles que déclarent les boutiques.
Les modules déjà disponibles
-
Product
catalogue
-
Stock Location
lieux
-
Inventory
quantités
-
Fulfillment
envois
-
Order
ventes
Construire un module de dépôt-vente
Les modules natifs tiennent le catalogue, le stock, les envois et les ventes. Le dépôt-vente produit en plus des documents échangés entre la marque et chaque boutique : des accords, des déclarations, des comptages. Ces documents propres au dépôt-vente n'ont pas de modèle dédié dans Medusa. Nous avons besoin de conserver quatre types de documents :
- Les demandes de mise en dépôt (Requests) : une boutique, les lignes proposées puis retenues pour chaque référence, les révisions successives et l'état de la demande.
- Les relevés de ventes (Sales Reports) : une boutique, une période, une date de déclaration, les lignes déclarées avec quantités et montants, et l'état de traitement du relevé.
- Les retours d'invendus (Returns) : un document global pour une boutique, qui peut regrouper des produits arrivés par plusieurs envois, avec les lignes déclarées puis reçues, sa date et son état.
- Les inventaires (Stock Counts) : un comptage daté transmis par la boutique, les quantités comptées, l'écart initial avec le stock attendu, puis les explications et la décision retenues.
Ces documents gardent ce qui a été convenu ou déclaré. Les envois restent dans Fulfillment, avec leurs propres dates, et les ventes validées sont enregistrées dans Order.
Nous créons donc un module de dépôt-vente qui regroupe ces quatre ensembles. Ses entités sont les modèles qui enregistrent les documents et leurs lignes, avec leurs révisions lorsque l'historique compte.
Un module, quatre ensembles de données
Module de dépôt-vente
- Demandes de mise en dépôt
- Relevés de ventes
- Retours d’invendus
- Inventaires
Son service expose les opérations que le reste de l'application utilise : créer un document, le lire, lister ceux d'une boutique, le modifier, supprimer un brouillon, faire évoluer son état. MedusaService fournit les méthodes courantes de gestion des modèles. Le module y ajoute ses propres règles : une demande annulée, par exemple, ne peut plus être validée.
Des workflows pour orchestrer chaque opération
Chaque information a maintenant sa place. Il reste à les faire évoluer ensemble, car une même action de la marque touche souvent plusieurs modules. Envoyer des produits en dépôt, par exemple, fait avancer la demande dans le module de dépôt-vente, crée un envoi dans Fulfillment et déplace des quantités dans Inventory. Un workflow coordonne ces changements : il appelle dans l'ordre les opérations de chaque module, et chaque module applique ses propres règles.
Tant que la marque et la boutique discutent, seule la demande change. La créer, la réviser, la valider ou l'annuler ne réserve rien et ne déplace aucun stock. Une fois la demande validée, la marque peut préparer l'envoi. Le workflow crée alors l'envoi dans Fulfillment et réserve les quantités à l'entrepôt, pour qu'elles ne partent pas ailleurs. À l'expédition, il retire ces quantités du stock de l'entrepôt et libère la réservation. Quand la marque confirme la réception dans l'Admin, le workflow date la livraison dans Fulfillment et ajoute les quantités au stock de la boutique.
Entre l'expédition et la réception, les produits ont quitté le stock de l'entrepôt sans figurer encore dans celui de la boutique. Pour connaître les quantités en transit, la marque additionne celles des envois expédiés et pas encore reçus. Ce calcul suffit parce que, dans ce cas, chaque envoi est reçu en entier.
| Événement | Entrepôt | En transitcalculé | Boutique |
|---|---|---|---|
| Demande validée | 12 | 0 | 0 |
| Préparation de l’envoi | 12dont 12 réservées | 0 | 0 |
| Expédition | 0 | 12 | 0 |
| Réception | 0 | 0 | 12 |
Les ventes suivent un autre chemin : les produits ont déjà été livrés à la boutique, puis vendus à ses clients. Quand la marque valide un relevé, le workflow retire les quantités vendues du stock de la boutique et enregistre ces ventes dans Order. Ce workflow ne crée aucun nouvel envoi et ne retire le stock qu'une fois.
Workflow de validation d’un relevé de ventes
-
Dépôt-vente
-
Inventory
-
Order
Le retour d'invendus refait le trajet en sens inverse. Son transport s'enregistre dans Fulfillment comme un envoi de la boutique vers l'entrepôt, même s'il regroupe des produits arrivés par plusieurs envois. À l'expédition, les quantités quittent le stock de la boutique. À la réception, elles entrent dans celui de l'entrepôt.
Un retour pour plusieurs envois
Deux envois partent de l’entrepôt vers la boutique ; un seul retour d’invendus revient de la boutique vers l’entrepôt.
Entrepôt
Boutique
L'inventaire sert à vérifier le stock de la boutique, mais sa déclaration ne le modifie pas. Le workflow compare les quantités comptées au stock attendu à la date du comptage et fait apparaître les écarts. Un écart n'est pas forcément une perte : des ventes de la période peuvent ne pas encore avoir été déclarées. La marque vérifie donc d'abord s'il manque des relevés pour cette période. S'il en manque, elle les traite avant de décider d'un ajustement. L'inventaire garde son constat initial, sa date et le motif retenu. Si un écart demeure après ce traitement, la marque décide s'il faut ajuster le stock. Dans ce cas seulement, elle motive l'ajustement et le valide, puis le workflow modifie le stock de la boutique.
Examiner un écart d’inventaire
-
Écart constaté
-
Vérifier les relevés
-
Décision humaine
- Stock conservé
- Ajustement motivé et validé
Une action peut aussi être lancée deux fois, ou s'interrompre en cours de route. Les workflows doivent donc garder la trace des mouvements déjà effectués, pour qu'une reprise ne retire ni n'ajoute deux fois les mêmes quantités.
Il faut enfin pouvoir déclencher ces workflows depuis une interface. L'Admin, l'interface d'administration de Medusa, appelle des routes d'API, et chaque route déclenche un workflow : créer une demande, préparer un envoi, valider un relevé. Un portail réservé aux boutiques disposerait de ses propres routes, limitées aux données de chaque boutique. Ces routes appelleraient les mêmes workflows.
Deux interfaces, les mêmes workflows
L’Admin passe par l’API Admin, le portail boutiques optionnel par l’API boutiques ; les deux appellent les mêmes workflows de dépôt-vente.
Utiliser le dépôt-vente dans l'Admin de Medusa
Pour explorer ce module, nous avons construit un prototype interactif de l'Admin. Ses écrans, comme les mouvements de stock et les commandes qu'ils affichent, sont simulés dans le navigateur avec des données de démonstration : rien n'y est encore relié au module serveur. Une marque, quatre boutiques et trois entreprises suffisent pour en faire le tour.
Agrandir la captureSavoir qui doit agir
Dans le menu de l'Admin, un clic sur Consignment ouvre l'accueil du dépôt-vente ; trois sous-entrées mènent ensuite à Stock, Sales et Locations. L'accueil rassemble toutes les opérations dans une même table, filtrable par type et par état : demandes de mise en dépôt, retours, relevés de ventes et comptages. La colonne Next step répond à la question qu'on se pose en arrivant : qui doit agir ? Admin action signale une tâche pour la marque, Location une action attendue de la boutique, Delivery une livraison à confirmer. Une opération terminée indique No action needed, et un relevé enregistré renvoie directement à sa commande.
Le stock sous trois angles
La page Stock présente les mêmes unités confiées par boutique, par entreprise ou par produit. Elle distingue deux quantités : le stock comptabilisé (Book stock), encore enregistré pour la boutique, et le disponible (Available), encore à vendre. Les ventes déclarées en attente et les retours annoncés sont déjà exclus du disponible ; quand le relevé est enregistré ou le retour expédié, seul le stock comptabilisé diminue. Incoming et Returning montrent les unités en route, vers la boutique ou vers l'entrepôt.
Agrandir la capture
Agrandir la capture
Agrandir la captureUne entreprise, deux boutiques
Une même entreprise peut tenir plusieurs boutiques : StrideHouse Retail exploite StrideHouse à Lyon et Corner Run à Bordeaux. Sa fiche, ouverte depuis la vue By company, aligne les deux boutiques avec leur stock et leurs ventes, puis leur total. Deux onglets détaillent le stock et les ventes par produit, et chaque ligne mène à la boutique concernée.
Agrandir la captureUne boutique et son historique
La fiche d'une boutique réunit ses opérations, son stock, ses ventes et son activité. La marque y demande un nouvel envoi ou un comptage. L'onglet Activity retrace chaque étape avec l'opération concernée et son origine : une action de la marque, ou une confirmation de la boutique saisie dans l'Admin.
Agrandir la capture
Agrandir la captureSuivre une mise en dépôt
Une demande commence en brouillon, avec sa boutique et ses produits, puis elle est soumise à l'accord de la boutique. Une fois l'envoi expédié depuis l'entrepôt, ses unités apparaissent en Incoming et la page attend la confirmation de livraison. Le bouton Record receipt l'enregistre : les unités entrent alors dans le stock de la boutique.
Agrandir la captureDes ventes déclarées aux commandes
La page Sales reprend les trois vues du stock, sur une période choisie. Seuls les relevés enregistrés comptent dans le bilan. Un relevé soumis mais pas encore enregistré reste à part, sous Not yet recorded, comme les 8 unités déclarées par Harbor Steps ; les brouillons sont ignorés.
Agrandir la capture
Agrandir la capture
Agrandir la captureEnregistrer un relevé diminue le stock de la boutique et crée une commande dans Order. Relevé et commande restent distincts et se renvoient l'un à l'autre : SR-3001 affiche la commande #1041, qui rappelle à son tour son relevé, sa boutique et l'absence d'expédition, puisque les produits ont été vendus en boutique.
Agrandir la capture
Agrandir la captureRetours et comptages
Un retour déclaré rend aussitôt ses unités indisponibles à la vente. La boutique l'expédie ensuite, puis l'entrepôt confirme sa réception.
Agrandir la captureUn comptage, lui, ne change rien tant qu'il n'est pas validé. La page compare quantité attendue et quantité comptée, et chaque écart demande un motif choisi ligne par ligne avant la validation, qui le transforme en ajustement.
Agrandir la captureCe que le dépôt-vente montre de Medusa
Ce cas montre une façon d'étendre Medusa : réemployer les briques en place et leur ajouter un module pour ce qui appartient au métier. Produits, emplacements de stock, envois et commandes restent portés par les modules existants. Le module de dépôt-vente modélise les opérations avec les boutiques, leurs états et leurs règles, puis les workflows coordonnent chaque opération entre ce module et les autres, chacun conservant ses propres règles.
Pour la marque, le résultat se lit dans l'Admin de Medusa. Elle voit ce que chaque boutique détient, ce qui a été vendu et qui doit agir ensuite, et ses ventes rejoignent les commandes qu'elle suit déjà.










