Commencez à vendre avec WebBlocks Commerce

Commerce ajoute trois éléments liés à votre CMS :

• Des produits : titres, descriptions, prix, devises, stock et classe fiscale du produit.
• Un parcours d'achat : un bloc natif Commerce Buy Button, un panier avec réglage des quantités et un formulaire de commande distinct pour les coordonnées et la livraison.
• Des commandes et paiements : lignes de commande enregistrées, informations du client et de livraison, totaux fiscaux et tentatives de paiement. PayPal et SumUp encaissent sur leurs propres pages hébergées ; les visiteurs ne saisissent pas leurs données de carte dans un bloc CMS.

Vous continuez à utiliser des pages CMS ordinaires pour présenter le produit, les photographies, les questions fréquentes et la navigation. Le bloc Commerce relie cette page éditoriale à un produit réel. Modifier un paragraphe de vente ne change ni le prix ni le stock ; ceux-ci se gèrent dans Commerce → Products.

C'est un bon point de départ pour un petit catalogue ou quelques produits vendus sur des pages existantes. Il n'inclut pas de moteur de tarifs d'expédition, de coupons, de processus logistique d'entrepôt ni de bouton de remboursement sur la commande. Collecter une adresse ne déclenche pas l'expédition. Les adhésions récurrentes utilisent le plugin distinct Memberships et sa propre configuration ; il n'est pas nécessaire pour les commandes ponctuelles de ce guide.

Pour les noms des points d'accès, l'intégration développeur et le contrat détaillé des paiements, gardez la référence technique Commerce à portée de main. Ce guide suit les opérations dans le panneau.

Utilisez une installation de test ou une boutique qui n'est pas encore ouverte aux clients. Changer la passerelle active affecte le passage de commande Commerce de toute l'installation ; ne basculez pas une boutique en activité en mode test pendant les achats.

Il vous faut :

• Une installation WebBlocks CMS fonctionnelle et un compte Super admin pour l'installation et les réglages de paiement.
• Une version CMS compatible avec la version choisie du catalogue. Commerce 0.16.0 déclare CMS ^1.100.0 ; le catalogue mentionne aussi Laravel 13. Vérifiez la compatibilité avec votre installation avant de procéder.
• L'extension PHP intl pour le site et pour la ligne de commande. Demandez son activation à l'administrateur si Commerce signale un avertissement de formatage des devises.
• Un site dans le CMS et l'autorisation d'y modifier et prévisualiser une page.
• Plus tard, un compte marchand PayPal ou SumUp adapté, les identifiants de test correspondants et un site HTTPS accessible publiquement pour les notifications du prestataire.

Un Site Admin peut gérer les produits et consulter les commandes des sites qui lui sont attribués. L'installation des plugins, les réglages Commerce et les identifiants de paiement relèvent de Super admin. Si un écran manque, faites vérifier votre rôle et votre affectation ; créer un second compte ne fait pas partie de la configuration.

Le plugin est annoncé gratuit dans le catalogue WebBlocks. Le compte du prestataire est un service distinct ; installer Commerce ne crée ni ne connecte ce compte à votre place.

1. Connectez-vous au CMS et ouvrez System → Plugins.
2. Sélectionnez Browse Plugin Catalog et ouvrez WebBlocks Commerce.
3. Lisez le résultat de compatibilité et les notes de version. Sélectionnez Install from Catalog lorsqu'une version compatible est proposée.
4. Revenez aux détails du plugin installé. Un nouveau paquet démarre en état disabled afin de permettre son examen.
5. Sélectionnez Enable Plugin. Confirmez son activation et examinez le résultat de santé.

Les versions actuelles du CMS appliquent automatiquement les changements de base de données des plugins à l'installation, à la mise à jour et à l'activation. Migrations Up to Date signifie qu'aucune migration manuelle n'est nécessaire. Si la préparation échoue, résolvez le problème indiqué avant de continuer ; réactiver plusieurs fois ne corrige pas une permission de base de données manquante.

La capture montre l'installation terminée. Si votre administrateur fournit plutôt un ZIP de version fiable, utilisez Plugin ZIP → Upload Plugin ZIP sur ce même écran, puis examinez et activez le paquet. Ces deux parcours dans le panneau ne demandent au propriétaire ni dépôt de code source du plugin ni commande de compilation Composer.

Après activation, Commerce → Products, Orders, Settings apparaît dans la barre latérale. Ouvrez Settings. La santé du plugin confirme que le paquet peut fonctionner ; la disponibilité du paiement se vérifie séparément dans Commerce Settings.

1. Ouvrez Commerce → Settings → General.
2. Réglez Gateway sur Test order (no payment).
3. Choisissez EUR dans Default Currency pour cet exemple.
4. Laissez PayPal Mode et SumUp Mode sur Sandbox pour les tests ultérieurs.
5. Sélectionnez Save Commerce Settings, puis revenez à Overview.

La devise par défaut est la valeur initiale des nouveaux produits. Elle ne convertit pas le prix d'un produit existant. Chaque produit conserve sa devise et tous les articles d'un panier doivent utiliser la même.

Dans cet exercice, les contrôles utiles sont Schema: Ready et Gateway: Ready. PayPal et SumUp peuvent afficher Needs config lorsqu'ils sont inactifs. Aucun identifiant de prestataire n'est nécessaire pour une commande de test sans paiement.

La vue d'ensemble peut nommer la passerelle fake : c'est le nom interne de Test order (no payment). Elle enregistre une commande impayée, réserve du stock et ne contacte aucun prestataire. Elle ne simule pas un paiement réussi et ne passe pas la commande à Paid.

Ouvrez Commerce → Products → New Product. Saisissez ces valeurs en remplaçant Northstar Studio par votre site :

Price Amount utilise des unités monétaires mineures entières, pas un prix décimal. Pour €18.00, saisissez 1800, pas 18 ni 18.00. Certaines devises ont un autre nombre de sous-unités ; elles n'utilisent pas toutes des centimes. Vérifiez le prix formaté après enregistrement.

Ne laissez Inventory vide que si vous souhaitez volontairement ne pas suivre le stock. Vide signifie disponibilité illimitée, pas rupture. Choisissez un site précis pour ce parcours. Install-wide est une portée distincte pour Super admin, différente de la sélection du site actuel.

Sélectionnez Save Product, puis vérifiez Active, €18.00, Inventory 24 et Product Available dans les détails. Cet écran fournit aussi une Public Buy URL. Pour un lien direct, copiez celle de votre installation, pas l'adresse localhost d'une capture.

Si d'autres langues sont actives, le formulaire propose des titres et descriptions traduits. Une traduction vide utilise le contenu de base. Traduire la page de vente CMS et le produit Commerce sont deux tâches distinctes : vérifiez les deux lors de l'ajout d'une langue à la boutique.

Créez un brouillon de page pour le carnet ou préparez une mise à jour intermédiaire d'une page de vente publiée. Choisissez le même site que le produit. Ajoutez un titre, une description utile et, si disponible, une photo via la Media Library et le bloc Image habituels.

Reliez ensuite la page à Commerce :

1. Ouvrez l'emplacement Main de la page et choisissez Add Block à l'endroit voulu.
2. Choisissez Commerce Buy Button.
3. Dans Block Fields, sélectionnez Studio notebook sous Product.
4. Réglez Button Label sur Add to Cart.
5. Choisissez l'alignement Start et activez Show price beside the button.
6. Sélectionnez Save Block et ouvrez Preview de la page enregistrée.

Le bloc natif ajoute le produit sélectionné au panier Commerce. Aucun bloc Trusted HTML, formulaire de paiement collé ou script de prestataire n'est nécessaire dans le contenu de la page.

L'aperçu permet de tester avant publication. La bannière d'aperçu ne transforme pas les actions du panier en simulation sans effet. Le bouton modifie toujours le panier de votre session ; terminer le checkout crée toujours une commande. C'est pourquoi vous avez d'abord choisi la passerelle sans paiement.

Pour un lien permanent au panier dans l'en-tête, ajoutez une entrée vers /plugins/webblocks-commerce/cart, nommez-la Cart et choisissez l'icône shopping-cart. Commerce peut afficher la quantité du panier sur cette action. Le guide des menus de navigation explique l'ajout et l'ordre des éléments.

Dans l'aperçu, sélectionnez Add to Cart. Commerce ouvre le panier avec un carnet. Appuyez une fois sur + pour en avoir deux.

Confirmez le nom, la quantité et le prix formaté. Avec les prix EUR et les données d'exemple taxes comprises, deux carnets à €18.00 totalisent €36.00. Vous pouvez diminuer la quantité ou supprimer une ligne. Ajouter à nouveau le même produit cumule les quantités ; une devise différente est refusée.

Sélectionnez Go to checkout. Les coordonnées et la livraison se trouvent sur cet écran séparé. Saisissez des données de test, par exemple Example customer et customer@example.test, plutôt que de vraies données client.

Le formulaire exige nom complet, adresse électronique, rue et numéro, code postal, ville et code pays à deux lettres comme DE. Le téléphone et la seconde ligne d'adresse sont facultatifs. Vérifiez le total et sélectionnez Place test order.

Le formulaire collecte actuellement la livraison même pour un pass d'atelier ou un article non expédié. Ce n'est pas un service de transport : cette version ne calcule pas de tarif et ne réserve pas de transporteur. Le texte d'expédition du récapitulatif ne prouve pas qu'un coût ou un processus logistique est configuré.

Un résultat réussi indique Test Order Received et explique qu'aucun paiement n'a été encaissé. Pending est le statut attendu. Conservez le numéro pour l'étape suivante ; il n'est pas nécessaire de partager le lien privé de suivi.

Ouvrez Commerce → Orders, trouvez le numéro de l'écran de résultat et ouvrez la commande. Vérifiez :

• Status : Pending, car cette commande de test est impayée.
• Items : Studio notebook, quantité 2, €18.00 chacun, total €36.00.
• Customer et Delivery : les informations fictives saisies.
• Gateway : fake, le mode sans paiement.
• Payment Attempts : la tentative enregistrée et son état.
• Détail fiscal : sous-total net, TVA et total brut du checkout.

Rouvrez le produit. Inventory devrait maintenant être 22 : deux unités ont été réservées au début du checkout. Le simple ajout au panier ne réserve rien. Les commandes en attente de vrais prestataires comme les tests sans paiement peuvent retenir du stock.

L'écran de commande est en lecture seule. Vous ne pouvez pas transformer un test en commande payée en modifiant son statut ici ; un retour réussi du navigateur depuis PayPal ou SumUp ne constitue pas non plus une preuve. Le statut réel change après vérification par Commerce de la notification et des détails du paiement.

Les prix et totaux fiscaux sont enregistrés dans la commande au checkout. Une modification ultérieure du prix affecte les prochains achats et ne réécrit pas les montants des commandes existantes.

Devise : le prestataire doit prendre en charge la devise par défaut et celles des produits existants non archivés. Un changement de passerelle peut être refusé si un produit utilise une devise non prise en charge. Corrigez-la ou archivez volontairement le produit ; changer seulement la devise par défaut n'effectue pas de conversion.

Taxes : la classe fiscale du produit se combine aux taux configurés sur le serveur pour le pays fiscal de la boutique. Le plugin ne choisit pas automatiquement une nouvelle juridiction selon chaque adresse. Faites confirmer les réglages fiscaux par l'administrateur de l'hébergement avant d'accepter des commandes.

Les réglages concernés sont WEBBLOCKS_COMMERCE_TAX_ENABLED, WEBBLOCKS_COMMERCE_PRICES_INCLUDE_TAX et WEBBLOCKS_COMMERCE_TAX_COUNTRY. Avec des prix taxes comprises, la TVA est extraite du prix ; avec des prix hors taxes, elle est ajoutée. Le test utilise un taux standard configuré de 19% et des prix EUR taxes comprises : €36.00 incluent €5.75 de TVA et €30.25 nets. Cela illustre ces données d'exemple, pas un taux valable pour toutes les boutiques.

Stock : les unités suivies sont réservées au checkout puis libérées en cas d'échec, d'annulation, d'expiration ou de remboursement dans le cycle pris en charge. Les produits non suivis ne sont pas décrémentés. Le panier revérifie prix et disponibilité avant la création ; un panier enregistré ne garantit ni prix fixe ni stock réservé.

Demandez à l'administrateur de planifier le nettoyage des commandes abandonnées. Le plugin fournit :

Il peut, par exemple, l'exécuter toutes les quinze minutes via le planificateur Laravel de l'application hôte. Choisissez un délai adapté au magasin et au paiement : la commande fait expirer toutes les commandes en attente plus anciennes que ce seuil, pas seulement les tests. Cela libère le stock des achats abandonnés. Attendre davantage ne rend pas une commande de test payée.

Utilisez ici un site de test HTTPS accessible publiquement. Le prestataire ne peut pas envoyer sa notification serveur à l'adresse locale 127.0.0.1 des captures.

1. Dans PayPal Developer Dashboard, ouvrez Apps & Credentials et obtenez le client ID et le client secret sandbox de votre application. Utilisez l'application et le compte marchand prévus pour cette boutique.
2. Dans Commerce → Settings → General, sélectionnez PayPal, choisissez Sandbox pour PayPal Mode, une devise compatible, puis enregistrez.
3. Ouvrez PayPal et saisissez Client ID et Client Secret.
4. Copiez la Webhook URL générée par votre installation. Enregistrez cet endpoint HTTPS dans PayPal pour la même application et le même mode, avec l'événement CHECKOUT.ORDER.APPROVED utilisé ici. Reportez la Webhook ID obtenue dans Commerce.
5. Enregistrez, puis contrôlez la préparation du checkout et du webhook dans Overview et dans PayPal.
6. Lancez une nouvelle commande et approuvez-la avec un compte acheteur sandbox adapté. Vérifiez qu'elle devient Paid après la notification vérifiée, sans vous fier uniquement à la page de retour du navigateur.

L'endpoint public utilise /plugins/webblocks-commerce/webhooks/paypal. Copiez-le du panneau pour que domaine et protocole correspondent à l'installation réelle. Client ID, secret et webhook ID doivent venir de la même application et du même environnement PayPal.

Les instructions REST PayPal expliquent identifiants d'application et comptes sandbox ; la référence Webhooks décrit les abonnements. Vous n'avez pas à implémenter ces API pour le parcours dans le panneau.

Dans General, vous choisissez une seule passerelle de commande active. Configurer les deux prestataires n'ajoute pas de sélecteur pour le visiteur au checkout.

1. Préparez un compte marchand de test SumUp avec sa clé API et son code marchand. Si leur origine n'est pas claire, suivez le parcours de connexion SumUp.
2. Dans Commerce → Settings → General, choisissez SumUp, Sandbox pour SumUp Mode et une devise compatible, puis enregistrez.
3. Ouvrez SumUp, saisissez API Key et Merchant Code, puis enregistrez.
4. Vérifiez la préparation et l'URL webhook générée. Le chemin HTTPS public /plugins/webblocks-commerce/webhooks/sumup doit être accessible.
5. Lancez un nouveau checkout depuis le panier. Commerce crée la session hébergée et dirige le client vers la page SumUp. Terminez le test, revenez sur le site et examinez la commande enregistrée.
6. Confirmez qu'elle devient Paid seulement après récupération et vérification du résultat du paiement par Commerce.

Commerce transmet l'URL de notification SumUp lors de la création de chaque checkout. Il ne demande pas de SumUp Webhook ID distincte. Choisir Sandbox ne transforme pas une clé réelle en clé de test : compte, code marchand et clé doivent appartenir à l'environnement prévu.

La présentation des paiements en ligne SumUp décrit l'encaissement hébergé et la référence Checkouts API le checkout et la notification serveur. Le CMS exploite ce parcours pour vous ; les données de carte restent sur l'interface hébergée par SumUp.

Les champs d'identifiants sont en écriture seule. Après enregistrement, le formulaire redevient vide et indique si une valeur est configurée. Un champ vide ne signifie donc pas nécessairement que l'identifiant a disparu. Le laisser vide conserve la valeur ; utilisez Clear saved value uniquement pour la supprimer volontairement.

Les valeurs enregistrées dans Commerce Settings sont chiffrées au repos. L'administrateur peut aussi gérer les variables correspondantes de l'environnement serveur. Elles sont prioritaires et indiquées Managed by environment ; le champ remplacé est en lecture seule dans le panneau. System liste les noms des variables prises en charge sans exposer leurs valeurs.

Si un remplacement enregistré semble sans effet, vérifiez l'étiquette de provenance avant de le ressaisir. Coordonnez les changements d'environnement avec l'administrateur. Ne placez jamais de clé ou de secret dans une page, un bloc HTML, une capture ou un message d'assistance.

Les réglages de paiement sont communs à l'installation. Les produits limités à un site et les droits Site Admin ne créent pas une configuration marchande séparée pour chaque site.

Terminez d'abord l'exercice sans paiement, puis effectuez un test complet séparé dans le sandbox du prestataire choisi. Les captures ne montrent que l'exercice sans paiement ; elles ne prouvent pas le bon fonctionnement de votre compte ni de vos notifications publiques.

Avant d'ouvrir la page de vente, confirmez que :

• Le prestataire, le mode, les identifiants marchands et les webhooks correspondent.
• Le site et les URL de notification utilisent le bon domaine HTTPS public et restent accessibles.
• Chaque produit à vendre est Active, affecté au bon site, correctement tarifé et dans une devise prise en charge.
• La configuration fiscale et le véritable processus de livraison respectent les promesses de la page.
• Un paiement sandbox devient Paid dans Commerce → Orders après vérification du prestataire. Testez aussi l'annulation et les échecs pertinents.
• Le nettoyage des commandes en attente est planifié et son délai vérifié.
• La page, la navigation, les coordonnées et les langues actives ont été prévisualisées.

Lors du passage volontaire aux paiements réels, utilisez les identifiants live du vrai marchand, le mode correspondant et les bons webhooks de production. Les identifiants ou webhook ID sandbox et live ne sont pas interchangeables. Revérifiez la passerelle et sa préparation, puis suivez votre révision habituelle et le processus de publication.

Publier une page ne configure pas de compte marchand. Changer de passerelle est également distinct de la publication et affecte immédiatement le checkout.

Utilisez Draft pour préparer un produit et Active lorsqu'il est prêt à être acheté. Archivez-le pour arrêter les nouveaux achats et revoyez les pages ou liens qui le présentent encore. Les lignes historiques conservent noms et montants enregistrés.

Avant une mise à jour, lisez notes de version et compatibilité, faites une sauvegarde selon votre procédure habituelle et répétez ensuite un test panier/checkout. Les versions actuelles appliquent les changements de base de données des plugins à la mise à jour et à l'activation.

Désactiver Commerce rend inactifs ses routes, menus, réglages et contributions. Sur une boutique ouverte, tenez compte des visiteurs, des blocs Commerce placés et des notifications des prestataires avant de le faire. Désinstaller un paquet téléversé désactivé conserve ses tables ; cela ne nettoie pas les données de commande.

Le parcours principal est prêt : produit → page CMS → panier → checkout → examen de la commande. Consultez la documentation de référence Commerce pour l'automatisation et le diagnostic avancé, ou revenez à tous les guides pour les tâches courantes de pages, médias et équipe.