Guide de l'opérateur WebBlocks Commerce

Ce guide explique comment installer, configurer et tester WebBlocks Commerce. Le plugin prend en charge un panier public basé sur une session, une collecte de clients et d'adresses de livraison, un mode de commande test sans paiement, un paiement hébergé sur plusieurs lignes via PayPal ou SumUp, un administrateur de produits et de commandes en lecture seule, des paramètres de fournisseur cryptés en écriture seule, des diagnostics sécurisés, des pages de produits publiques et un bloc de bouton d'achat Commerce appartenant au plugin. Les données de carte de paiement restent sur la surface de paiement hébergée du fournisseur sélectionné.

Les propriétaires de magasins qui souhaitent connecter SumUp doivent commencer par une approche axée sur les tâches. Démarrage rapide SumUp. Ce guide de l'opérateur est le guide technique référence pour l'architecture, les API, la vérification et le dépannage avancé.

Le plugin est développé dans son propre référentiel, webblocks-commerce-plugin, aux côtés des autres plugins du catalogue. Il reste un package de plug-in installé manuellement et ne doit pas être déplacé vers le noyau du CMS.

Version du package documentée : 0.14.0. WebBlocks CMS ^1.61.0 ; PHP >=8.3.

PHP ext-intl est requis sur les environnements d'exécution Web et CLI pour le formatage monétaire.

1. Un opérateur CMS installe et active WebBlocks Commerce.
2. L'opérateur exécute les migrations de plugins à partir de l'écran de détails du plugin.
3. L'opérateur sélectionne PayPal, SumUp ou Test order (no payment) et une devise par défaut compatible dans Commerce Settings. Les vrais fournisseurs exigent des informations d’identification ; Les valeurs de l'environnement géré par l'hébergement peuvent être utilisées à la place comme remplacements.
4. L'opérateur ouvre Commerce Settings pour confirmer la préparation du paiement et du webhook.
5. L'opérateur crée un produit commercial.
6. L'écran de détail du produit affiche une URL d'achat publique.
7. L'opérateur ajoute un bloc Commerce Buy Button à une page et sélectionne le produit.
8. Le bloc ajoute le produit à /plugins/webblocks-commerce/cart ; le visiteur met à jour les quantités et saisit les coordonnées et les coordonnées de livraison requises.
9. En mode commande test, Commerce enregistre une commande impayée en attente et revient directement à la page d'état de la commande sans contacter un fournisseur.
10. Avec PayPal ou SumUp, le visiteur approuve le paiement sur la page hébergée du fournisseur sélectionné et revient sur le site.
11. Les commandes d'un fournisseur réel restent en attente jusqu'à ce qu'un webhook vérifié par le fournisseur confirme le paiement.
12. L'opérateur examine les détails du client, de la livraison, de l'article, des taxes et du paiement sous Commerce Orders.

Construisez le ZIP du plugin à partir du référentiel du plugin :

L'artefact est écrit dans build/webblocks-commerce-{version}.zip avec son SHA-256 à côté.

Ensuite, complétez le cycle de vie manuel du plugin :

1. Ouvrez System -> Plugins.
2. Téléchargez le ZIP WebBlocks Commerce généré.
3. Consultez l’écran de détails du plugin.
4. Activez le plug-in.
5. Exécutez la configuration/les migrations du plugin si le plugin signale Setup required.
6. Confirmez que l’état passe de configuration requise à prêt.

Le plugin possède les tables webblocks_commerce_*. La désactivation du plugin rend les itinéraires, les menus, les paramètres et le comportement inertes. La désinstallation d'un plugin téléchargé manuellement désactivé supprime le package téléchargé, mais préserve les tables appartenant au plugin.

Les outils de l'opérateur de confiance peuvent effectuer le flux de travail de configuration et de création de pages via /webadmin/api lorsque le jeton API CMS dispose de fonctionnalités explicites de plug-in, de commerce et de contenu.

Cycle de vie du plugin :

Ressources commerciales :

Les capacités de jeton requises sont intentionnellement divisées :

• Cycle de vie du plugin : plugins.read, plugins.install, plugins.manage, plugins.setup et uniquement en cas de besoin plugins.uninstall
• travail du produit : commerce.read et commerce.products.write
• révision de la commande : commerce.orders.read
• Emplacement des pages : content.validate et content.apply

Le flux API pour l'ajout d'un bouton d'achat est :

1. Installer, activer et configurer webblocks-commerce.
2. Créez un produit actif avec POST /webadmin/api/commerce/products.
3. Lire GET /webadmin/api/block-types ou GET /webadmin/api/content-contract.
4. Ajouter un bloc webblocks-commerce-buy-button via la validation/l'application du contenu.
5. Définissez settings.commerce_product_id sur l'ID de produit renvoyé par l'API Commerce.

Le bloc Commerce Buy Button appartient au plugin. Il est masqué de la découverte de blocs lorsque le plugin est désactivé, et la validation/application du contenu rejette les identifiants de produit manquants, inconnus ou inactifs. Son moteur de rendu public publie dans le panier appartenant au plugin ; aucun bloc HTML de confiance n’est requis. L'API ne collecte pas de données de carte ; les visiteurs effectuent le paiement sur la caisse hébergée PayPal ou SumUp configurée.

WebBlocks Commerce utilise les API REST PayPal. PayPal documente que les API REST utilisent des jetons d'accès OAuth 2.0 et que les appels d'API échangent un identifiant client et un secret client contre un jeton d'accès. Gardez le secret du client privé et ne le collez jamais dans le contenu du CMS, les pages de documentation, les captures d'écran ou les journaux d'assistance.

ORéférences PayPal officielles :

• Démarrez avec les API REST PayPal
• Codes de devises et précision pris en charge par PayPal
• API Webhooks PayPal
• Vérifier la signature du webhook

Ouvrez Commerce Settings, sélectionnez PayPal, sélectionnez Sandbox et entrez l'ID client, le secret client, et l'identifiant du webhook. Les champs sont en écriture seule : les valeurs enregistrées sont cryptées dans le tableau des paramètres du plugin et ne sont jamais restitués dans le navigateur. Laisser un champ vide conserve sa valeur actuelle ; utilisez la case à cocher explicite pour le supprimer.

Pour la configuration gérée par l'hébergement, les variables d'environnement suivantes restent prises en charge et prennent en charge priorité sur les paramètres d'administration chiffrés : 

Utilisez WEBBLOCKS_COMMERCE_PAYPAL_MODE=live uniquement après que l'extraction sandbox et la vérification du webhook aient été testées.

Dans le tableau de bord du développeur PayPal :

1. Ouvert Apps & Credentials.
2. Utilisez l'application API REST par défaut ou créez une nouvelle application.
3. Copiez l'ID client sandbox et le secret client dans le formulaire Paramètres Commerce sécurisé (ou dans l'environnement d'installation lors de l'utilisation de remplacements gérés par l'hébergement).
4. Créez ou ouvrez les paramètres du webhook de l'application.
5. Ajouter cette URL de webhook : 

1. Abonnez-vous au minimum à :

1. Copiez l'ID du webhook PayPal dans le formulaire Paramètres commerciaux (ou WEBBLOCKS_COMMERCE_PAYPAL_WEBHOOK_ID lors de l'utilisation d'un remplacement d'environnement).
2. Utilisez les comptes acheteur et vendeur PayPal sandbox pour les tests de paiement.

Pour les tunnels HTTPS locaux, utilisez l'URL HTTPS du tunnel comme URL du webhook. Pour la production, utilisez l'URL publique finale du site HTTPS.

SumUp Hosted Checkout conserve la saisie de la carte et l'interface utilisateur du portefeuille prise en charge sur une page hébergée par SumUp. Le l'intégration crée le côté serveur de paiement et n'expose jamais la clé API au navigateur.

Pour un flux de travail de propriétaire de magasin écran par écran, utilisez le Démarrage rapide SumUp. La courte séquence de configuration est :

1. Créez et sélectionnez un marchand sandbox sous SumUp Dashboard Paramètres du développeur → Sandboxes.
2. Copiez le sandbox Merchant ID affiché dans la zone de compte du tableau de bord en haut à gauche.
3. Créez une clé API de test secrète sous Paramètres → Pour les développeurs → Boîte à outils → Clés API.
4. Entrez la passerelle, le mode, la clé API et le code marchand dans les paramètres Commerce et confirmez que vous êtes prêt.
5. Testez avec la carte sandbox documentée de SumUp avant d'utiliser les informations d'identification en direct.

ORéférences officielles SumUp :

• Caisse hébergée
• Créer et récupérer des caisses
• Webhooks d'état de paiement
• Clés API
• Test des paiements en ligne

Dans Commerce Settings, sélectionnez SumUp, sélectionnez Sandbox, puis saisissez la clé API et le code marchand. Les informations d'identification enregistrées sont chiffrées au repos et restent en écriture seule. Les déploiements gérés par l'hébergement peuvent définissez plutôt ces variables d'environnement ; ils ont priorité et font correspondre les champs du formulaire lecture seule : 

Utilisez la clé API secrète créée pour le marchand sandbox sélectionné ; n'utilisez pas la clé publique SumUp. Une clé secrète de test commence normalement par sk_test_. Ne le collez pas dans les blocs CMS, les paramètres du site, captures d'écran, journaux d'assistance ou discussion normale. WebBlocks Commerce envoie ce rappel automatiquement lorsqu'il crée chaque paiement : 

Aucun enregistrement manuel de webhook dans le tableau de bord SumUp n'est requis pour cet adaptateur. Le public Le point de terminaison HTTPS doit néanmoins être accessible par SumUp et ne doit pas être bloqué par un pare-feu, page de maintenance, mot de passe HTTP ou règle de proxy.

SumUp appelle le return_url configuré avec CHECKOUT_STATUS_CHANGED et un ID de paiement. Cela la charge utile n’est pas acceptée comme preuve de paiement. WebBlocks Commerce récupère le paiement à partir de SumUp, fait ensuite correspondre l'identifiant, le code marchand, la référence de la commande, le montant, la devise, l'état du terminal, et transaction réussie avant de marquer une commande payée. Transitions de statut ayant échoué et expiré libérer l'inventaire réservé. Les types d'événements inconnus sont ignorés en toute sécurité.

Ouvert :

L'écran des paramètres fournit des champs d'informations d'identification en écriture seule et affiche intentionnellement uniquement des diagnostics sécurisés :

• passerelle active
• devise par défaut et sa source de configuration
• Mode PayPal
• Mode Somme
• ID client configuré ou manquant
• Secret client configuré ou manquant
• ID webhook configuré ou manquant
• préparation à la caisse
• préparation au webhook
• URL du webhook attendu
• Clé API SumUp et code marchand configurés ou manquants
• Préparation au schéma du plugin

Il ne doit pas afficher les secrets PayPal bruts, les clés API SumUp, les jetons d'accès, les signatures de charge utile des webhooks ou les informations d'identification de paiement. Les champs d'informations d'identification vides préservent les valeurs chiffrées existantes. Les contrôles d'effacement explicites suppriment les valeurs stockées, tandis que les valeurs gérées par l'environnement ne peuvent pas être modifiées ou effacées du CMS.

Ouvert :

Créer un produit avec :

• titre
• limace
• description
• statut
• montant du prix
• devise
• quantité d'inventaire facultative
• SKU en option
• portée du site facultative

Définissez le statut du produit sur Active lorsqu'il doit être disponible pour le paiement. Les produits brouillons et archivés ne démarrent pas le paiement public.

La devise par défaut est stockée avec les autres paramètres Commerce et est utilisée pour les nouveaux produits. WEBBLOCKS_COMMERCE_DEFAULT_CURRENCY reste un remplacement d'environnement facultatif ; lorsqu'il est présent, le le sélecteur est en lecture seule. La devise du produit est sélectionnée dans la liste prise en charge par la passerelle active, et l'API interne du produit applique la même règle.

Les passerelles de commutation sont bloquées si un produit non archivé utilise une devise non prise en charge par la cible passerelle. Les paniers en devises mixtes restent rejetés. La caisse effectue une compatibilité finale de la passerelle vérifiez avant de créer une commande ou de réserver un inventaire.

Les prix sont des unités mineures entières, mais la précision des unités mineures est spécifique à la devise plutôt que toujours deux chiffres. Les vues publiques et administratives utilisent les paramètres régionaux actuels du CMS via PHP intl NumberFormatter, de sorte que les symboles et les séparateurs sont localisés pour EUR, USD, GBP, JPY et chaque devise sélectionnable. Les requêtes de passerelle utilisent la même précision. Zéro décimal spécifique à PayPal les exigences pour HUF et TWD sont respectées.

Il n’existe aucune dépendance Composer supplémentaire. PHP ext-intl est une exigence de plate-forme et doit être activé pour le serveur Web et la CLI. Le résultat de santé du plugin avertit lorsqu’il n’est pas disponible. Les codes pris en charge sont basés sur le code officiel Référence de devise PayPal et SumUp Checkout API enum ; pays marchand et les restrictions de compte peuvent toujours restreindre ces listes de fournisseurs.

L'écran de détail du produit affiche l'URL d'achat public du produit :

Une fois le plug-in activé et prêt à être configuré, le sélecteur de blocs du générateur de pages affiche un bloc Commerce Buy Button appartenant au plug-in.

Flux de travail recommandé :

1. Ouvrez la page d'illustration, de portfolio ou « Œuvres » dans le générateur de pages.
2. Ajoutez Commerce Buy Button à l'emplacement souhaité.
3. Sélectionnez un produit commercial actif.
4. Modifiez éventuellement l'étiquette du bouton, l'alignement et l'affichage du prix.
5. Publiez la page lorsque le contenu environnant est prêt.

Le bloc affiche un formulaire public natif qui ajoute le produit sélectionné à :

L'URL d'achat du produit reste utile pour les liens vers les détails du produit et expose une action d'ajout au panier. Le paiement est effectué à partir du panier, les champs obligatoires concernant le client et la livraison ne peuvent donc pas être ignorés. Les vues du panier, de la page produit et de l'état de paiement étendent toutes le CMS mise en page publique, préservant les emplacements d'en-tête et de pied de page du site actif.

Ne collez pas les URL de paiement hébergées par le fournisseur dans le contenu du CMS. Ils sont générés par commande et doivent provenir uniquement du flux de démarrage du paiement.

Lorsqu'un visiteur utilise un bloc Commerce ou une page produit :

1. Le plugin vérifie la configuration, l'état du produit, le stock suivi et la devise du panier.
2. Le produit est stocké dans le panier côté serveur sauvegardé par session ; aucune donnée de paiement n'est collectée.
3. Le visiteur fournit son nom, son e-mail, son adresse de livraison et un ajout facultatif de téléphone/adresse.
4. Lors du paiement, WebBlocks Commerce gèle les métadonnées client/livraison, les titres de lignes localisés, les prix, la TVA et les totaux sur une commande en attente et réserve le stock de manière atomique.
5. En mode commande test, le visiteur revient directement sur une page de statut signée et aucun prestataire de paiement n'est contacté. Avec PayPal ou SumUp, l'adaptateur actif crée une caisse hébergée et redirige le visiteur.
6. Une page de retour signée peut signaler que le traitement se poursuit, mais elle ne marque jamais la commande payée.
7. Les webhooks PayPal sont vérifiés par signature et les commandes PayPal approuvées sont capturées.
8. Les notifications de statut SumUp déclenchent une nouvelle récupération de l'API de paiement et une correspondance complète entre commande et transaction.
9. Seul le résultat du fournisseur vérifié déplace la commande et la tentative de paiement vers paid/succeeded.

Les événements Webhook sont stockés par passerelle et par ID d'événement, de sorte que la livraison répétée est idempotente.

Ouvert :

Les commandes sont en lecture seule. L'écran de détail de la commande affiche : 

• numéro de commande
• nom du client, e-mail requis, téléphone facultatif et adresse de livraison capturés par le panier public
• état de la commande
• articles de ligne
• tentatives de paiement
• références de paiement et de paiement sur la passerelle
• horodatages

La modification manuelle du statut, les remboursements, le calcul des frais d'expédition et les flux de travail d'exécution sont intentionnellement différés. La capture des clients et des adresses de livraison, les instantanés de TVA et la réservation des stocks sont implémentés.

Sélectionnez Test order (no payment) dans Commerce Settings lorsqu'un propriétaire de magasin souhaite vérifier le Remplissez le formulaire de vitrine et le flux d'enregistrement des commandes sans contacter PayPal ou SumUp. Le public le panier indique clairement le mode, nécessite les détails du client et de la livraison, crée une commande en attente, réserve le stock suivi, enregistre une fausse tentative de paiement en attente pour la continuité de l'audit et redirige à une page de confirmation signée indiquant qu'aucun paiement n'a été encaissé. Revenir à un configuré véritable fournisseur avant d'accepter les commandes payantes des clients.

Utilisez cette liste de contrôle avant de passer en mode direct :

• WebBlocks Commerce est installé, activé et prêt à être configuré.
• Commerce Settings affiche le schéma prêt.
• Commerce Settings affiche la passerelle paypal.
• L'ID client PayPal est configuré.
• Le secret client PayPal est configuré.
• L'ID du webhook PayPal est configuré.
• L'URL du webhook utilise HTTPS et pointe vers /plugins/webblocks-commerce/webhooks/paypal.
• Un produit est actif et a le prix/devise attendu.
• L'URL d'achat du produit s'ouvre publiquement.
• Une page avec un Commerce Buy Button ajoute le produit attendu à /plugins/webblocks-commerce/cart.
• Le démarrage du paiement redirige vers PayPal.
• Un acheteur sandbox peut approuver le paiement.
• Le visiteur revient à la page de réussite signée.
• La commande reste en attente avant la confirmation du webhook.
• PayPal livre CHECKOUT.ORDER.APPROVED.
• Le webhook vérifie avec succès.
• La capture de la commande PayPal est terminée.
• La commande CMS devient paid.
• La tentative de paiement devient succeeded.
• Renvoyer le même webhook ne duplique pas les tentatives de paiement.
• Les signatures de webhook invalides sont rejetées et ne marquent pas les commandes payées.
• Aucun secret PayPal n'apparaît dans les écrans d'administration, les pages publiques, les journaux, les captures d'écran ou les documents.

• Le marchand sandbox est sélectionné dans SumUp Dashboard.
• L'ID marchand et la clé secrète sk_test_ appartiennent à ce même compte sandbox.
• Commerce Settings affiche la passerelle sumup, le mode sandbox et le paiement prêt.
• La clé API de test et le code marchand sandbox sont configurés, mais la valeur de la clé n'est pas rendue.
• Un bloc Commerce ajoute le produit EUR actif à /plugins/webblocks-commerce/cart.
• La quantité, la TVA et le montant final sont corrects avant le paiement.
• Le démarrage du paiement crée une commande en attente et redirige vers checkout.sumup.com.
• La référence de paiement SumUp correspond au numéro de commande CMS.
• La réalisation d'un paiement sandbox produit CHECKOUT_STATUS_CHANGED à /plugins/webblocks-commerce/webhooks/sumup.
• Le gestionnaire récupère le paiement depuis SumUp et confirme la réussite de la transaction.
• La commande CMS devient paid et sa tentative de paiement devient succeeded.
• Renvoyer la même notification payante ne crée pas une autre tentative de paiement.
• Un code marchand, une référence, un montant ou une devise incompatible ne marque jamais une commande payée.
• Les paiements SumUp ayant échoué ou expirés libèrent l'inventaire réservé.
• La carte de test réussie documentée 4200 0000 0000 0091 est complétée par toute date d'expiration future. et tout CVV à trois chiffres.

Avant de passer à WEBBLOCKS_COMMERCE_PAYPAL_MODE=live :

• Confirmez que l'opérateur possède un compte PayPal Business lorsque PayPal l'exige.
• Créez ou sélectionnez l'application REST en direct dans le tableau de bord du développeur PayPal.
• Remplacez l'ID client sandbox, la clé secrète client et l'ID webhook par des valeurs actives.
• Configurez l'URL du webhook en direct avec le domaine HTTPS de production.
• Confirmez que le site de production peut recevoir des demandes de webhook PayPal publiques.
• Rexécutez un paiement en direct de faible valeur si cela est acceptable pour l'opérateur.
• Rexaminer la commande dans l'administrateur CMS.

Gardez le bac à sable et les informations d'identification en direct séparés. Ne réutilisez pas les ID de webhook sandbox en mode live.

Pour le mode direct SumUp, sélectionnez le compte marchand réel vérifié, créez un sk_live_ distinct clé API secrète, utilisez l'ID marchand en direct de ce compte, définissez WEBBLOCKS_COMMERCE_SUMUP_MODE=live, actualisez la configuration de l'application et exécutez un paiement acceptable de faible valeur. Ne jamais réutiliser ou mélangez un marchand sandbox, une clé de test, un marchand en direct ou une clé en direct.

Si la page d'achat indique que le paiement n'est pas prêt :

• Ouvert Commerce Settings.
• Confirmez que la passerelle sélectionnée est paypal ou sumup.
• Pour PayPal, confirmez que l'ID client et le secret client sont configurés.
• Pour SumUp, confirmez que la clé API et le code marchand sont configurés.
• Confirmez que le produit est actif et a un prix valide.
• Confirmez que les migrations du plug-in ont été exécutées.

Si le paiement est redirigé vers PayPal mais que la commande reste en attente :

• Confirmez que l'URL du webhook PayPal est correcte.
• Confirmez que WEBBLOCKS_COMMERCE_PAYPAL_WEBHOOK_ID correspond au webhook configuré dans PayPal.
• Confirmer que PayPal envoie CHECKOUT.ORDER.APPROVED.
• Confirmez que le site est accessible depuis PayPal via HTTPS.
• Confirmez que la vérification de la signature du webhook n'échoue pas.

Si un webhook est rejeté :

• Vérifiez que l'événement webhook provient du mode PayPal correspondant.
• Vérifiez que les informations d'identification du sandbox ne sont pas mélangées avec les ID de webhook en direct.
• Vérifiez que l'ID du webhook appartient à la même application PayPal REST que les informations d'identification du client.

Si une commande SumUp reste en attente :

• Confirmez que l'URL HTTPS publique /plugins/webblocks-commerce/webhooks/sumup est accessible.
• Confirmez que la clé API peut lire le paiement et appartient au code marchand configuré.
• Confirmez que la référence de paiement, le montant et la devise correspondent toujours à la commande CMS.
• Confirmez que SumUp rapporte PAID et inclut une transaction SUCCESSFUL.

Si la page hébergée par SumUp signale un paiement expiré ou manquant, démarrez un nouveau paiement à partir du panier. Les sessions de paiement hébergées expirent après environ 30 minutes et leurs URL ne doivent pas être mises en favoris. ou réutilisé.

Le plugin actuel n'inclut pas encore :

• expédition
• coupons
• abonnements
• remboursements de CMS
• comptes clients
• workflows d'exécution
• Intégration du compte du fournisseur (les informations de paiement peuvent être modifiées dans les paramètres Commerce)

Ces fonctionnalités restent distinctes plutôt que d'être cachées dans les intégrations du fournisseur.

Le statut de la commande n'est modifié que via Support\Orders\OrderStateMachine, jamais un mise à jour brute. Il applique le graphe de transition autorisé (pending → paid|failed|cancelled|expired, paid → refunded), est idempotent pour les webhooks relivrés et verrouille la ligne de commande afin les rappels de la passerelle de course ne peuvent pas appliquer une transition deux fois.

Le stock suivi (inventory_quantity non nul) est réservé atomiquement au démarrage du paiement, ce qui empêche la survente sous des acheteurs simultanés, et est relâché dans le catalogue lorsqu'un la commande est annulée, expire, échoue ou est remboursée. Produits avec un inventory_quantity nul ne sont pas suivis (illimités) et ne sont jamais décrémentés.

ALes commandes pending abandonnées conservent leur réservation jusqu'à leur expiration. Courir php artisan webblocks-commerce:expire-stale-orders --minutes=30 selon un calendrier de sortie du stock détenu par les caisses que l'acheteur n'a jamais finalisées. Connectez-le au noyau de la console de l'application hôte, par exemple $schedule->command('webblocks-commerce:expire-stale-orders')->everyFifteenMinutes();.

Carts sont côté serveur, persistants et à devise unique. Un panier stocke uniquement le produit références + quantités ; les prix et la TVA sont résolus en direct à partir du catalogue actuel et uniquement figé sur la commande à la caisse (StartCheckout::forCart), qui construit une commande multi-lignes, réserve le stock de manière atomique pour chaque ligne et marque le panier converted. En ajoutant le même le produit fusionne les quantités ; l'ajout d'une devise différente, ou d'un stock supérieur au stock suivi, est rejeté.

Les visiteurs utilisent le panier public basé sur une session sans jeton API. Avant le paiement, le formulaire public nécessite le nom, l'adresse e-mail, la rue, le code postal, la ville et le code du pays à deux lettres du client ; téléphone et une deuxième ligne d'adresse restent facultatives. Les détails sont stockés dans les métadonnées du panier/commande et affichés sur les écrans d'état de la commande et de détails de la commande d'administration.

Voies publiques :

• GET /plugins/webblocks-commerce/cart — examiner les lignes du panier, la TVA et le total
• POST /plugins/webblocks-commerce/cart/items/{product} — ajoutez un produit à partir d'un bloc Commerce ou achetez une page
• PATCH|DELETE /plugins/webblocks-commerce/cart/items/{product} — modifier la quantité ou supprimer une ligne
• POST /plugins/webblocks-commerce/cart/checkout — enregistrez les détails du client/de la livraison, créez la commande et continuez vers la passerelle configurée

Les pages publiques du panier, de la page d'achat et de l'état du paiement étendent la présentation publique du CMS et affichent le propres emplacements header et footer du site autour de leur contenu, résolus depuis la page d'accueil par Support\PublicStorefrontShell. Un en-tête détenu dans un Shared Slot fonctionne de la même manière, donc en changeant le l'en-tête du site modifie la vitrine avec. Le bouton Commerce Buy est un bloc de plugin natif et publications dans le panier ; il ne nécessite pas de bloc HTML de confiance.

Tout ce que fait le panier est disponible surAPI interne appartenant au plugin— monté dans le Groupe d'API interne du CMS (/webadmin/api, authentification par jeton du porteur) via le pluginapiRoutes()crochet, Ainsi, les agents IA bénéficient des mêmes capacités que le panneau d'administration offre aux humains. Points de terminaison (capacité dans parenthèses) :

• POST /webadmin/api/commerce/cart — créer un panier (commerce.cart.write)
• GET /webadmin/api/commerce/cart/{token} — lire un panier avec des totaux en direct (commerce.cart.read)
• POST /webadmin/api/commerce/cart/{token}/items — ajouter {product_id, quantity} (commerce.cart.write)
• PATCH /webadmin/api/commerce/cart/{token}/items/{product} — définir {quantity} (0 suppressions) (commerce.cart.write)
• DELETE /webadmin/api/commerce/cart/{token}/items/{product} — supprimer une ligne (commerce.cart.write)
• DELETE /webadmin/api/commerce/cart/{token}/items — vider le panier (commerce.cart.write)
• POST /webadmin/api/commerce/cart/{token}/checkout — démarre le paiement hébergé, renvoie redirect_url (commerce.cart.write)

Les produits et les commandes sont exposés de la même manière (ces points de terminaison appartiennent au plugin, pas au Noyau du CMS, et ne sont présents que lorsque le plugin est activé) :

• GET|POST /webadmin/api/commerce/products, PATCH /webadmin/api/commerce/products/{id} — catalogue incl. tax_class (commerce.read / commerce.products.write)
• GET /webadmin/api/commerce/orders, GET /webadmin/api/commerce/orders/{id} — lecture seule, avec la répartition complète nette/taxe/brut (commerce.orders.read)

ATous ces éléments s'auto-annoncent : lorsque le plugin est activé, ils apparaissent dans la découverte de l'API CMS. (Chemins GET /webadmin/api _links, GET /webadmin/api/openapi.json et conseils de découverte) via la contribution apiDiscovery() du plugin, et disparaissent lorsque le plugin est désactivé.

Il n'y a pas de jeton commercial distinct : le plugin utilise le jeton d'API CMS partagé . C'est Les capacités commerce.* sont ajoutées à l'ensemble des autorisations du CMS via apiCapabilities(). (ils apparaissent comme un groupe « Commerce » dans l'interface utilisateur d'administration du jeton lorsque le plugin est activé), donc un un seul jeton de moindre privilège peut être limité aux seules capacités commerciales.

Storefront partage le système CMS Site+Locale plutôt qu'un système parallèle. Le la ligne du produit de base contient le title/description par défaut/de secours ; une ligne de traduction par langue (webblocks_commerce_product_translations, saisi par produit + paramètres régionaux CMS) les remplace. Ceci est l'axe linguistique du panneau d'administration content — distinct du langage UI du panneau d'administration, qui reste dans les fichiers Laravel resources/lang.

ProductLocalizer résout le titre/description affiché pour un paramètre régional, en revenant à la base. Les paniers portent un locale, donc les résumés des paniers et, surtout, l'instantané du titre de la ligne de commande à l'adresse checkout utilise le texte localisé que l'acheteur a réellement vu. La page d'achat publique se localise via un Requête ?locale=<code>, retour à la base.

Modifier les traductions dans le formulaire de produit d'administration (par paramètres régionaux non activés par défaut) ou via l'API (capacité entre parenthèses) :

• GET /webadmin/api/commerce/products/{product}/translations — base de liste + traductions (commerce.read)
• PUT /webadmin/api/commerce/products/{product}/translations/{locale} — insérer {title?, description?} (commerce.products.write)
• DELETE /webadmin/api/commerce/products/{product}/translations/{locale} — supprimer un paramètre régional (commerce.products.write)