Inizia a vendere con WebBlocks Commerce

Commerce aggiunge al CMS tre parti collegate:

• Prodotti: titoli, descrizioni, prezzi, valute, scorte e una classe fiscale del prodotto.
• Un percorso di acquisto per i visitatori: un blocco nativo Commerce Buy Button, un carrello con controlli della quantità e un modulo di checkout separato per contatti e consegna.
• Ordini e pagamenti: righe d'ordine salvate, dati del cliente e di consegna, totali fiscali e tentativi di pagamento. PayPal e SumUp incassano sulle proprie pagine ospitate; i visitatori non inseriscono dati della carta in un blocco di contenuto CMS.

Continui a usare normali pagine CMS per presentazione del prodotto, fotografie, domande frequenti e navigazione. Il blocco Commerce collega la pagina editoriale a un prodotto reale. Modificare un paragrafo della pagina di vendita non cambia prezzo o scorte: questi si gestiscono in Commerce → Products.

È un buon punto di partenza per un catalogo ridotto o pochi prodotti venduti da pagine esistenti. Non offre un motore di tariffe di spedizione, coupon, un flusso di evasione di magazzino o un pulsante di rimborso nella schermata dell'ordine. Raccogliere un indirizzo non organizza automaticamente la spedizione. Gli abbonamenti ricorrenti usano il plugin separato Memberships con la propria configurazione; non serve per gli ordini singoli di questa guida.

Per nomi degli endpoint, integrazioni per sviluppatori e contratto dettagliato dei pagamenti, tieni a portata la documentazione tecnica Commerce. Questa guida segue le operazioni nel pannello.

Usa un'installazione di prova o un negozio non ancora aperto ai clienti. Cambiare il gateway attivo influisce sul checkout Commerce dell'installazione; non passare un negozio operativo alla modalità di prova mentre i clienti acquistano.

Ti servono:

• Un'installazione funzionante di WebBlocks CMS e un account Super admin per installazione e impostazioni di pagamento.
• Una versione CMS compatibile con la release scelta dal catalogo. Commerce 0.16.0 dichiara CMS ^1.100.0; il catalogo indica anche Laravel 13. Controlla la compatibilità con l'installazione effettiva prima di procedere.
• L'estensione PHP intl sia per il sito sia per la riga di comando. Chiedi all'amministratore dell'hosting di abilitarla se Commerce segnala problemi di formattazione della valuta.
• Un sito nel CMS e il permesso di modificarne e visualizzarne in anteprima una pagina.
• In seguito, un conto esercente PayPal o SumUp adatto, credenziali di prova corrispondenti e un sito HTTPS raggiungibile pubblicamente per le notifiche del fornitore.

Un Site Admin può gestire prodotti e consultare ordini nei siti assegnati. Installazione dei plugin, impostazioni Commerce e credenziali di pagamento spettano a Super admin. Se manca una schermata, fai controllare ruolo e assegnazione del sito; creare un secondo account non è un passaggio di configurazione.

Il plugin è elencato come gratuito nel catalogo WebBlocks. Il conto del fornitore di pagamenti è un servizio separato: installare Commerce non lo crea e non lo collega automaticamente.

1. Accedi al CMS e apri System → Plugins.
2. Seleziona Browse Plugin Catalog e apri WebBlocks Commerce.
3. Leggi il risultato di compatibilità e le note di rilascio. Se viene offerta una release compatibile, seleziona Install from Catalog.
4. Torna ai dettagli del plugin installato. Un nuovo pacchetto parte disabled, così puoi esaminarlo.
5. Seleziona Enable Plugin. Verifica che sia abilitato e controlla il risultato sullo stato di salute.

Le versioni attuali del CMS applicano automaticamente le modifiche al database durante installazione, aggiornamento e attivazione. Migrations Up to Date indica che non servono migrazioni manuali. Se la preparazione del database fallisce, risolvi il problema indicato prima di continuare; attivazioni ripetute non correggono un permesso mancante del database.

L'immagine mostra l'installazione completata. Se l'amministratore fornisce invece uno ZIP di una release attendibile, usa Plugin ZIP → Upload Plugin ZIP sulla stessa schermata, poi esaminalo e abilitalo. Nessuna delle due procedure nel pannello richiede al titolare del negozio un repository sorgente del plugin o un comando di build Composer.

Dopo l'attivazione compare Commerce → Products, Orders, Settings nella barra laterale. Apri Settings per continuare. Lo stato del plugin conferma che il pacchetto può funzionare; la disponibilità dei pagamenti viene verificata separatamente in Commerce Settings.

1. Apri Commerce → Settings → General.
2. Imposta Gateway su Test order (no payment).
3. Per questo esempio scegli EUR in Default Currency.
4. Lascia PayPal Mode e SumUp Mode su Sandbox per i test successivi.
5. Seleziona Save Commerce Settings, poi torna a Overview.

La valuta predefinita è il valore iniziale dei nuovi prodotti. Non converte il prezzo dei prodotti esistenti. Ogni prodotto conserva la propria valuta e tutti gli articoli del carrello devono usare la stessa.

Per l'esercizio contano Schema: Ready e Gateway: Ready. PayPal e SumUp possono mostrare Needs config mentre sono inattivi. Per un ordine senza pagamento non occorrono credenziali del fornitore.

La panoramica può chiamare il gateway di prova fake, il nome interno di Test order (no payment). Registra un ordine non pagato, riserva scorte e non contatta fornitori di pagamento. Non simula un pagamento riuscito e non imposta l'ordine su Paid.

Apri Commerce → Products → New Product. Inserisci i seguenti valori sostituendo Northstar Studio con il tuo sito:

Price Amount usa unità minori intere, non il prezzo di vendita decimale. Per un prodotto da €18.00 inserisci 1800, non 18 o 18.00. Alcune valute hanno un numero diverso di unità minori; non tutte usano i centesimi. Controlla il prezzo formattato dopo il salvataggio.

Lascia Inventory vuoto solo se vuoi deliberatamente scorte non monitorate. Vuoto significa disponibilità illimitata, non esaurito. Per questa guida scegli un sito specifico. Install-wide è un ambito separato per Super admin, diverso dalla selezione del sito corrente.

Seleziona Save Product, poi verifica Active, €18.00, Inventory 24 e Product Available nei dettagli. La schermata offre anche una Public Buy URL. Per un collegamento diretto copia l'URL mostrato dalla tua installazione, non l'indirizzo localhost della schermata.

Se il sito ha altre lingue attive, il modulo offre titoli e descrizioni tradotti. Una traduzione vuota usa il contenuto di base. Tradurre la pagina di vendita CMS e il prodotto Commerce sono attività distinte: controlla entrambe quando aggiungi una lingua al negozio.

Crea una pagina CMS in bozza per il quaderno o prepara un aggiornamento in staging di una pagina di vendita pubblicata. Seleziona lo stesso sito del prodotto. Aggiungi un titolo, una descrizione utile e, se disponibile, una foto del prodotto tramite la normale Media Library e il blocco Image.

Collega quindi la pagina a Commerce:

1. Apri lo slot Main della pagina e seleziona Add Block nella posizione desiderata.
2. Scegli Commerce Buy Button.
3. In Block Fields, scegli Studio notebook da Product.
4. Imposta Button Label su Add to Cart.
5. Scegli allineamento Start e attiva Show price beside the button.
6. Seleziona Save Block e apri Preview della pagina salvata.

Il blocco nativo aggiunge il prodotto selezionato al carrello Commerce. Non servono un blocco Trusted HTML, un modulo di pagamento incollato o uno script del fornitore nel contenuto.

L'anteprima permette di provare la pagina prima della pubblicazione. Il banner di anteprima non rende le azioni del carrello una simulazione priva di effetti. Premere il pulsante modifica comunque il carrello della sessione; completare il checkout crea comunque un ordine. Ecco perché prima abbiamo scelto il gateway senza pagamento.

Per un collegamento permanente al carrello nell'intestazione, aggiungi una voce di navigazione a /plugins/webblocks-commerce/cart, chiamala Cart e scegli l'icona shopping-cart. Commerce può mostrare la quantità del carrello su questa azione con icona. La guida ai menu di navigazione spiega come aggiungere e ordinare la voce.

Nell'anteprima seleziona Add to Cart. Commerce apre il carrello con un quaderno. Premi una volta + per portare la quantità a due.

Conferma nome, quantità e prezzo formattato. Con i prezzi EUR e i dati di esempio con imposte incluse della guida, due quaderni da €18.00 totalizzano €36.00. Puoi ridurre la quantità o eliminare una riga. Aggiungere di nuovo lo stesso prodotto unisce le quantità; prodotti con valuta diversa vengono rifiutati.

Seleziona Go to checkout. Contatti e dati di consegna sono su questa schermata separata. Inserisci dati di prova, per esempio Example customer e customer@example.test, anziché informazioni di clienti reali.

Il modulo richiede nome completo, email, via e numero civico, codice postale, città e codice paese di due lettere come DE. Telefono e seconda riga dell'indirizzo sono facoltativi. Rivedi il totale e seleziona Place test order.

Attualmente il modulo raccoglie dati di consegna anche per un pass a un workshop o un articolo non spedito. Non è un servizio di spedizione: questa versione di Commerce non calcola tariffe e non prenota corrieri. Il testo sulla spedizione nel riepilogo non dimostra che siano stati configurati un costo o un flusso di evasione.

Se tutto riesce appare Test Order Received, con la spiegazione che non è stato riscosso alcun pagamento. Pending è lo stato atteso. Conserva il numero d'ordine per il passo successivo; non occorre condividere il collegamento privato allo stato.

Apri Commerce → Orders, trova il numero della schermata di risultato e aprilo. Controlla:

• Status: Pending, perché è un ordine di prova non pagato.
• Items: Studio notebook, quantità 2, €18.00 ciascuno, totale €36.00.
• Customer e Delivery: le informazioni fittizie inserite.
• Gateway: fake, la modalità senza pagamento.
• Payment Attempts: il tentativo registrato e il relativo stato.
• Dettaglio fiscale: subtotale netto, IVA e totale lordo usati al checkout.

Riapri il prodotto. Inventory dovrebbe ora essere 22: due unità sono state riservate all'inizio del checkout. Aggiungere al carrello non riserva scorte. Sia gli ordini pendenti di fornitori reali sia le prove senza pagamento possono mantenere una riserva.

La schermata dell'ordine è di sola lettura. Non puoi trasformare una prova in ordine pagato modificandone qui lo stato; neppure un ritorno riuscito del browser da PayPal o SumUp dimostra il pagamento. Lo stato reale cambia solo dopo che Commerce verifica la notifica e i dettagli del fornitore.

Prezzi e totali fiscali vengono salvati nell'ordine al checkout. Cambiare successivamente il prezzo del prodotto riguarda gli acquisti futuri e non riscrive gli importi degli ordini esistenti.

Valuta: il fornitore deve supportare la valuta predefinita e quelle dei prodotti esistenti non archiviati. Il cambio di gateway può essere rifiutato se un prodotto usa una valuta non supportata. Correggila o archivia consapevolmente il prodotto; cambiare solo quella predefinita non è una conversione.

Imposte: la classe fiscale del prodotto si combina con le aliquote configurate sul server per il paese fiscale del negozio. Il plugin non seleziona automaticamente una nuova giurisdizione per ogni indirizzo di consegna. Fai confermare la configurazione fiscale all'amministratore prima di accettare ordini.

Le impostazioni rilevanti sono WEBBLOCKS_COMMERCE_TAX_ENABLED, WEBBLOCKS_COMMERCE_PRICES_INCLUDE_TAX e WEBBLOCKS_COMMERCE_TAX_COUNTRY. Con prezzi comprensivi d'imposta, l'IVA viene scorporata dal prezzo; con prezzi esclusi, viene aggiunta. Il test usa un'aliquota standard configurata del 19% e prezzi EUR IVA inclusa: €36.00 contengono €5.75 di IVA e €30.25 netti. Illustra il calcolo di questi dati di esempio, non un'aliquota per ogni negozio.

Scorte: le unità monitorate vengono riservate al checkout e liberate quando l'ordine fallisce, viene annullato, scade o viene rimborsato tramite il ciclo supportato. I prodotti non monitorati non vengono decrementati. Il carrello ricontrolla prezzo e disponibilità prima di creare l'ordine: un carrello salvato non promette prezzo fisso o scorte riservate.

Chiedi all'amministratore di pianificare la pulizia degli ordini abbandonati. Il plugin fornisce:

Per esempio può eseguirlo ogni quindici minuti tramite lo scheduler Laravel dell'applicazione ospitante. Scegli una scadenza adatta al negozio e ai pagamenti: il comando fa scadere tutti gli ordini pendenti più vecchi della soglia, non solo quelli di prova. Libera le scorte impegnate dai checkout abbandonati. Aspettare più a lungo non rende pagati gli ordini di prova.

Usa un sito HTTPS di prova raggiungibile pubblicamente. Il fornitore non può inviare una notifica server all'indirizzo locale 127.0.0.1 delle immagini.

1. Nel PayPal Developer Dashboard apri Apps & Credentials e ottieni client ID e client secret sandbox della tua app. Usa l'app e il conto esercente previsti per il negozio.
2. In Commerce → Settings → General, seleziona PayPal, scegli Sandbox per PayPal Mode, imposta una valuta predefinita supportata e salva.
3. Apri PayPal e inserisci Client ID e Client Secret.
4. Copia la Webhook URL generata dall'installazione. Registrala in PayPal come endpoint HTTPS per la stessa app e modalità, includendo l'evento CHECKOUT.ORDER.APPROVED usato dall'integrazione. Riporta in Commerce la Webhook ID ottenuta.
5. Salva e controlla la disponibilità di checkout e webhook in Overview e nella scheda PayPal.
6. Avvia un nuovo ordine e approvalo con un account acquirente sandbox appropriato. Verifica che diventi Paid dopo la notifica verificata, senza affidarti solo alla pagina di ritorno del browser.

L'endpoint pubblico ha percorso /plugins/webblocks-commerce/webhooks/paypal. Copialo dal pannello per far corrispondere dominio e protocollo all'installazione reale. Client ID, secret e webhook ID devono provenire dalla stessa app e ambiente PayPal.

Le istruzioni REST PayPal spiegano credenziali app e account sandbox; la documentazione Webhooks descrive le sottoscrizioni. Per il flusso nel pannello non devi implementare queste API.

In General scegli un solo gateway attivo per gli ordini. Configurare entrambi i fornitori non aggiunge un selettore per i visitatori al checkout.

1. Prepara un conto esercente SumUp di prova con chiave API e codice esercente corrispondenti. Se non sai dove ottenerli, segui il percorso di connessione SumUp.
2. In Commerce → Settings → General, seleziona SumUp, scegli Sandbox per SumUp Mode, imposta una valuta compatibile e salva.
3. Apri SumUp, inserisci API Key e Merchant Code, quindi salva.
4. Controlla disponibilità e URL webhook generato. Assicurati che il percorso HTTPS pubblico /plugins/webblocks-commerce/webhooks/sumup sia raggiungibile.
5. Avvia un nuovo checkout dal carrello. Commerce crea il checkout ospitato e invia il cliente alla pagina SumUp. Completa lì il test, torna al sito e ispeziona l'ordine salvato.
6. Conferma che diventi Paid solo dopo il recupero e la verifica del risultato del pagamento da parte di Commerce.

Commerce fornisce l'URL di notifica SumUp quando crea ciascun checkout. Non richiede una SumUp Webhook ID separata. Impostare Sandbox non trasforma una chiave reale in una chiave di prova: account, codice e chiave devono appartenere all'ambiente previsto.

La panoramica SumUp sui pagamenti online descrive l'incasso ospitato, mentre la documentazione Checkouts API spiega checkout e notifica al backend. Il CMS usa questo flusso per te; i dati della carta restano sulla superficie ospitata da SumUp.

I campi delle credenziali sono di sola scrittura. Dopo il salvataggio il modulo torna vuoto e indica se il valore è configurato. Un campo vuoto non significa necessariamente che la credenziale sia persa. Lasciarlo vuoto mantiene il valore salvato; usa Clear saved value solo per rimuoverlo deliberatamente.

I valori salvati in Commerce Settings vengono cifrati a riposo. In alternativa, l'amministratore può gestire i corrispondenti valori nell'ambiente del server. Hanno precedenza e appaiono come Managed by environment; il campo sovrascritto è di sola lettura nel pannello. System elenca i nomi delle variabili supportate senza esporne i valori.

Se una sostituzione salvata sembra non avere effetto, controlla l'etichetta dell'origine prima di reinserirla. Coordina i cambiamenti d'ambiente con l'amministratore dell'hosting. Non inserire chiavi o segreti in pagine, blocchi HTML, schermate o messaggi di assistenza.

Le impostazioni di pagamento sono condivise a livello di installazione. Prodotti con ambito sito e permessi Site Admin non creano una configurazione esercente distinta per ciascun sito.

Completa prima l'esercizio senza pagamento, poi svolgi un test separato completo nel sandbox del fornitore scelto. Le schermate mostrano solo l'esercizio senza pagamento e non dimostrano che il conto esercente o le notifiche pubbliche funzionino.

Prima di aprire la pagina di vendita, conferma che:

• Fornitore, modalità, credenziali esercente e configurazione webhook corrispondano.
• Sito e URL di notifica usino il dominio HTTPS pubblico corretto e rimangano raggiungibili.
• Ogni prodotto da vendere sia Active, assegnato al sito giusto, prezzato correttamente e in una valuta supportata.
• Configurazione fiscale e processo reale di consegna/evasione rispettino le promesse della pagina.
• Un pagamento sandbox diventi Paid in Commerce → Orders dopo la verifica del fornitore. Prova anche annullamento ed eventuali errori pertinenti.
• La pulizia degli ordini pendenti sia pianificata e la scadenza sia stata verificata.
• Pagina, navigazione, contatti e versioni linguistiche attive siano stati controllati in anteprima.

Quando passi consapevolmente a pagamenti reali, usa le credenziali live del vero esercente, la modalità corrispondente e la corretta configurazione webhook di produzione. Credenziali o webhook ID sandbox e live non sono intercambiabili. Conferma nuovamente gateway e disponibilità, poi segui il normale controllo e flusso di pubblicazione.

Pubblicare una pagina non configura un conto esercente. Anche cambiare gateway è separato dalla pubblicazione e influisce subito sul checkout.

Usa Draft mentre prepari un prodotto e Active quando può essere acquistato. Archivialo quando vuoi interrompere nuovi acquisti e rivedi pagine o link che continuano a mostrarlo. Le righe storiche mantengono nomi e importi salvati.

Prima di aggiornare il plugin, leggi note e compatibilità della release, crea un backup con la normale procedura e ripeti poi un test di carrello e checkout. Le versioni attuali del CMS applicano le modifiche al database del plugin durante aggiornamento e attivazione.

Disabilitare Commerce rende inattivi percorsi, menu, impostazioni e contributi. In un negozio operativo considera prima visitatori, blocchi Commerce inseriti e notifiche dei fornitori. Disinstallare un pacchetto caricato e disabilitato conserva le tabelle del plugin; non è una pulizia dei dati degli ordini.

Il percorso principale è pronto: prodotto → pagina CMS → carrello → checkout → revisione ordine. Prosegui con la documentazione di riferimento Commerce per automazione e diagnostica avanzata, oppure torna a tutte le guide per il lavoro quotidiano su pagine, contenuti multimediali e team.