Guide de l'opérateur WebBlocks Commerce

Installer, configurer, tester et exploiter le plugin WebBlocks Commerce.

Guide de l'opérateur WebBlocks Commerce

Ce guide explique comment installer, configurer et tester le premier plugin MVP de WebBlocks Commerce. Le plugin actuel prend en charge le paiement hébergé d'un produit unique via PayPal. Il est volontairement restreint : administration des produits, administration des commandes en lecture seule, diagnostics de disponibilité sans exposition de secrets, URL d'achat publiques, un bloc Commerce Buy Button appartenant au plugin, redirections de paiement PayPal et confirmation de capture par webhook PayPal.

Le plugin est développé dans plugins/webblocks-commerce. Il reste un paquet de plugin installé manuellement et ne doit pas être déplacé dans le cœur du CMS.

Parcours utilisateur actuel

Un opérateur du CMS installe et active WebBlocks Commerce.
L'opérateur lance les migrations du plugin depuis l'écran de détail du plugin.
L'opérateur configure les identifiants PayPal dans l'environnement de l'installation.
L'opérateur ouvre Commerce Settings pour confirmer que le paiement et le webhook sont prêts.
L'opérateur crée un produit commerce.
L'écran de détail du produit affiche une URL d'achat publique.
L'opérateur ajoute un bloc Commerce Buy Button à une page et sélectionne le produit.
Un visiteur démarre le paiement, l'approuve dans PayPal et revient sur le site.
La commande reste en attente jusqu'à ce que le webhook PayPal vérifie et capture le paiement.
L'opérateur consulte la commande payée dans Commerce Orders.

Installer le plugin

Génère le ZIP du plugin depuis le dépôt du CMS :

php plugins/webblocks-commerce/build-plugin.php

Puis déroule le cycle de vie manuel du plugin :

Ouvre System -> Plugins.
Téléverse le ZIP WebBlocks Commerce généré.
Consulte l'écran de détail du plugin.
Active le plugin.
Lance l'installation/les migrations du plugin s'il signale Setup required.
Vérifie que l'état passe de « setup required » à « ready ».

Le plugin possède les tables webblocks_commerce_*. Désactiver le plugin rend ses routes, menus, réglages et comportements inertes. Désinstaller un plugin désactivé téléversé manuellement supprime le paquet téléversé, mais conserve les tables du plugin.

Automatisation par API

Des outils d'opérateur de confiance peuvent dérouler la configuration et la construction de pages via /webadmin/api lorsque le jeton d'API du CMS possède explicitement les capacités plugin, commerce et contenu.

Cycle de vie du plugin :

GET /webadmin/api/plugins POST /webadmin/api/plugins/install POST /webadmin/api/plugins/webblocks-commerce/enable POST /webadmin/api/plugins/webblocks-commerce/setup POST /webadmin/api/plugins/webblocks-commerce/disable DELETE /webadmin/api/plugins/webblocks-commerce

Ressources commerce :

GET /webadmin/api/commerce/products POST /webadmin/api/commerce/products PATCH /webadmin/api/commerce/products/{product} GET /webadmin/api/commerce/orders GET /webadmin/api/commerce/orders/{order}

Les capacités requises du jeton sont volontairement séparées :

cycle de vie du plugin : plugins.read, plugins.install, plugins.manage, plugins.setup et, seulement si nécessaire, plugins.uninstall
travail sur les produits : commerce.read et commerce.products.write
consultation des commandes : commerce.orders.read
placement en page : content.validate et content.apply

Le flux d'API pour ajouter un bouton d'achat est :

Installe, active et prépare webblocks-commerce.
Crée un produit actif avec POST /webadmin/api/commerce/products.
Lis GET /webadmin/api/block-types ou GET /webadmin/api/content-contract.
Ajoute un bloc webblocks-commerce-buy-button via content validate/apply.
Renseigne settings.commerce_product_id avec l'id de produit renvoyé par l'API Commerce.

Le bloc Commerce Buy Button appartient au plugin. Il est masqué dans la découverte des blocs tant que le plugin est désactivé, et content validate/apply rejette les ids de produit manquants, inconnus ou inactifs. L'API ne collecte pas de données de carte ; les visiteurs terminent toujours le paiement via le flux public Commerce/PayPal.

Configuration de PayPal

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

Références officielles PayPal :

Définis ces variables d'environnement dans l'installation du CMS :

WEBBLOCKS_COMMERCE_GATEWAY=paypal WEBBLOCKS_COMMERCE_PAYPAL_MODE=sandbox WEBBLOCKS_COMMERCE_PAYPAL_CLIENT_ID=your-paypal-client-id WEBBLOCKS_COMMERCE_PAYPAL_CLIENT_SECRET=your-paypal-client-secret WEBBLOCKS_COMMERCE_PAYPAL_WEBHOOK_ID=your-paypal-webhook-id

N'utilise WEBBLOCKS_COMMERCE_PAYPAL_MODE=live qu'après avoir testé le paiement en sandbox et la vérification du webhook.

Configuration du sandbox PayPal

Dans le PayPal Developer Dashboard :

Ouvre Apps & Credentials.
Utilise l'app REST API par défaut ou crée-en une nouvelle.
Copie le client ID et le client secret de sandbox dans l'environnement de l'installation.
Crée ou ouvre les réglages de webhook de l'app.
Ajoute cette URL de webhook :

https://your-site.example/commerce/webhooks/paypal

Abonne-toi au minimum à :

CHECKOUT.ORDER.APPROVED PAYMENT.CAPTURE.COMPLETED

Copie le webhook ID PayPal dans WEBBLOCKS_COMMERCE_PAYPAL_WEBHOOK_ID.
Utilise des comptes acheteur et vendeur du sandbox PayPal pour tester le paiement.

Pour les tunnels HTTPS locaux, utilise l'URL HTTPS du tunnel comme URL de webhook. En production, utilise l'URL HTTPS publique définitive du site.

Diagnostics de disponibilité

Ouvre :

/webadmin/plugins/webblocks-commerce/settings

L'écran de réglages n'affiche volontairement que des diagnostics sans risque :

passerelle active
mode PayPal
client ID configuré ou absent
client secret configuré ou absent
webhook ID configuré ou absent
disponibilité du paiement
disponibilité du webhook
URL de webhook attendue
disponibilité du schéma du plugin

Il ne doit afficher ni client secret PayPal en clair, ni jeton, ni signature de charge utile de webhook, ni identifiant de paiement.

Créer un produit

Ouvre :

/webadmin/plugins/webblocks-commerce/products

Crée un produit avec :

titre
slug
description
statut
montant du prix
devise
quantité en stock (facultatif)
SKU (facultatif)
portée de site (facultatif)

Mets le statut du produit sur Active quand il doit être disponible à l'achat. Les produits en brouillon ou archivés ne déclenchent pas le paiement public.

L'écran de détail du produit affiche son URL d'achat publique :

/commerce/products/{slug}/buy

Ajouter un bouton d'achat à une page

Une fois le plugin activé et prêt, le sélecteur de blocs du constructeur de pages propose un bloc Commerce Buy Button appartenant au plugin.

Déroulé conseillé :

Ouvre la page d'œuvre, de portfolio ou « Works » dans le constructeur de pages.
Ajoute Commerce Buy Button dans le slot voulu.
Sélectionne un produit commerce actif.
Au besoin, change le libellé du bouton, l'alignement et l'affichage du prix.
Publie la page quand le contenu autour est prêt.

Le bloc rend un bouton public qui pointe vers :

/commerce/products/{slug}/buy

L'URL d'achat du produit reste utile comme solution de repli pour des éléments de navigation manuels ou des champs de lien existants.

Ne colle pas d'URL de paiement hébergé PayPal dans le contenu du CMS. Les URL d'approbation PayPal sont générées par commande et ne doivent venir que du démarrage du paiement.

Déroulé du paiement

Quand un visiteur ouvre l'URL d'achat :

La page d'achat vérifie que le plugin est activé, la préparation terminée, le produit actif et la passerelle configurée.
Le visiteur démarre le paiement.
WebBlocks Commerce crée une commande en attente, une ligne de commande et une tentative de paiement en attente.
L'adaptateur PayPal crée un PayPal Order.
Le visiteur est redirigé vers l'approbation PayPal.
Le visiteur revient sur une page signée de succès ou d'annulation.
La page de succès ne marque pas la commande comme payée.
PayPal envoie un webhook vers /commerce/webhooks/paypal.
WebBlocks Commerce vérifie la signature du webhook auprès de PayPal.
Pour CHECKOUT.ORDER.APPROVED, WebBlocks Commerce capture la commande PayPal.
Si la capture aboutit, la commande passe à paid et la tentative de paiement à succeeded.

Les événements de webhook sont stockés par passerelle et par ID d'événement : les livraisons répétées sont donc idempotentes.

Consulter les commandes

Ouvre :

/webadmin/plugins/webblocks-commerce/orders

Dans le MVP, les commandes sont en lecture seule. L'écran de détail d'une commande affiche :

numéro de commande
e-mail du client lorsque PayPal le renvoie
statut de la commande
lignes de commande
tentatives de paiement
références de paiement et de checkout de la passerelle
horodatages

La modification manuelle des statuts, les remboursements, la livraison, les taxes et les flux de préparation sont volontairement reportés.

Liste de vérification en sandbox

Utilise cette liste avant de passer en mode live :

WebBlocks Commerce est installé, activé et prêt.
Commerce Settings indique un schéma prêt.
Commerce Settings indique la passerelle paypal.
Le client ID PayPal est configuré.
Le client secret PayPal est configuré.
Le webhook ID PayPal est configuré.
L'URL du webhook utilise HTTPS et pointe vers /commerce/webhooks/paypal.
Un produit est actif, au prix et dans la devise attendus.
L'URL d'achat du produit s'ouvre publiquement.
Une page contenant un bloc Commerce Buy Button affiche le libellé de produit et le lien d'achat attendus.
Le démarrage du paiement redirige vers PayPal.
Un acheteur sandbox peut approuver le paiement.
Le visiteur revient sur la page signée de succès.
La commande reste en attente avant la confirmation par webhook.
PayPal livre CHECKOUT.ORDER.APPROVED.
Le webhook est vérifié avec succès.
La capture de la commande PayPal aboutit.
La commande du CMS passe à paid.
La tentative de paiement passe à succeeded.
Renvoyer le même webhook ne duplique pas les tentatives de paiement.
Les signatures de webhook invalides sont rejetées et ne marquent aucune commande comme payée.
Aucun secret PayPal n'apparaît dans les écrans d'administration, les pages publiques, les journaux, les captures ou la documentation.

Liste de vérification pour le mode live

Avant de passer à WEBBLOCKS_COMMERCE_PAYPAL_MODE=live :

Vérifie que l'opérateur dispose d'un compte PayPal Business là où PayPal l'exige.
Crée ou sélectionne l'app REST live dans le PayPal Developer Dashboard.
Remplace les client ID, client secret et webhook ID de sandbox par les valeurs live.
Configure l'URL de webhook live avec le domaine HTTPS de production.
Vérifie que le site de production peut recevoir les requêtes publiques de webhook PayPal.
Effectue un paiement live de faible montant si l'opérateur l'accepte.
Consulte la commande dans l'admin du CMS.

Garde séparés les identifiants sandbox et live. Ne réutilise pas un webhook ID de sandbox en mode live.

Dépannage

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

Ouvre Commerce Settings.
Vérifie que la passerelle est paypal.
Vérifie que le client ID et le client secret sont configurés.
Vérifie que le produit est actif et a un prix valide.
Vérifie que les migrations du plugin ont été exécutées.

Si le paiement redirige vers PayPal mais que la commande reste en attente :

Vérifie que l'URL de webhook PayPal est correcte.
Vérifie que WEBBLOCKS_COMMERCE_PAYPAL_WEBHOOK_ID correspond au webhook configuré dans PayPal.
Vérifie que PayPal envoie CHECKOUT.ORDER.APPROVED.
Vérifie que le site est joignable par PayPal en HTTPS.
Vérifie que la vérification de signature du webhook n'échoue pas.

Si un webhook est rejeté :

Vérifie que l'événement provient du mode PayPal correspondant.
Vérifie que des identifiants sandbox ne sont pas mélangés à des webhook ID live.
Vérifie que le webhook ID appartient à la même app REST PayPal que les identifiants client.

Limites actuelles

Le MVP ne comprend pas encore :

panier ou paiement multiproduit
taxes
livraison
codes de réduction
abonnements
remboursements depuis le CMS
comptes clients
réservation de stock
flux de préparation de commande
interface d'activation live PayPal dans le CMS

Ces éléments sont volontairement reportés pour que la première tranche du plugin reste petite, sûre et relisible.