E-Shop

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.

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 l’URL externe au lieu du flux de panier interne.

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 : Placer l’add-on

Copiez ou créez un lien symbolique du dossier shop dans le répertoire « extensions/addons » de Larapen :

Étape 2 : Activer l’add-on

Allez dans Admin → Add-ons → Add-ons installés et activez E-Shop.

Étape 3 : Exécuter les migrations

Cela crée les tables suivantes : shop_products, shop_product_variants, shop_carts, shop_cart_items, shop_orders, shop_order_items, shop_transactions, shop_coupons, shop_product_feed_data, shop_category_feed_data, shop_merchant_feed_platforms et shop_merchant_feed_field_mappings. Les catégories de produits utilisent la table principale categories avec categorizable_type = 'product'.

Étape 4 : Définir les permissions

L’add-on enregistre 19 permissions (voir Permissions). Assignez-les aux rôles administrateurs via Admin → Utilisateurs → Rôles & Permissions.

Étape 5 : Configurer

Accédez à Admin → Shop → Paramètres et configurez la devise, les taxes, la livraison et les options de commande. Voir Configuration.

Configuration

Tous les paramètres sont gérés dans Admin → Shop → 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

Paramètre	Description	Par défaut
shop_order_prefix	Préfixe pour les numéros de commande générés (ex. ORD-20260307-00000001).	ORD
shop_products_per_page	Nombre de produits par page dans le catalogue.	12
shop_sidebar_position	Position de la barre latérale sur les pages de liste : left, right ou none.	right
shop_grid_columns	Nombre de colonnes de produits par rangée en vue grille (1–4).	3
shop_default_view_mode	Mode d’affichage initial du catalogue : grid ou list.	grid
shop_guest_checkout	Permettre aux clients de commander sans créer de compte.	true

Taxes

Paramètre	Description	Par défaut
shop_tax_enabled	Activer le calcul des taxes sur les commandes.	false
shop_tax_rate	Taux de taxe en pourcentage (ex. 20 pour 20%).	0
shop_tax_inclusive	Indique si les prix des produits incluent déjà la taxe. Lorsque activé, le montant de la taxe est extrait des prix plutôt qu’ajouté.	false

Livraison

Paramètre	Description	Par défaut
shop_shipping_enabled	Activer les frais de livraison sur les commandes avec des produits physiques.	true
shop_free_shipping_threshold	Seuil de sous-total pour la livraison gratuite. Mettre à 0 pour désactiver.	0
shop_shipping_flat_rate	Tarif forfaitaire de livraison appliqué lorsque la commande ne remplit pas les conditions de livraison gratuite.	10

Produits numériques

Paramètre	Description	Par défaut
shop_digital_max_downloads	Nombre maximum de téléchargements d’un produit numérique par achat. Mettre à 0 pour illimité.	5
shop_digital_expiry_days	Nombre de jours après l’achat avant l’expiration du lien de téléchargement.	30

Stock & Notifications

Paramètre	Description	Par défaut
shop_low_stock_threshold	Quantité en stock à laquelle les produits sont signalés comme stock faible.	5
shop_notify_admin_on_order	Envoyer une notification par e-mail aux administrateurs lorsqu’une nouvelle commande est passée.	true
shop_notify_customer_on_order	Envoyer un e-mail de confirmation de commande au client.	true

Variables d’environnement

Admin : Paramètres

La page des paramètres (Shop → 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 : Téléchargements maximum par achat, expiration du lien en jours.
• Stock : Seuil de stock faible.
• Notifications : Notification admin pour nouvelle commande, confirmation de commande client.

Admin : Produits

La page Produits (Shop → 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 :

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.
• 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 URL externe. 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.

Produits externes

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

• Un champ URL externe apparaît.
• Le produit ne peut pas être ajouté au panier.
• Le front-end affiche un bouton « Acheter maintenant » renvoyant vers l’URL externe.
• 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 Shop → 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 (Shop → Commandes) fournit une liste de toutes les commandes clients.

Liste des commandes

Un tableau paginé et filtrable affichant :

• Numéro de commande (format : ORD-AAAAMMJJ-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 (Shop → 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

Statut	Description
pending	Commande passée mais pas encore traitée ni payée.
processing	La commande est en cours de préparation / exécution.
completed	La commande a été exécutée et livrée / téléchargée.
cancelled	La commande a été annulée. Le stock est automatiquement restauré.
refunded	Le paiement a été remboursé au client.

Statuts de paiement

Statut	Description
pending	En attente de paiement.
paid	Paiement reçu et confirmé.
failed	La tentative de paiement a échoué.
refunded	Le paiement a été remboursé.

Admin : Coupons

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

Champs du coupon

Champ	Description
code	Code coupon unique saisi par le client lors de la commande.
type	Réduction en percentage (pourcentage) ou fixed (montant fixe).
value	Montant de la réduction (points de pourcentage ou montant fixe en devise).
min_order_amount	Sous-total minimum requis pour appliquer le coupon.
max_discount	Plafond de réduction maximum (utile pour les coupons en pourcentage sur les grosses commandes).
max_uses	Nombre total de fois que ce coupon peut être utilisé par tous les clients.
max_uses_per_user	Utilisations maximum par utilisateur individuel.
starts_at	Le coupon devient valide après cette date.
expires_at	Le coupon expire après cette date.
is_active	Activer/désactiver le 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 : Flux marchands

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

Plateformes supportées

Plateforme	Format	Paramètres clés
Google Merchant Center	XML	ID Merchant Center, Pays cible, Langue du contenu
Bing / Microsoft	XML	ID marchand, ID boutique
Facebook / Meta Commerce	XML	ID compte Commerce, ID catalogue
Amazon Product Ads	XML	ID vendeur, ID marketplace, Catégorie par défaut
TikTok Shop	CSV	ID TikTok Shop
Yandex.Market	YML	Nom de la boutique, Nom de l’entreprise
Baidu Commerce	XML	ID marchand

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

Méthode	URL	Nom de la route	Description
GET	/{locale}/shop	shop.index.localized	Page de liste des produits
GET	/{locale}/shop/category/{slug}	shop.category.localized	Liste filtrée par catégorie
GET	/{locale}/shop/product/{slug}	shop.product.localized	Page de détail du produit

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>).

Front-end : Panier d’achat

Routes

Méthode	URL	Nom de la route	Description
GET	/{locale}/shop/cart	shop.cart.localized	Voir le panier
POST	/{locale}/shop/cart/add	shop.cart.add.localized	Ajouter un article au panier
POST	/{locale}/shop/cart/update	shop.cart.update.localized	Mettre à jour la quantité
POST	/{locale}/shop/cart/remove	shop.cart.remove.localized	Retirer un article du panier
POST	/{locale}/shop/cart/clear	shop.cart.clear.localized	Vider le panier
POST	/{locale}/shop/cart/coupon	shop.cart.coupon.localized	Appliquer un code coupon
DELETE	/{locale}/shop/cart/coupon	shop.cart.coupon.remove.localized	Retirer le coupon appliqué

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

Méthode	URL	Nom de la route	Description
GET	/{locale}/shop/checkout	shop.checkout.localized	Formulaire de commande
POST	/{locale}/shop/checkout	shop.checkout.process.localized	Traiter la commande
GET	/{locale}/shop/checkout/success/{orderNumber}	shop.checkout.success.localized	Page de succès de la commande

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

Méthode	URL	Nom de la route	Description
GET	/{locale}/shop/my-orders	shop.orders.localized	Lister les commandes de l’utilisateur (authentification requise)
GET	/{locale}/shop/my-orders/{orderNumber}	shop.orders.show.localized	Détail de la commande (authentification requise)
GET	/{locale}/shop/my-orders/{orderNumber}/download/{itemId}	shop.orders.download.localized	Télécharger un produit numérique (authentification requise)

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.

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

Étape 1 : Remplacer les fichiers

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

Étape 2 : Exécuter les migrations

Étape 3 : Vider les caches

Étape 4 : Reconstruire les assets

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 URL externe. Ils ne peuvent pas être ajoutés au panier interne. Sur le front-end, un lien « Acheter maintenant » 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é.

Le flux marchand retourne vide ou 404

• Vérifiez que la plateforme est activée dans Shop → 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.