Guide du module Pont PDV ↔ Boutique

Connectez le catalogue de votre point de vente, le stock de vos entrepôts et l’historique des ventes à votre boutique en ligne. Vendez les produits du POS sur le web, gardez l’inventaire synchronisé automatiquement et consultez côte à côte les ventes au comptoir et sur le web dans un historique unifié.

Cas d’utilisation

Commerce physique et en ligne (brick-and-click)

Vous exploitez un magasin physique équipé d’un système POS et souhaitez vendre les mêmes produits en ligne. Le pont vous permet de gérer votre catalogue une seule fois dans le POS et de publier les produits vers la boutique sans dupliquer la saisie. L’inventaire reste synchronisé automatiquement.

Rapports de ventes unifiés

Les ventes au comptoir comme les commandes web apparaissent dans l’historique des ventes POS sous les mêmes rapports. Les commandes web sont étiquetées avec le canal web afin que vous puissiez les filtrer séparément des transactions en magasin.

Catalogue en ligne sélectif

Tous les produits POS n’ont pas vocation à être vendus en ligne. Le pont fonctionne par adhésion, produit par produit : vous contrôlez quels articles sont publiés, avec la possibilité de remplacer le prix, le prix promotionnel et la catégorie boutique au moment de la publication.

Prérequis

• Larapen CMS v1.0.0 ou ultérieur
• PHP 8.3+
• MySQL 8.0+
• Add-on POS installé et actif
• Add-on Boutique installé et actif

Installation

Étape 1 : Téléverser l’add-on

Dans le panneau d’administration, allez dans Admin → Extensions → Add-ons et cliquez sur le bouton Télécharger un add-on. Sélectionnez le fichier ZIP de l’add-on : le système le décompresse automatiquement et l’add-on apparaît dans la liste des add-ons installés.

Étape 2 : Activer l’add-on

Repérez POS ↔ Shop Bridge dans la liste et cliquez sur Activer. Ses migrations, ses seeders (le cas échéant) et ses permissions sont mis en place automatiquement.

Étape 3 : Configurer

Naviguez vers Admin → Pont POS ↔ Boutique pour configurer les produits partagés, la synchronisation des stocks et le report du catalogue entre le POS et la Boutique. Voir Configuration.

Code d’achat (clé de licence)

POS ↔ Shop Bridge est vendu comme un produit séparé, il possède donc son propre code d’achat (clé de licence) — distinct du code d’achat de l’application principale et de celui de chaque autre add-on. Il vous est demandé lorsque vous activez POS ↔ Shop Bridge dans Panneau d’administration → Add-ons.

Nos produits sont vendus sur trois plateformes. La façon dont vous recevez un code d’achat dépend de l’endroit où vous avez acheté le produit.

1. Boutique bedigit.com (achat sur le site)

• Dès que le statut de paiement de la commande devient Payée, une clé de licence est générée automatiquement pour chaque article sous licence de la commande (une clé par unité achetée — acheter 3 unités donne 3 clés distinctes).
• Elle est envoyée par e-mail à l’adresse utilisée pour la commande, soit dans un e-mail de licence dédié, soit dans l’e-mail de confirmation de commande. Vérifiez votre boîte de réception et votre dossier spam / courrier indésirable.
• La clé reste disponible dans votre compte sous Mon compte → Mes licences. Les clés sont masquées dans la liste ; ouvrez la page de détail de la licence pour afficher et copier la clé complète, voir les domaines sur lesquels elle est activée, et désactiver un domaine pour libérer un emplacement d’activation.
• La facture correspondante se trouve sous Mon compte → Mes commandes.

2. Gumroad

• Un achat sur Gumroad produit deux e-mails distincts : le reçu Gumroad (envoyé par Gumroad, donnant accès aux fichiers) et un e-mail de clé de licence (envoyé par bedigit.com) qui contient votre code d’achat.
• L’e-mail de clé de licence est généré dès que Gumroad nous notifie la vente, il arrive donc normalement quelques secondes après le paiement. Ici aussi, vérifiez votre boîte de réception et votre dossier spam / courrier indésirable.
• Lorsque le produit Gumroad utilise la fonctionnalité de clés de licence propre à Gumroad, la même clé apparaît aussi dans votre reçu Gumroad et sous Bibliothèque → votre achat sur gumroad.com.
• Utilisez la même adresse e-mail sur bedigit.com que sur Gumroad : vos clés sont alors liées automatiquement à votre compte et listées sous Mon compte → Mes licences, même si vous vous inscrivez après l’achat. Vous pouvez aussi ajouter une clé Gumroad manuellement depuis Mon compte → Mes licences Gumroad.

3. Envato Market (CodeCanyon)

• Les codes d’achat Envato sont délivrés et fournis par Envato Market, jamais envoyés par e-mail par nous — il n’y a donc rien à chercher dans votre dossier de spam : vous récupérez le code depuis votre compte Envato.
• Connectez-vous à votre compte Envato / CodeCanyon, ouvrez la page Downloads, trouvez l’article et choisissez License certificate & purchase code dans le menu déroulant Download. Le code est inscrit dans ce certificat.
• Un code d’achat Envato ressemble à 12345678-90ab-cdef-1234-567890abcdef (8-4-4-4-12 caractères). Il ne change jamais, et le renouvellement du support de l’article n’en délivre pas de nouveau.
• Article officiel Envato : Where Is My Purchase Code?

Configuration

Tous les paramètres sont gérés dans Admin → Pont POS ↔ Boutique (stockés dans la table settings, groupe pos_shop_bridge).

Admin : Paramètres du pont

La page des paramètres (Pont POS ↔ Boutique → Paramètres du pont) comporte deux sections :

Paramètres généraux

• Activer le pont : interrupteur principal pour toute la synchronisation automatique. Le désactiver arrête la synchronisation des stocks et le report des commandes sans supprimer aucune donnée. Vous pouvez toujours publier et dépublier des produits manuellement lorsque le pont est désactivé.
• Entrepôt en ligne : sélectionnez l’entrepôt POS qui représente votre stock en ligne. Seules les variations de quantité dans cet entrepôt sont poussées vers les produits boutique liés. Il s’agit généralement d’un entrepôt nommé “En ligne” ou “Boutique web”.
• Publication automatique des nouveaux produits POS : lorsqu’il est activé, l’enregistrement d’un nouveau produit POS crée automatiquement un produit boutique en brouillon. Une correspondance de catégorie doit exister pour la catégorie POS du produit, sinon la publication automatique est ignorée silencieusement.

Correspondance des catégories

Voir Correspondance des catégories ci-dessous.

Admin : Correspondance des catégories

Le tableau de correspondance des catégories associe chaque catégorie de produit POS à une catégorie boutique. Cette correspondance est utilisée lors de la publication d’un produit POS : le pont consulte la catégorie POS et place le produit boutique résultant dans la catégorie boutique correspondante.

Ajouter une correspondance

1. En bas de la page Paramètres du pont, localisez la section Correspondance des catégories.
2. Sélectionnez une catégorie POS et une catégorie boutique dans les listes déroulantes.
3. Cliquez sur Ajouter une correspondance.

Supprimer une correspondance

Cliquez sur l’icône de suppression à côté de n’importe quelle ligne du tableau de correspondance. La suppression d’une correspondance n’affecte pas les produits déjà publiés ; elle n’affecte que les futures opérations de publication.

Correspondance et remplacements à la publication

Lors de la publication d’un produit POS, vous pouvez indiquer manuellement une catégorie boutique de remplacement dans le panneau de publication. Cela remplace la correspondance de catégorie pour ce seul produit sans modifier le tableau de correspondance.

Admin : Publication des produits

La publication rend un produit POS disponible en tant que produit boutique sur la vitrine.

Comment publier

1. Allez dans POS → Produits et ouvrez n’importe quel produit pour le modifier.
2. Dans la barre latérale, localisez le panneau Publier dans la boutique injecté par le pont.
3. Remplacez éventuellement la catégorie boutique, le prix, le prix promo et le statut (Brouillon ou Publié).
4. Cliquez sur Publier.

Le pont va :

• Créer un nouveau produit boutique (ou mettre à jour le produit lié existant).
• Copier le nom, le slug et la description du produit depuis le POS (dans toutes les langues traduisibles).
• Définir la quantité en stock sur le stock actuel de l’entrepôt en ligne.
• Copier l’image principale du POS vers le produit boutique (configurable).

Champs du panneau de publication

Republication

Cliquer sur Publier sur un produit déjà lié met à jour le produit boutique existant. La quantité en stock, le nom et la description sont rafraîchis. Tous les remplacements fournis dans le panneau sont appliqués à nouveau.

Dépublication

Cliquez sur Dépublier dans le panneau de publication pour passer le statut du produit boutique lié à Brouillon. La ligne du produit boutique est conservée en base de données ; elle n’est pas supprimée. La republication le rendra à nouveau visible.

Badge du produit boutique

Sur la page de liste des produits de la boutique, les produits synchronisés depuis le POS affichent un badge “Synchronisé depuis le POS”. Cliquer sur le badge ou sur la ligne du produit vous amène à la page de modification standard du produit boutique.

Lien de vente POS sur les commandes boutique

Sur la page de détail d’une commande boutique, si la commande dispose d’un enregistrement de vente POS reporté, un lien “Voir la vente POS” est affiché, conduisant l’administrateur directement à la vente POS correspondante.

Automatisation : Synchronisation des stocks

Le stock est synchronisé automatiquement chaque fois que la quantité d’un produit dans l’entrepôt en ligne change.

Fonctionnement

1. Un mouvement de stock est enregistré dans le POS (vente, achat, ajustement, transfert).
2. La ligne warehouse_products du POS pour l’entrepôt en ligne est mise à jour.
3. Le WarehouseProductStockObserver détecte le changement.
4. Le pont lit la nouvelle quantité et l’écrit dans shop_products.stock_quantity en utilisant withoutEvents pour éviter de déclencher des observateurs secondaires.

Quand la synchronisation ne s’exécute pas

• Le pont est désactivé (pos_shop_bridge_enabled est sur off).
• Aucun entrepôt en ligne n’a été configuré.
• L’entrepôt modifié n’est pas l’entrepôt en ligne configuré.
• Le produit boutique n’a pas stock_source = 'pos' (c’est-à-dire qu’il n’a pas été publié via le pont).

Automatisation : Report des commandes

Lorsqu’une commande boutique est payée, le pont crée un enregistrement correspondant dans l’historique des ventes POS. Cela permet aux responsables de voir tout le chiffre d’affaires — web et comptoir — dans une vue unique.

Déclencheur du report

L’OrderBridgeObserver surveille les changements de shop_orders.payment_status. Lorsqu’il passe à paid, le pont appelle createPosSaleFromShopOrder().

Ce qui est créé

• Une ligne pos_sales avec channel = 'web' et les totaux financiers de la commande boutique (sous-total, remise, taxe, total).
• Une ligne pos_sale_items pour chaque article de commande dont le produit boutique est lié à un produit POS. Les articles sans lien POS sont ignorés.
• Une ligne pos_sale_payments correspondant au mode de paiement de la boutique.
• Des enregistrements de mouvements de stock via le MovementService du POS.

Format du numéro de vente

Le numéro de la vente POS reportée est préfixé par WEB- suivi du numéro de la commande boutique (par exemple WEB-ORD-20260419-00000001). Le préfixe est configurable dans config/bridge.php.

Correspondance des modes de paiement

Idempotence

Si une vente POS existe déjà pour une commande boutique donnée, l’appel à createPosSaleFromShopOrder() renvoie l’enregistrement existant sans créer de doublon. Cela protège contre un double report accidentel si le statut de paiement est basculé plus d’une fois.

Annulation de vente

Lorsqu’une commande boutique est annulée ou que son statut de paiement passe à remboursé, le pont appelle reversePosSaleForShopOrder(), qui annule la vente POS liée via la méthode SaleService::void() du POS. Cela rétablit les mouvements de stock dans le journal des mouvements POS.

Automatisation : Cycle de vie des produits POS

Le PosProductBridgeObserver maintient le statut du produit boutique synchronisé avec le cycle de vie du produit POS.

Mise à jour

Méthode 1 : Téléversement via le panneau d’administration (recommandée)

1. Téléchargez le dernier fichier .zip de cet add-on.
2. Allez dans Panneau d’administration → Add-ons et cliquez sur le bouton Téléverser.
3. Sélectionnez ou glissez le fichier .zip dans la zone de téléversement.
4. Une invite de confirmation affichera les numéros de version actuelle et nouvelle. Cliquez sur Remplacer pour continuer.
5. Allez dans Panneau d’administration → Mise à jour du système (/admin/update) pour appliquer les migrations de base de données en attente.

Méthode 2 : Remplacement manuel des fichiers

Étape 1 : Remplacer les fichiers

Remplacez le répertoire de l’add-on par la nouvelle version.

Étape 2 : Exécuter les migrations

php artisan migrate

Étape 3 : Vider les caches

php artisan optimize:clear

Désinstallation

Éteindre un add-on sans rien perdre, c’est le désactiver : allez dans Panneau d’administration → Add-ons, trouvez POS ↔ Shop Bridge et cliquez sur Désactiver.

• Ses routes, ses vues, ses entrées de menu d’administration et ses permissions cessent d’être enregistrées, et ses pages publiques ne répondent plus.
• Ses tables de base de données et toutes les données qu’elles contiennent sont conservées, et ses fichiers restent dans extensions/addons/pos-shop-bridge/. Rien n’est supprimé.
• Le code d’achat enregistré lors de l’activation est conservé lui aussi : réactiver l’add-on ne le redemande pas.
• La désactivation est refusée tant qu’un autre add-on actif dépend de celui-ci : désactivez d’abord cet add-on.

Cliquez sur Activer sur la même carte pour le rallumer. Les migrations en attente sont rejouées, les assets republiés, et l’add-on reprend exactement là où il s’était arrêté.

Suppression

La suppression est définitive et détruit les données de l’add-on. Le bouton Supprimer n’apparaît que sur un add-on désactivé : la suppression se fait donc toujours en deux temps :

1. Désactivez POS ↔ Shop Bridge (voir Désinstallation).
2. Cliquez sur Supprimer sur sa carte et confirmez la demande.

Le panneau d’administration, en une seule passe :

• exécute le hook de désinstallation de l’add-on, s’il en fournit un, tant que son code est encore sur le disque ;
• révoque les permissions déclarées dans son addon.json ;
• annule ses migrations — ce qui supprime ses tables de base de données et toutes les lignes qu’elles contiennent — et purge ses entrées de la table migrations, afin qu’une réinstallation ultérieure reparte de zéro ;
• supprime ses assets publiés : public/addons/pos-shop-bridge/, public/vendor/pos-shop-bridge/ et storage/app/public/addons/pos-shop-bridge/ ;
• supprime le dossier de l’add-on extensions/addons/pos-shop-bridge/ ;
• supprime sa ligne dans la table addons (le code d’achat enregistré disparaît avec elle) et vide le cache de l’application.

La suppression est refusée, avec un message explicatif et avant toute destruction, lorsque l’add-on est encore actif, lorsqu’un autre add-on actif en dépend, ou lorsque l’utilisateur du serveur web (PHP) ne peut pas supprimer extensions/addons/pos-shop-bridge/. Dans ce dernier cas, donnez à cet utilisateur le droit d’écriture sur le dossier et sur son parent, puis réessayez.

Supprimer le dossier en FTP ou en SSH n’est pas équivalent : les tables de l’add-on, ses entrées dans la table migrations et sa ligne addons restent en place, et sa carte reste dans la liste. Utilisez plutôt Supprimer dans le panneau d’administration.

Dépannage

Le pont n’a aucun effet après l’activation

• Vérifiez que les add-ons POS et Boutique sont tous les deux actifs dans Admin → Add-ons.
• Vérifiez que pos_shop_bridge_enabled est activé (on) dans les Paramètres du pont.
• Assurez-vous que l’entrepôt en ligne a été sélectionné.

Échec de la publication : “Correspondance de catégorie manquante”

• Le produit POS a une catégorie, mais aucune correspondance n’existe pour elle dans le tableau de correspondance des catégories des Paramètres du pont.
• Ajoutez une correspondance pour cette catégorie POS, ou indiquez une catégorie boutique de remplacement dans le panneau de publication lors de la publication du produit.

Le stock ne se synchronise pas avec la boutique

• Vérifiez que pos_shop_bridge_enabled est sur on.
• Vérifiez que le bon entrepôt est défini comme entrepôt en ligne. Les changements de stock dans les autres entrepôts sont ignorés.
• Vérifiez que le produit boutique a stock_source = 'pos'. Les produits non publiés via le pont ont stock_source = 'manual' et ne sont pas synchronisés.

Une commande boutique n’apparaît pas dans l’historique des ventes POS

• Le pont ne crée une vente POS que lorsque le payment_status de la commande boutique passe à paid. Vérifiez que la commande a été payée.
• Vérifiez que la commande contient au moins un article dont le produit boutique est lié à un produit POS (pos_product_id n’est pas null).
• Vérifiez que l’entrepôt en ligne est configuré. Sans lui, le pont journalise un avertissement et saute le report.
• Vérifiez le journal Laravel à la recherche de messages d’avertissement [pos-shop-bridge].

La vente POS reportée affiche 0 $ pour les articles issus d’un produit non lié

Seuls les articles de commande dont le produit boutique possède un lien pos_product_id sont inclus dans la vente reportée. Les articles correspondant à des produits publiés indépendamment (sans le pont) sont exclus des articles de la vente POS. Les totaux globaux de la commande (sous-total, taxe, total) sont tout de même reportés fidèlement depuis la commande boutique.

La publication automatique n’a pas créé de produit boutique pour un nouveau produit POS

• Vérifiez que pos_shop_bridge_auto_publish est activé.
• Vérifiez qu’une correspondance de catégorie existe pour la catégorie du nouveau produit POS. La publication automatique est ignorée silencieusement si aucune correspondance n’est trouvée.

La suppression réversible d’un produit POS n’a pas passé le produit boutique en brouillon

• L’observateur ne réagit qu’aux suppressions réversibles (archives). Une suppression définitive (force-delete) ne change pas le statut du produit boutique — le pos_product_id est mis à null par la contrainte de clé étrangère de la base de données.