Guide du module Boutique

Fonctionnalité e-commerce complète pour votre site Larapen. Vendez des produits physiques et numériques avec un panier d’achat complet, un tunnel de commande, un système de coupons, une gestion des commandes et une génération de flux marchands.

Cas d’utilisation

Boutique en ligne

Vendez des produits physiques avec suivi des stocks, calcul des frais de livraison et réductions par coupons. Les clients parcourent les catégories, ajoutent au panier, passent commande et suivent leurs commandes.

Vente de produits numériques

Vendez des fichiers téléchargeables (e-books, modèles, logiciels). Les produits numériques n’ont pas de frais de livraison, et les acheteurs reçoivent des liens de téléchargement à durée limitée après le paiement. Activez d’abord la fonctionnalité Produits numériques (Boutique → Paramètres → Produits numériques — désactivée par défaut) ; en la laissant désactivée, toute la boutique et le panneau d’administration restent en mode produits physiques.

Produits affiliés / externes

Listez des produits qui redirigent vers des détaillants externes. Les produits externes affichent un bouton “Acheter maintenant” qui renvoie vers la boutique externe au lieu du flux de panier interne. Un produit peut lister jusqu’à cinq boutiques (liens d’affiliation, chacun avec son propre nom de fournisseur) : avec un seul lien actif, le bouton y mène directement ; avec plusieurs, le client choisit d’abord une boutique.

Commerce multicanal

Utilisez le système de flux marchands pour diffuser votre catalogue produits sur Google Shopping, Facebook Commerce, Amazon, TikTok Shop et d’autres plateformes.

Prérequis

• Larapen CMS v1.0.0 ou ultérieur
• PHP 8.3+
• MySQL 8.0+
• Au moins un add-on de passerelle de paiement (ex. Stripe) pour traiter les paiements

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éverser 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 Boutique 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 → Boutique → Paramètres pour configurer la devise, la taxe, la livraison et les options de commande. Voir Configuration.

Code d’achat (clé de licence)

Boutique 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 Boutique 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 → Boutique → Paramètres (stockés dans la table settings, groupe shop). Les valeurs par défaut sont définies dans config/shop.php.

Général

Taxes

Livraison

Produits numériques

Stock & Notifications

Variables d’environnement

Variables optionnelles pour les produits versionnés adossés à git (toutes ont des valeurs par défaut raisonnables) :

Admin : Paramètres

La page des paramètres (Boutique → Paramètres) est organisée en sections :

• Général : Préfixe de commande, produits par page, position de la barre latérale, colonnes de grille, mode d’affichage par défaut, titre/sous-titre/libellé du fil d’Ariane de la page boutique.
• Taxes : Activer/désactiver les taxes, pourcentage du taux de taxe, prix TTC.
• Livraison : Activer/désactiver la livraison, tarif forfaitaire, seuil de livraison gratuite.
• Commande : Commande en tant qu’invité, numéro de téléphone obligatoire, adresse de livraison obligatoire.
• Produits numériques : Un interrupteur principal Activer les produits numériques dans l’en-tête de la carte (désactivé par défaut) active/désactive toute la fonctionnalité — désactivé, ses champs sont masqués ici et toutes les cartes, boutons et entrées de menu propres au numérique sont masqués dans tout le panneau d’administration (et la boutique abandonne la mise en page marketplace). Activé : Type de catalogue, téléchargements maximum par achat, expiration du lien de téléchargement, fenêtre d’accès aux mises à jour et options de renouvellement payant.
• Stock : Seuil de stock faible.
• Notifications : Notification admin pour nouvelle commande, confirmation de commande client.

Admin : Produits

La page Produits (Boutique → Produits) gère votre catalogue de produits.

Liste des produits

Un tableau paginé affichant :

• Image mise en avant (miniature)
• Nom et SKU
• Catégorie
• Prix (avec prix promotionnel le cas échéant)
• Stock quantité
• Statut (brouillon / publié / archivé)
• Type de commande (interne / externe)

Actions par élément : Modifier, Supprimer. Suppression en masse avec sélection par cases à cocher.

Création & Modification de produits

Le formulaire produit comprend les sections suivantes :

Lors de la modification d’un produit publié, un bouton Voir (en haut à droite, à côté de Retour) ouvre sa page publique dans un nouvel onglet. Il est masqué pour les brouillons et les produits programmés dans le futur, qui n’ont pas encore de page publique.

Informations de base

• Nom (traduisible) : titre du produit affiché dans le catalogue.
• Slug (traduisible) : identifiant URL. Généré automatiquement à partir du nom si vide.
• Description courte (traduisible) : résumé affiché sur les pages de liste.
• Description (traduisible) : description complète du produit avec éditeur WYSIWYG.
• Catégorie : sélection parmi les catégories de produits.
• SKU : identifiant d’unité de gestion des stocks (unique parmi les produits de la boutique). Pour un produit numérique vendu avec une clé de licence, c’est aussi l’identifiant de produit que les applications clientes envoient à l’API de licences — voir Produits de licence.
• Statut : Brouillon, Publié ou Archivé.
• Publié le : planifier la date de publication.

Tarification

• Prix : prix normal du produit.
• Prix promotionnel : prix réduit optionnel (doit être inférieur au prix normal pour prendre effet).
• Devise : définie depuis le paramètre de devise par défaut du site.

Inventaire

• Gérer le stock : activer/désactiver le suivi des stocks. Lorsque désactivé, le produit est toujours “en stock”.
• Quantité en stock : nombre d’unités disponibles.

Type de commande

• Interne : flux standard d’ajout au panier et de commande.
• Externe : le produit renvoie vers une ou plusieurs boutiques externes (liens d’affiliation). Ne peut pas être ajouté au panier. Le suivi des stocks est désactivé.

Images

• Image mise en avant : image principale du produit (utilise la médiathèque).
• Images de galerie : images supplémentaires du produit affichées sur la page de détail.

SEO

• Méta titre (traduisible)
• Méta description (traduisible)

Données de flux

• Marque, GTIN, MPN, État, Poids : utilisés dans la génération de flux marchands et les données structurées schema.org.
• Labels personnalisés (0–4) : pour la segmentation des flux marchands.

Variantes de produits

Les produits peuvent avoir plusieurs variantes, chacune avec ses propres :

• Nom (ex. “Grand, Rouge”)
• SKU
• Prix (remplace le prix du produit si défini)
• Quantité en stock
• Attributs (JSON : paires clé-valeur pour taille, couleur, etc.)
• Actif bascule

Les variantes sont synchronisées à l’enregistrement du produit. Les variantes supprimées sont automatiquement effacées.

Produits numériques

Lorsque Est numérique est activé :

• Un champ d’upload Fichier numérique apparaît. Les fichiers sont stockés sur le disque configuré (par défaut : local) sous le chemin digital-products.
• La livraison est automatiquement exclue pour les commandes entièrement numériques.
• Après le paiement, les éléments de commande reçoivent un lien de téléchargement à durée limitée.
• Les tentatives de téléchargement sont suivies via download_count et appliquées contre shop_digital_max_downloads.
• Les liens de téléchargement expirent après shop_digital_expiry_days.

Détails techniques

Les produits numériques peuvent annoncer leurs technologies & compatibilités à la manière de CodeCanyon dans une carte Détails techniques. Elle apparaît sur le formulaire produit uniquement lorsque Est numérique est activé, et sur la boutique elle est affichée comme une carte dédiée dans la barre latérale droite de la page produit — seuls les champs que vous renseignez sont affichés.

• Type de fichier numérique : la nature de ce produit — Code / Script, Graphisme / Template, Image / Photo, Vidéo, Audio / Musique, Document ou Autre. Le type détermine les champs affichés : par ex. Code expose Langages, Frameworks et Navigateurs compatibles, tandis que Graphisme et Image affichent plutôt Résolution. Il est aussi affiché comme ligne Type dans la carte Détails du produit de la boutique.
• Listes de tags groupées : chaque champ est un sélecteur de tags — Langages, Frameworks et bibliothèques, Navigateurs compatibles, Version logicielle, Résolution et Fichiers inclus. Choisissez une valeur existante parmi les suggestions ou saisissez-en une nouvelle et appuyez sur Entrée.
• Suggestions automatiques : le sélecteur est pré-rempli avec les valeurs courantes et y fusionne toutes les valeurs déjà utilisées par vos autres produits, afin que votre catalogue reste cohérent tout en vous laissant ajouter n’importe quelle nouveauté à la volée.

Produits avec mises à jour

Activez Produit avec mises à jour (affiché au-dessus du champ Fichier numérique) pour les produits livrés avec des mises à jour gratuites — logiciels, thèmes, templates et similaires. Lorsque cette option est activée :

• La limite de téléchargements par commande est levée afin que les acheteurs puissent toujours retélécharger le dernier fichier.
• Deux champs supplémentaires apparaissent : Accès aux mises à jour (fenêtre, en mois, pendant laquelle les acheteurs continuent de recevoir les nouvelles versions ; vide utilise shop_digital_update_access_months) et Prix du renouvellement de l’accès aux mises à jour (pourcentage du prix du produit pour prolonger la fenêtre ; vide utilise shop_update_access_renewal_percent).
• Sur leur page de commande, les acheteurs voient l’état de leur accès et — à l’approche ou après son expiration — peuvent payer pour prolonger l’accès aux mises à jour.

Liaison des licences (avec l’add-on Licences). Lorsque shop_update_access_syncs_license est activé, la clé de licence émise pour un achat avec mises à jour reçoit une date Expire le correspondant à la fenêtre d’accès aux mises à jour, et prolonger l’accès la repousse. Une clé dépassant sa date Expire le reste valide pour les versions publiées à cette date ou avant — seules les versions plus récentes exigent un renouvellement. L’API de vérification accepte un paramètre version optionnel pour ce contrôle.

Produits de licence (add-on Licences)

Lorsque l’add-on Licences est actif, un produit numérique peut être rattaché à un produit de licence afin que chaque commande payée émette une clé de licence pour celui-ci. Le bouton apparaît sous la forme d’une icône de clé dans la liste des produits et comme carte Produit de licence en bas de la page de modification du produit (produits numériques uniquement, et seulement lorsque Activer les produits numériques est actif). Il indique Créer un produit de licence ou Mettre à jour le produit de licence et nécessite la permission licenses.products.create ou licenses.products.edit.

• Comment le lien est stocké. Le produit de la boutique est enregistré comme la fiche marketplace shop du produit de licence (une ligne dans la table licenses_product_marketplace de l’add-on Licences : listing_id = le produit de la boutique, external_id = son SKU). L’add-on Boutique ne stocke lui-même rien sur ce lien : l’ancienne colonne shop_products.license_product_id a été supprimée par Licences 1.0.13, qui a copié chaque lien existant dans cette table.
• Créer crée un nouveau produit de licence à partir du produit de la boutique (nom, description courte, slug unique basé sur le slug du produit) avec le même SKU, puis enregistre la fiche. Mettre à jour rafraîchit le nom et la description du produit de licence lié et répare la fiche.
• Un seul SKU des deux côtés. Le SKU du produit de la boutique et celui de son produit de licence restent identiques : lorsque vous enregistrez l’un des deux produits et qu’un côté n’a pas de SKU, il est rempli depuis l’autre côté. Deux SKU différents ne sont jamais écrasés silencieusement.
• Le bouton refuse de s’exécuter (toast d’erreur) lorsque :
  • le produit de la boutique et son produit de licence portent des SKU différents — alignez l’un des deux, puis cliquez à nouveau ;
  • le SKU du produit de la boutique est déjà utilisé par un autre produit de licence ;
  • le produit n’est pas numérique.
• Clés de licence pour les commandes. Lorsqu’une commande est payée (ou acceptée hors ligne), une clé est émise pour chaque ligne de commande dont le produit de la boutique est listé comme produit de licence, à condition que la marketplace Boutique soit activée dans les paramètres de Licences (licenses_shop_marketplace_enabled). Les produits sans fiche n’émettent aucune clé.

Mises à jour versionnées (Git)

Les produits avec mises à jour peuvent être publiés directement depuis un dépôt git au lieu d’un téléversement manuel de fichier. Activez Mises à jour versionnées (affiché lorsque Produit avec mises à jour est actif) pour révéler le panneau git.

• Fournisseur : GitHub, GitLab, Bitbucket ou un serveur git privé / personnalisé.
• URL du dépôt et Branche optionnelle.
• Authentification : un jeton (jeton d’accès personnel / mot de passe d’application, avec un identifiant optionnel) ou une clé SSH (collez la clé privée ; ajoutez la clé de déploiement correspondante à votre dépôt). Les secrets sont stockés chiffrés et ne sont plus jamais affichés.
• Tester la connexion vérifie que le dépôt est joignable avec les identifiants actuels (fonctionne avant l’enregistrement).
• Créer une archive génère une version téléchargeable à partir d’un tag annoté choisi (ou du dernier tag annoté). Le sélecteur de tags est recherchable et charge les tags du dépôt à la demande. Si le dépôt n’a aucun tag annoté, le dernier commit est utilisé à la place.

Chaque tag annoté devient une version portant sa véritable date de tag. La version la plus récente est le fichier que les acheteurs téléchargent. La liste Versions affiche les dernières (avec un total), chacune avec un bouton de suppression (icône corbeille) qui supprime cette version et son fichier — supprimer la version actuelle vide le fichier du produit jusqu’à ce que vous publiiez une nouvelle version.

Les archives de version sont nommées <project>-v<version>.zip (par ex. larapen-v1.0.8.zip), le nom de projet étant repris de l’URL du dépôt.

Dans la liste des produits, les produits avec mises à jour adossés à git affichent un bouton Nouvelle version (icône tag) qui publie une nouvelle version depuis le dernier tag annoté, en remplaçant le fichier précédent.

Journaux de versions

Chaque version porte un journal des modifications. Lorsqu’une version est générée depuis un tag, le journal est créé automatiquement à partir des messages de commit entre ce tag et la version précédente (avec repli sur le message du tag lui-même). Les versions sont créées sans envoyer d’e-mail à personne, afin que vous puissiez d’abord relire et modifier les notes.

• Gérez-les sous Boutique → Journaux de versions (l’entrée de menu n’apparaît que lorsque la fonctionnalité Produits numériques est activée) : une liste recherchable et filtrable de toutes les versions, tous produits confondus. Ajoutez / modifiez / supprimez des entrées, et enregistrez manuellement des versions passées (avec leur propre version, date et notes) antérieures à l’intégration git.
• Modifiez le journal de n’importe quelle version depuis cet écran (ou depuis la liste des versions du produit) avant de le publier.
• Envoyer la notification : un bouton dédié envoie par e-mail le journal de cette version aux acheteurs abonnés. Il n’apparaît que lorsque la version possède un fichier téléchargeable (ainsi les notifications renvoient toujours vers quelque chose à télécharger).
• Page publique : chaque produit numérique avec mises à jour possède un journal des versions public à l’adresse /shop/product/{slug}/changelog, relié par un bouton Journal des versions dans la carte Détails du produit de la page produit.

Disponibilité & fichiers manquants

Un produit numérique ne peut être acheté que lorsque son fichier téléchargeable existe réellement (téléversé, ou une version a été générée). Lorsque le fichier est manquant — pas encore téléversé, aucune version générée, ou fichier supprimé — la boutique protège automatiquement les acheteurs :

• Les listes de la boutique affichent un bouton Indisponible désactivé, et la page produit affiche un avis de “temporairement indisponible” au lieu de Acheter / Ajouter au panier.
• Ajouter au panier, Acheter maintenant et Commander sont bloqués côté serveur avec un message clair, de sorte qu’un article indisponible ne peut jamais être commandé.
• Sur Mes commandes, si le fichier d’un article acheté est temporairement indisponible, l’acheteur voit un avis explicite, le bouton de téléchargement est masqué et Prolonger l’accès aux mises à jour est désactivé (afin qu’il ne paie pas l’accès à un fichier manquant).

Produits externes

Lorsque le Type de commande est défini sur Externe :

• Une carte Liens externes apparaît : ajoutez jusqu’à 5 boutiques, chacune avec un nom de fournisseur (affilié), une URL, une cible de lien (nouvel/même onglet) et un interrupteur d’activation. Les liens peuvent être supprimés ou temporairement désactivés ; au moins un lien actif est requis.
• Le produit ne peut pas être ajouté au panier.
• Le front-end affiche un bouton “Acheter maintenant”. Avec un seul lien actif, il mène directement à la boutique ; avec deux ou plus, il ouvre une boîte de dialogue “Choisissez où acheter” listant les boutiques (le nom du fournisseur, ou le domaine du lien lorsque aucun nom n’est défini).
• Les plans de service vendus via une commande externe disposent de la même carte Liens externes sur leur page de création/modification, et du même sélecteur de boutique dans la boutique.
• La gestion des stocks, le fichier numérique et les champs d’inventaire sont automatiquement désactivés.

Admin : Catégories

Les catégories de produits utilisent la table unifiée categories avec categorizable_type = 'product'. Les catégories sont gérées via Boutique → Catégories.

• Nom (traduisible) et Slug (traduisible, généré automatiquement).
• Description (traduisible) et Méta titre / Méta description (traduisible).
• Catégorie parente : supporte l’imbrication hiérarchique.
• Position : valeur d’ordonnancement.
• Est actif bascule.
• Image mise en avant via la médiathèque.
• Catégorie produit Google : données de flux pour la génération de flux marchands (via shop_category_feed_data).

Admin : Commandes

La page Commandes (Boutique → Commandes) fournit une liste de toutes les commandes clients.

Liste des commandes

Un tableau paginé et filtrable affichant :

• Numéro de commande (format : ORD-YYYYMMDD-00000001)
• Nom & e-mail du client
• Nombre d’articles
• Total (formaté avec devise)
• Statut badge (en attente, en traitement, terminée, annulée, remboursée)
• Statut de paiement badge (en attente, payé, échoué, remboursé)
• Date

Actions par élément : Voir, Supprimer.

Détail de la commande

La page de détail de la commande (Boutique → Commandes → {commande}) affiche :

• Carte résumé de la commande : numéro de commande, date, statut, statut de paiement, méthode de paiement.
• Informations client : nom, e-mail, téléphone, adresse de facturation, adresse de livraison.
• Tableau des articles : nom du produit, SKU, prix, quantité, total, badge numérique, informations de téléchargement.
• Résumé financier : sous-total, réduction, taxe, livraison, total.
• Code coupon (si appliqué).
• Liste des transactions : passerelle, ID de transaction, montant, statut, type (paiement / remboursement).
• Notes du client.

Mises à jour de statut

L’administrateur peut mettre à jour le statut de la commande et le statut de paiement via des sélecteurs déroulants :

• Mettre à jour le statut : envoie PATCH admin/shop/orders/{id}/status
• Mettre à jour le statut de paiement : envoie PATCH admin/shop/orders/{id}/payment-status

Statuts de commande

Statuts de paiement

Admin : Coupons

La page Coupons (Boutique → Coupons) gère les codes de réduction.

Champs du coupon

Règles de validation

Un coupon est considéré comme valide lorsque toutes les conditions suivantes sont remplies :

1. is_active est true.
2. La date actuelle est après starts_at (ou starts_at est null).
3. La date actuelle est avant expires_at (ou expires_at est null).
4. used_count est inférieur à max_uses (ou max_uses est null).

Un coupon est applicable à une commande lorsqu’il est valide ET que le sous-total de la commande atteint min_order_amount.

Le calcul de la réduction ne dépasse jamais le sous-total de la commande.

Admin : Avis & notes

Les clients notent les produits de 1 à 5 étoiles et laissent un titre et un commentaire depuis la page produit. Les avis sont modérés sur Boutique → Avis (approuver, rejeter, répondre, supprimer, suppression en masse). Les acheteurs du produit obtiennent un badge Achat vérifié ; la note moyenne et le nombre d’avis sont dénormalisés sur le produit (rating_avg, rating_count) et affichés sur les fiches produit, la page produit et dans le JSON-LD Product (aggregateRating + review) pour les résultats enrichis avec étoiles. Les listes peuvent être triées par Les mieux notés.

Paramètres (Boutique → Paramètres → Avis & notes)

Admin : Attributs & filtres à facettes

Boutique → Attributs définit les attributs de produit (Couleur, Taille, Matière…) et leurs valeurs. Les attributs de type Pastilles de couleur portent une couleur hexadécimale par valeur. Les produits sont associés à des valeurs depuis la carte Attributs du formulaire produit. Les attributs filtrables apparaissent dans la barre latérale de la boutique comme facettes avec le nombre de produits en direct (chaque facette est comptée sur le jeu de résultats courant, sa propre sélection retirée), à côté des filtres de fourchette de prix, de note client et de disponibilité. Les filtres actifs sont affichés comme puces supprimables au-dessus de la grille.

Paramètres d’URL des filtres

Le panneau de filtres et chaque type de facette peuvent être désactivés dans Boutique → Paramètres → Filtres du catalogue (shop_filters_enabled, shop_filter_price_enabled, shop_filter_stock_enabled, shop_filter_rating_enabled).

Admin : Règles de taxe

Deux modes de taxe sont disponibles (Boutique → Paramètres → Taxes, shop_tax_mode) : Taux unique conserve le taux unique applicable à toute la boutique des versions précédentes, et Règles de taxe applique des règles par localisation gérées sur Boutique → Règles de taxe.

Classes et taux de taxe

Une classe de taxe regroupe les produits taxés de la même manière (Standard, Réduit, Zéro…) ; une classe est celle par défaut et les produits peuvent en choisir une autre depuis le formulaire produit. Un taux de taxe appartient à une classe (ou à toutes les classes) et correspond à un pays, éventuellement à un état/région et à un code postal (exact, préfixe 75* ou plage 1000-1999). Les taux sont appliqués par ordre de priorité ; un taux composé est calculé au-dessus des taxes de priorité inférieure. Les taux marqués Taxe la livraison s’appliquent aussi au montant de la livraison. Les prix TTC sont respectés : le montant net est déduit d’abord et les mêmes fractions s’appliquent.

Résolution de la localisation

La localisation applicable est déterminée par shop_tax_basis : l’adresse de livraison du client, son adresse de facturation ou la localisation de la boutique (shop_tax_store_country / état / code postal). Avant qu’une adresse ne soit saisie, l’estimation lors de la commande utilise, dans l’ordre : la localisation mémorisée d’une estimation précédente, l’adresse par défaut enregistrée du client, le pays GeoIP du visiteur et enfin la localisation de la boutique. Changer le pays, l’état ou le code postal lors de la commande recalcule les totaux en direct (POST shop/checkout/estimate).

TVA UE (B2B)

Avec shop_tax_vat_enabled, la page de commande affiche un champ numéro de TVA. Les numéros sont validés auprès du service VIES de la Commission européenne (résultats mis en cache pendant un jour). Lorsque shop_tax_reverse_charge_enabled est activé, un numéro valide d’un pays de l’UE autre que celui de la boutique rend la commande exonérée de taxe (autoliquidation) ; shop_tax_vat_require_valid bloque en outre la commande lorsque VIES rejette le numéro. Le numéro de TVA, le détail par taux et le motif d’exonération sont enregistrés sur la commande (vat_number, tax_breakdown, tax_exempt_reason) et chaque ligne de commande porte son tax_amount.

Front-end : Liste d’envies & Mettre de côté

Un bouton cœur sur les fiches produit et les pages produit ajoute le produit à la liste d’envies du visiteur. Les clients connectés possèdent une seule liste ; les visiteurs obtiennent une liste de session qui est fusionnée dans leur compte à la connexion. La page Ma liste d’envies (/shop/wishlist, également dans le menu du compte) permet aux clients de déplacer des articles vers le panier, de les retirer et de partager la liste via un lien privé (/shop/wishlist/{token}) qui peut être désactivé à tout moment. Les listes de visiteurs restées inchangées pendant shop.wishlist.guest_retention_days (90 jours) sont purgées chaque semaine par shop:prune-guest-wishlists.

Dans le panier, Mettre de côté met une ligne en attente : elle quitte les totaux et la commande, mais reste listée sous Mis de côté jusqu’à ce qu’elle soit remise (au prix actuel) ou retirée. Les lignes mises de côté survivent à une commande finalisée.

Interrupteurs : shop_wishlist_enabled, shop_wishlist_guest_enabled, shop_save_for_later_enabled (Boutique → Paramètres → Liste d’envies).

Admin : Flux marchands

La page Flux marchands (Boutique → Flux marchands) gère la génération de flux de produits pour les plateformes publicitaires e-commerce.

Plateformes supportées

Gestion par plateforme

Pour chaque plateforme, l’administrateur peut :

• Activer/Désactiver : basculer la génération de flux.
• Configurer les paramètres : ID marchand, clés API (chiffrées), devise, durée du cache, inclure les variantes, inclure les produits en rupture de stock.
• Personnaliser les mappages de champs : mapper les champs spécifiques à la plateforme aux propriétés des données produit. Remplacer les mappages par défaut, définir des valeurs par défaut et appliquer des transformations.
• Générer le flux : déclencher manuellement la génération du flux.
• Prévisualiser le flux : afficher un échantillon de la sortie générée.
• Valider le flux : vérifier le flux pour détecter les erreurs structurelles.

Commande Artisan

Génère les flux pour toutes les plateformes activées. Peut être planifié via le planificateur de tâches de Laravel pour une régénération périodique automatique.

URLs des flux

Les flux générés sont accessibles à :

Par exemple : /feeds/products/google retourne le flux XML Google Merchant Center.

Front-end : Catalogue produits

Routes

Des variantes non localisées (sans {locale}) sont également enregistrées.

Fonctionnalités du catalogue

• Filtrage par catégorie via l’URL ou les liens de la barre latérale.
• Recherche dans le nom, la description et le SKU des produits.
• Trier par : plus récent, prix (croissant/décroissant), nom, popularité (nombre de vues).
• Filtre de fourchette de prix avec paramètres min/max.
• Vue grille / liste basculable.
• Pagination avec taille de page configurable.

Page de détail du produit

• Galerie d’images du produit avec image mise en avant.
• Affichage du prix avec badge promotionnel et pourcentage de réduction.
• Sélecteur de variante (si des variantes existent).
• Indicateur de disponibilité en stock.
• Bouton Ajouter au panier (ou lien “Acheter maintenant” pour les produits externes).
• Section produits similaires (même catégorie).
• Données structurées JSON-LD schema.org (via le composant <x-shop-json-ld>).

Les produits numériques utilisent une mise en page dédiée de type marketplace (galerie, carte détails du produit, lien vers le journal des versions, détails techniques) uniquement lorsque la fonctionnalité Produits numériques est activée. La fonctionnalité désactivée, chaque produit — même encore marqué comme numérique — utilise la mise en page physique standard.

Front-end : Panier d’achat

Routes

Comportement du panier

• Paniers invités : stockés en base de données, identifiés par un ID basé sur la session (clé de session shop_cart).
• Paniers authentifiés : stockés par user_id. Lorsqu’un utilisateur se connecte, son panier de session est automatiquement fusionné dans son panier utilisateur.
• Validation du stock : l’ajout d’articles vérifie le stock disponible. Si la quantité demandée dépasse le stock, une erreur est retournée.
• Quantité maximum : limite configurable par article (par défaut : 99).
• Les produits externes ne peuvent pas être ajoutés au panier ; une exception est levée avec un message traduisible.
• Le compteur du panier est partagé avec toutes les vues via un View Composer.

Totaux du panier

Le CartService calcule :

• Sous-total : somme de (prix × quantité) pour tous les articles.
• Réduction : réduction coupon (pourcentage ou fixe), plafonnée à max_discount.
• Taxe : calculée sur (sous-total - réduction). Supporte les prix TTC (extraction de la taxe intégrée).
• Livraison : tarif forfaitaire, supprimé pour les commandes entièrement numériques ou lorsque le sous-total atteint le seuil de livraison gratuite.
• Total : sous-total - réduction + taxe + livraison.

Front-end : Commande

Routes

Flux de commande

1. Validation du panier : redirige vers la page du panier si vide.
2. Vérification invité : si la commande en tant qu’invité est désactivée et que l’utilisateur n’est pas authentifié, redirige vers la connexion.
3. Affichage du formulaire : informations de facturation (nom, e-mail, téléphone), adresse de facturation, adresse de livraison, notes de commande, sélecteur de méthode de paiement.
4. Soumission du formulaire via la validation CheckoutRequest.
5. Création de la commande : la méthode OrderService::createFromCart() :
   • Crée l’enregistrement de la commande avec tous les totaux.
   • Crée les articles de la commande à partir des articles du panier.
   • Génère les liens de téléchargement pour les produits numériques.
   • Décrémente le stock pour les produits à stock géré.
   • Incrémente le compteur d’utilisation du coupon.
   • Envoie les notifications par e-mail à l’administrateur et au client.
6. Traitement du paiement : la commande implémente l’interface Payable, permettant au PaymentService principal de router vers la passerelle de paiement sélectionnée.
7. Page de succès : affiche la confirmation de commande avec le numéro et les détails de la commande.

Front-end : Mes commandes

Routes

Téléchargements numériques

Pour les produits numériques, le téléchargement est autorisé lorsque toutes les conditions sont remplies :

• L’article de la commande est marqué comme is_digital avec un download_link.
• La commande a été payée (payment_status = 'paid').
• Le lien de téléchargement n’a pas expiré (download_expires_at est dans le futur).
• Le nombre de téléchargements n’a pas atteint le maximum (shop_digital_max_downloads).

Chaque téléchargement réussi incrémente download_count.

Accès aux mises à jour & téléchargements versionnés

Pour les produits avec mises à jour, la page de commande affiche l’état de l’accès aux mises à jour de l’acheteur et, à l’approche ou après son expiration, un bouton Prolonger pour payer une nouvelle fenêtre.

Pour les produits adossés à git dont l’accès aux mises à jour a expiré, l’acheteur peut encore récupérer la version exacte que couvre sa licence (la version la plus récente datée au plus tard à la fin de son accès) :

• Il clique sur Obtenir la version… sur la page de commande. L’archive est (re)générée depuis son tag git en arrière-plan — la requête répond donc immédiatement.
• Lorsqu’elle est prête, l’acheteur reçoit par e-mail un lien de téléchargement privé à durée limitée qui indique sa date de validité (48 h par défaut, SHOP_GIT_VERSION_LINK_TTL_HOURS).
• Les liens expirés et les fichiers générés correspondants sont nettoyés automatiquement (shop:prune-version-downloads, quotidiennement).

Notifications de mise à jour

Les acheteurs d’un produit avec mises à jour sont abonnés par défaut aux notifications de nouvelles versions. Une case à cocher sur la page de commande leur permet de se désabonner. Lorsqu’une nouvelle version est publiée (et que l’administrateur choisit de notifier), chaque acheteur abonné reçoit un e-mail.

Front-end : Suivi de commande

Flux de paiement

1. Le client sélectionne une méthode de paiement sur la page de commande.
2. Le contrôleur de commande crée la commande via OrderService::createFromCart().
3. Le PaymentService route la commande vers la passerelle sélectionnée.
4. La passerelle traite le paiement (redirection vers une page externe, formulaire de carte, etc.).
5. En cas de succès, la passerelle appelle order->markAsPaid() qui définit le statut sur terminé et le statut de paiement sur payé, puis vide le panier.
6. En cas d’échec, la passerelle appelle order->markPaymentFailed().
7. Le client est redirigé vers l’URL de succès ou de retour à la commande.

Transactions

Les passerelles de paiement créent des enregistrements Transaction pour suivre les événements de paiement :

• Type : payment ou refund
• Statut : pending, completed ou failed
• Infos passerelle : nom de la passerelle, ID de transaction passerelle, montant, devise
• Métadonnées : champ JSON pour les données spécifiques à la passerelle

Mise à jour

Il existe deux façons de mettre à jour cet add-on : depuis le panneau d’administration (recommandé) ou en remplaçant manuellement les fichiers.

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

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 demande de confirmation affichera les numéros de version actuel et nouveau. 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

Les migrations en attente ne s’exécutent qu’une seule fois : la commande peut être relancée sans risque.

Étape 3 : Vider les caches

php artisan config:clear
php artisan route:clear
php artisan view:clear

Étape 4 : Reconstruire les assets

Désinstallation

Éteindre un add-on sans rien perdre, c’est le désactiver : allez dans Panneau d’administration → Add-ons, trouvez Shop 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/shop/. 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 Shop (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/shop/, public/vendor/shop/ et storage/app/public/addons/shop/ ;
• supprime le dossier de l’add-on extensions/addons/shop/ ;
• 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/shop/. 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

Les produits n’apparaissent pas dans le catalogue

• Vérifiez que le statut du produit est Publié (pas Brouillon ni Archivé).
• Vérifiez published_at : s’il est défini, il doit être dans le passé.
• Vérifiez que le produit a au moins un nom défini pour la langue actuelle.

L’ajout au panier échoue : “Stock insuffisant”

• Vérifiez que stock_quantity est supérieur à la quantité demandée.
• Si l’article est déjà dans le panier, la quantité combinée ne doit pas dépasser le stock disponible.
• Désactivez Gérer le stock sur le produit pour le considérer toujours comme en stock.

Impossible d’ajouter un produit externe au panier

C’est par conception. Les produits externes (checkout_type = 'external') redirigent vers une boutique externe. Ils ne peuvent pas être ajoutés au panier interne. Sur le front-end, un lien “Acheter maintenant” (ou un sélecteur de boutique lorsque le produit liste plusieurs boutiques) est affiché au lieu du bouton Ajouter au panier.

Le coupon ne s’applique pas

• Vérifiez que is_active du coupon est true.
• Vérifiez les dates starts_at et expires_at.
• Confirmez que le sous-total de la commande atteint min_order_amount.
• Vérifiez si used_count a atteint max_uses.

La commande échoue : aucune passerelle de paiement disponible

• Installez et activez au moins un add-on de passerelle de paiement (ex. Stripe).
• Le paiement à la livraison (COD) est disponible comme option intégrée lorsque la boutique est active.
• Vérifiez que la passerelle de paiement est correctement configurée dans ses paramètres.

Le téléchargement numérique retourne 403 ou “Téléchargement non disponible”

• Confirmez que le payment_status de la commande est paid.
• Vérifiez si le téléchargement a expiré (download_expires_at).
• Vérifiez si le nombre maximum de téléchargements a été atteint.
• Vérifiez que le fichier numérique existe sur le disque de stockage configuré au chemin enregistré.

“Créer / Mettre à jour le produit de licence” échoue

• SKU différents : le produit de la boutique et son produit de licence ont des SKU différents. Rendez-les identiques (sur le produit de la boutique ou dans Licences → Produits), puis cliquez à nouveau sur le bouton.
• SKU déjà utilisé : un autre produit de licence porte déjà ce SKU. Liez plutôt ce produit de licence, ou changez l’un des SKU.
• Le bouton n’existe que pour les produits numériques, avec l’add-on Licences actif et Activer les produits numériques activé.

Aucune clé de licence émise pour une commande payée

• Vérifiez que le produit possède un produit de licence (voir Produits de licence).
• Vérifiez que la marketplace Boutique est activée dans les paramètres de Licences (licenses_shop_marketplace_enabled).
• Les commandes de renouvellement de l’accès aux mises à jour n’émettent jamais de clé : elles prolongent seulement celle qui existe.

Le flux marchand retourne vide ou 404

• Vérifiez que la plateforme est activée dans Boutique → Flux marchands.
• Exécutez php artisan shop:generate-feeds pour régénérer les flux.
• Vérifiez que des produits publiés existent avec is_digital = false ou que include_out_of_stock est activé.
• Vérifiez l’URL du flux : /feeds/products/{platformKey} (ex. /feeds/products/google).

Le calcul des taxes semble incorrect

• Si vous utilisez des prix TTC, la taxe est extraite du (et non ajoutée au) sous-total. Pour un taux de 20% sur un sous-total de 120$ : taxe = 120$ - (120$ / 1,20) = 20$.
• Pour des prix HT, la taxe est calculée comme : (sous-total - réduction) × taux / 100.
• Vérifiez que le paramètre shop_tax_rate est le pourcentage correct (ex. 20 pour 20%, pas 0,20).

Le panier ne fusionne pas après la connexion

• Le panier de session est identifié par la clé de session shop_cart. Si la session a été effacée avant la connexion, le panier invité ne peut pas être trouvé.
• La fusion se produit dans CartService::mergeSessionCart() lors du premier accès au panier après la connexion.