Guida per l'operatore di WebBlocks Commerce

Installa, configura, testa e gestisci il plugin WebBlocks Commerce.

Guida per l'operatore di WebBlocks Commerce

Questa guida spiega come installare, configurare e testare il primo plugin MVP di WebBlocks Commerce. Il plugin attuale supporta il checkout ospitato di un singolo prodotto tramite PayPal. È volutamente ridotto: gestione dei prodotti, gestione degli ordini in sola lettura, diagnostica di prontezza che non espone segreti, URL pubblici di acquisto, un blocco Commerce Buy Button di proprietà del plugin, reindirizzamenti al checkout PayPal e conferma della cattura tramite webhook PayPal.

Il plugin è sviluppato in plugins/webblocks-commerce. Resta un pacchetto di plugin a installazione manuale e non va spostato nel core del CMS.

Flusso utente attuale

Un operatore del CMS installa e abilita WebBlocks Commerce.
L'operatore esegue le migrazioni del plugin dalla schermata di dettaglio del plugin.
L'operatore configura le credenziali PayPal nell'ambiente dell'installazione.
L'operatore apre Commerce Settings per verificare che checkout e webhook siano pronti.
L'operatore crea un prodotto commerce.
La schermata di dettaglio del prodotto mostra un URL pubblico di acquisto.
L'operatore aggiunge un blocco Commerce Buy Button a una pagina e seleziona il prodotto.
Un visitatore avvia il checkout, approva il pagamento in PayPal e torna al sito.
L'ordine resta in sospeso finché il webhook PayPal non verifica e cattura il pagamento.
L'operatore controlla l'ordine pagato in Commerce Orders.

Installare il plugin

Genera lo ZIP del plugin dal repository del CMS:

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

Poi completa il ciclo di vita manuale del plugin:

Apri System -> Plugins.
Carica lo ZIP generato di WebBlocks Commerce.
Controlla la schermata di dettaglio del plugin.
Abilita il plugin.
Esegui setup/migrazioni del plugin se questo segnala Setup required.
Verifica che lo stato passi da «setup required» a «ready».

Il plugin possiede le tabelle webblocks_commerce_*. Disabilitare il plugin rende inerti rotte, menu, impostazioni e comportamenti. Disinstallare un plugin disabilitato caricato manualmente rimuove il pacchetto caricato, ma conserva le tabelle di proprietà del plugin.

Automazione via API

Gli strumenti di operatore fidati possono eseguire il flusso di configurazione e di costruzione delle pagine tramite /webadmin/api quando il token API del CMS ha capacità esplicite di plugin, commerce e contenuti.

Ciclo di vita del 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

Risorse 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}

Le capacità richieste del token sono volutamente separate:

ciclo di vita del plugin: plugins.read, plugins.install, plugins.manage, plugins.setup e, solo se serve, plugins.uninstall
lavoro sui prodotti: commerce.read e commerce.products.write
controllo degli ordini: commerce.orders.read
inserimento in pagina: content.validate e content.apply

Il flusso API per aggiungere un pulsante di acquisto è:

Installa, abilita e prepara webblocks-commerce.
Crea un prodotto attivo con POST /webadmin/api/commerce/products.
Leggi GET /webadmin/api/block-types o GET /webadmin/api/content-contract.
Aggiungi un blocco webblocks-commerce-buy-button tramite content validate/apply.
Imposta settings.commerce_product_id con l'id prodotto restituito dall'API Commerce.

Il blocco Commerce Buy Button è di proprietà del plugin. È nascosto dalla scoperta dei blocchi finché il plugin è disabilitato, e content validate/apply rifiuta id prodotto mancanti, sconosciuti o inattivi. L'API non raccoglie dati di carta; i visitatori completano comunque il pagamento tramite il flusso pubblico Commerce/PayPal.

Configurazione di PayPal

WebBlocks Commerce usa le API REST di PayPal. PayPal documenta che le sue API REST usano token di accesso OAuth 2.0 e che le chiamate API scambiano un client ID e un client secret con un token di accesso. Tieni riservato il client secret e non incollarlo mai nei contenuti del CMS, nelle pagine di documentazione, negli screenshot o nei log di supporto.

Riferimenti ufficiali PayPal:

Imposta queste variabili d'ambiente nell'installazione del 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

Usa WEBBLOCKS_COMMERCE_PAYPAL_MODE=live solo dopo aver testato il checkout in sandbox e la verifica del webhook.

Configurazione del sandbox PayPal

Nel PayPal Developer Dashboard:

Apri Apps & Credentials.
Usa l'app REST API predefinita oppure creane una nuova.
Copia client ID e client secret di sandbox nell'ambiente dell'installazione.
Crea o apri le impostazioni webhook dell'app.
Aggiungi questo URL di webhook:

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

Iscriviti almeno a:

CHECKOUT.ORDER.APPROVED PAYMENT.CAPTURE.COMPLETED

Copia il webhook ID di PayPal in WEBBLOCKS_COMMERCE_PAYPAL_WEBHOOK_ID.
Usa account acquirente e venditore del sandbox PayPal per testare il checkout.

Per i tunnel HTTPS locali, usa l'URL HTTPS del tunnel come URL del webhook. In produzione, usa l'URL HTTPS pubblico definitivo del sito.

Diagnostica di prontezza

Apri:

/webadmin/plugins/webblocks-commerce/settings

La schermata delle impostazioni mostra volutamente solo diagnostiche sicure:

gateway attivo
modalità PayPal
client ID configurato o mancante
client secret configurato o mancante
webhook ID configurato o mancante
prontezza del checkout
prontezza del webhook
URL di webhook atteso
prontezza dello schema del plugin

Non deve mostrare client secret PayPal in chiaro, token, firme dei payload dei webhook o credenziali di pagamento.

Creare un prodotto

Apri:

/webadmin/plugins/webblocks-commerce/products

Crea un prodotto con:

titolo
slug
descrizione
stato
importo del prezzo
valuta
quantità di magazzino (facoltativa)
SKU (facoltativo)
ambito di sito (facoltativo)

Imposta lo stato del prodotto su Active quando deve essere acquistabile. I prodotti in bozza o archiviati non avviano il checkout pubblico.

La schermata di dettaglio del prodotto mostra il suo URL pubblico di acquisto:

/commerce/products/{slug}/buy

Aggiungere un pulsante di acquisto a una pagina

Una volta abilitato il plugin e completata la preparazione, il selettore di blocchi del page builder mostra un blocco Commerce Buy Button di proprietà del plugin.

Flusso consigliato:

Apri nel page builder la pagina dell'opera, del portfolio o «Works».
Aggiungi Commerce Buy Button nello slot desiderato.
Seleziona un prodotto commerce attivo.
Se vuoi, cambia etichetta del pulsante, allineamento e visualizzazione del prezzo.
Pubblica la pagina quando il contenuto circostante è pronto.

Il blocco produce un pulsante pubblico che rimanda a:

/commerce/products/{slug}/buy

L'URL di acquisto del prodotto resta utile come ripiego per voci di navigazione manuali o campi link già esistenti.

Non incollare URL di checkout ospitato PayPal nei contenuti del CMS. Gli URL di approvazione PayPal sono generati per singolo ordine e devono arrivare solo dal flusso di avvio del checkout.

Comportamento del checkout

Quando un visitatore apre l'URL di acquisto:

La pagina di acquisto verifica che il plugin sia abilitato, la preparazione completata, il prodotto attivo e il gateway configurato.
Il visitatore avvia il checkout.
WebBlocks Commerce crea un ordine in sospeso, una riga d'ordine e un tentativo di pagamento in sospeso.
L'adattatore PayPal crea un PayPal Order.
Il visitatore viene reindirizzato all'approvazione PayPal.
Il visitatore torna a una pagina firmata di successo o di annullamento.
La pagina di successo non segna l'ordine come pagato.
PayPal invia un webhook a /commerce/webhooks/paypal.
WebBlocks Commerce verifica con PayPal la firma del webhook.
Per CHECKOUT.ORDER.APPROVED, WebBlocks Commerce cattura l'ordine PayPal.
Se la cattura si completa, l'ordine passa a paid e il tentativo di pagamento a succeeded.

Gli eventi webhook sono memorizzati per gateway e ID evento, così le consegne ripetute sono idempotenti.

Controllare gli ordini

Apri:

/webadmin/plugins/webblocks-commerce/orders

Nell'MVP gli ordini sono in sola lettura. La schermata di dettaglio dell'ordine mostra:

numero d'ordine
email del cliente quando PayPal la restituisce
stato dell'ordine
righe d'ordine
tentativi di pagamento
riferimenti di checkout e pagamento del gateway
marche temporali

Modifica manuale degli stati, rimborsi, spedizioni, imposte e flussi di evasione sono volutamente rimandati.

Lista di verifica in sandbox

Usa questa lista prima di passare alla modalità live:

WebBlocks Commerce è installato, abilitato e pronto.
Commerce Settings mostra lo schema pronto.
Commerce Settings mostra il gateway paypal.
Il client ID PayPal è configurato.
Il client secret PayPal è configurato.
Il webhook ID PayPal è configurato.
L'URL del webhook usa HTTPS e punta a /commerce/webhooks/paypal.
Un prodotto è attivo e ha prezzo e valuta attesi.
L'URL di acquisto del prodotto si apre pubblicamente.
Una pagina con un blocco Commerce Buy Button mostra l'etichetta di prodotto e il link di acquisto attesi.
Avviare il checkout reindirizza a PayPal.
Un acquirente sandbox riesce ad approvare il pagamento.
Il visitatore torna alla pagina firmata di successo.
L'ordine resta in sospeso prima della conferma via webhook.
PayPal consegna CHECKOUT.ORDER.APPROVED.
Il webhook viene verificato correttamente.
La cattura dell'ordine PayPal si completa.
L'ordine nel CMS diventa paid.
Il tentativo di pagamento diventa succeeded.
Rinviare lo stesso webhook non duplica i tentativi di pagamento.
Le firme di webhook non valide vengono rifiutate e non segnano gli ordini come pagati.
Nessun segreto PayPal compare nelle schermate di amministrazione, nelle pagine pubbliche, nei log, negli screenshot o nella documentazione.

Lista di verifica per la modalità live

Prima di passare a WEBBLOCKS_COMMERCE_PAYPAL_MODE=live:

Verifica che l'operatore disponga di un account PayPal Business dove PayPal lo richiede.
Crea o seleziona l'app REST live nel PayPal Developer Dashboard.
Sostituisci client ID, client secret e webhook ID di sandbox con i valori live.
Configura l'URL di webhook live con il dominio HTTPS di produzione.
Verifica che il sito di produzione possa ricevere richieste pubbliche di webhook PayPal.
Esegui un checkout live di importo basso, se accettabile per l'operatore.
Controlla l'ordine nell'admin del CMS.

Tieni separate le credenziali sandbox e live. Non riutilizzare webhook ID di sandbox in modalità live.

Risoluzione dei problemi

Se la pagina di acquisto dice che il checkout non è pronto:

Apri Commerce Settings.
Verifica che il gateway sia paypal.
Verifica che client ID e client secret siano configurati.
Verifica che il prodotto sia attivo e abbia un prezzo valido.
Verifica che le migrazioni del plugin siano state eseguite.

Se il checkout reindirizza a PayPal ma l'ordine resta in sospeso:

Verifica che l'URL di webhook PayPal sia corretto.
Verifica che WEBBLOCKS_COMMERCE_PAYPAL_WEBHOOK_ID corrisponda al webhook configurato in PayPal.
Verifica che PayPal invii CHECKOUT.ORDER.APPROVED.
Verifica che il sito sia raggiungibile da PayPal via HTTPS.
Verifica che la verifica della firma del webhook non stia fallendo.

Se un webhook viene rifiutato:

Controlla che l'evento provenga dalla modalità PayPal corrispondente.
Controlla che le credenziali sandbox non siano mescolate con webhook ID live.
Controlla che il webhook ID appartenga alla stessa app REST PayPal delle credenziali client.

Limitazioni attuali

L'MVP non include ancora:

carrello o checkout multiprodotto
imposte
spedizioni
coupon
abbonamenti
rimborsi dal CMS
account cliente
prenotazione del magazzino
flussi di evasione
interfaccia di onboarding live PayPal dentro il CMS

Sono volutamente rimandati perché la prima fetta del plugin resti piccola, sicura e verificabile.