WebBlocks Commerce Guida per l'operatore

Questa guida spiega come installare, configurare e testare WebBlocks Commerce. Il plug-in supporta un carrello pubblico supportato dalla sessione, la raccolta di clienti e indirizzi di consegna, una modalità di ordine di prova senza pagamento, pagamento ospitato su più righe tramite PayPal o SumUp, amministrazione del prodotto e dell'ordine di sola lettura, impostazioni del provider crittografate di sola scrittura, diagnostica segreta, pagine di prodotto pubbliche e un blocco del pulsante di acquisto commerciale di proprietà del plug-in. I dati della carta di pagamento rimangono sulla superficie di pagamento ospitata del fornitore selezionato.

I proprietari di negozi che desiderano connettersi a SumUp dovrebbero iniziare con l'attività incentrata SumUp Avvio rapido. Questa guida per l'operatore è quella tecnica riferimento per architettura, API, verifica e risoluzione avanzata dei problemi.

Il plugin è sviluppato nel proprio repository, webblocks-commerce-plugin, insieme agli altri plugin del catalogo. Rimane un pacchetto plug-in installato manualmente e non deve essere spostato nel core CMS.

Versione del pacchetto documentato: 0.14.0. WebBlocks CMS ^1.61.0; PHP >=8.3.

PHP ext-intl è richiesto sia sul runtime Web che su CLI per la formattazione della valuta.

1. A L'operatore CMS installa e abilita WebBlocks Commerce.
2. L'operatore esegue le migrazioni dei plugin dalla schermata dei dettagli del plugin.
3. L'operatore seleziona PayPal, SumUp o Test order (no payment) e una valuta predefinita compatibile in Commerce Settings. I veri fornitori richiedono credenziali; I valori dell'ambiente gestito dall'hosting possono invece essere utilizzati come sostituzioni.
4. L'operatore apre Commerce Settings per confermare il checkout e la disponibilità del webhook.
5. L'operatore crea un prodotto commerciale.
6. La schermata dei dettagli del prodotto mostra un URL di acquisto pubblico.
7. L'operatore aggiunge un blocco Commerce Buy Button ad una pagina e seleziona il prodotto.
8. Il blocco aggiunge il prodotto a /plugins/webblocks-commerce/cart; il visitatore aggiorna le quantità e inserisce i dettagli di contatto e di consegna richiesti.
9. In modalità ordine di prova, Commerce registra un ordine in sospeso non pagato e torna direttamente alla pagina di stato dell'ordine senza contattare un fornitore.
10. Con PayPal o SumUp, il visitatore approva il pagamento sulla pagina ospitata del fornitore selezionato e ritorna al sito.
11. Gli ordini del fornitore reale rimangono in sospeso finché un webhook verificato dal fornitore non conferma il pagamento.
12. L'operatore esamina i dettagli relativi a cliente, consegna, articolo, tasse e pagamento in Commerce Orders.

Crea lo ZIP del plugin dal repository dei plugin:

L'artefatto è scritto su build/webblocks-commerce-{version}.zip con il relativo SHA-256 accanto.

Quindi completa il ciclo di vita del plug-in manuale:

1. Apri System -> Plugins.
2. Carica il ZIP WebBlocks Commerce generato.
3. Esamina la schermata dei dettagli del plug-in.
4. Abilita il plugin.
5. Esegui la configurazione/migrazione del plug-in se il plug-in segnala Setup required.
6. Conferma che l'integrità cambia da configurazione richiesta a pronta.

Il plugin possiede le tabelle webblocks_commerce_*. La disabilitazione del plugin rende inerti percorsi, menu, impostazioni e comportamenti. La disinstallazione di un plug-in disabilitato caricato manualmente rimuove il pacchetto caricato, ma conserva le tabelle di proprietà del plug-in.

Gli strumenti dell'operatore attendibili possono eseguire il flusso di lavoro di configurazione e creazione di pagine tramite /webadmin/api quando il token API CMS dispone di funzionalità esplicite di plug-in, commercio e contenuti.

Ciclo di vita del plug-in:

Risorse commerciali:

Le funzionalità del token richieste sono intenzionalmente suddivise:

• ciclo di vita del plugin: plugins.read, plugins.install, plugins.manage, plugins.setup e solo quando necessario plugins.uninstall
• funzionamento del prodotto: commerce.read e commerce.products.write
• revisione dell'ordine: commerce.orders.read
• posizionamento della pagina: content.validate e content.apply

Il flusso API per l'aggiunta di un pulsante Acquista è:

1. Installa, abilita e configura webblocks-commerce.
2. Crea un prodotto attivo con POST /webadmin/api/commerce/products.
3. Leggi GET /webadmin/api/block-types o GET /webadmin/api/content-contract.
4. Aggiungi un blocco webblocks-commerce-buy-button tramite la convalida/applicazione del contenuto.
5. Imposta settings.commerce_product_id sull'ID prodotto restituito dall'API Commerce.

Il blocco Commerce Buy Button è di proprietà del plug-in. È nascosto al rilevamento dei blocchi mentre il plug-in è disabilitato e la convalida/applicazione del contenuto rifiuta gli ID prodotto mancanti, sconosciuti o inattivi. Il suo renderer pubblico pubblica post sul carrello di proprietà del plugin; non è richiesto alcun blocco HTML attendibile. L'API non raccoglie i dati della carta; i visitatori completano il pagamento sul checkout ospitato da PayPal o SumUp configurato.

WebBlocks Commerce utilizza le API REST di PayPal. PayPal documenta che le API REST utilizzano token di accesso OAuth 2.0 e che le chiamate API scambiano un ID client e un segreto client con un token di accesso. Mantieni il client segreto privato e non incollarlo mai nel contenuto CMS, nelle pagine di documenti, negli screenshot o nei registri di supporto.

Oriferimenti PayPal ufficiali:

• Inizia con le API REST PayPal
• Codici valuta e precisione supportati da PayPal
• API webhook PayPal
• Verifica firma webhook

Apri Commerce Settings, seleziona PayPal, seleziona Sandbox e inserisci l'ID client, il segreto client, e l'ID del webhook. I campi sono di sola scrittura: i valori salvati vengono crittografati nella tabella delle impostazioni del plugin e non vengono mai ritrasmessi nel browser. Lasciare un campo vuoto ne preserva il valore corrente; utilizzare la casella di controllo chiara esplicita per rimuoverlo.

Per la configurazione gestita dall'hosting, le seguenti variabili di ambiente rimangono supportate e assumono precedenza sulle impostazioni di amministrazione crittografate:

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

Nella dashboard per sviluppatori PayPal:

1. Aperto Apps & Credentials.
2. Utilizza l'app API REST predefinita o crea una nuova app.
3. Copiare l'ID client sandbox e il segreto client nel modulo Impostazioni commerciali sicure (o nell'ambiente di installazione quando si utilizzano le sostituzioni gestite dall'hosting).
4. Crea o apri le impostazioni del webhook dell'app.
5. Aggiungi questo URL webhook:

1. Iscriviti almeno a:

1. Copia l'ID webhook PayPal nel modulo Impostazioni commercio (o WEBBLOCKS_COMMERCE_PAYPAL_WEBHOOK_ID quando si utilizza un ambiente override).
2. Utilizza gli account acquirente e venditore sandbox PayPal per testare il pagamento.

Per i tunnel HTTPS locali, utilizzare l'URL HTTPS del tunnel come URL del webhook. Per la produzione, utilizzare l'URL del sito HTTPS pubblico finale.

SumUp Hosted Checkout mantiene l'immissione della carta e l'interfaccia utente del portafoglio supportata su una pagina ospitata da SumUp. Il l'integrazione crea il lato server di pagamento e non espone mai la chiave API al browser.

Per un flusso di lavoro del proprietario del negozio schermata per schermata, utilizzare SumUp Avvio rapido. La breve sequenza di installazione è:

1. Crea e seleziona un commerciante sandbox nella dashboard di SumUp Impostazioni sviluppatore → Sandbox.
2. Copia il sandbox ID commerciante mostrato nell'area account della dashboard in alto a sinistra.
3. Crea una chiave API di test segreta in Impostazioni → Per sviluppatori → Toolkit → Chiavi API.
4. Inserisci il gateway, la modalità, la chiave API e il codice commerciante in Impostazioni commerciali e conferma la disponibilità.
5. Testare con la scheda sandbox documentata di SumUp prima di utilizzare le credenziali live.

Oriferimenti ufficiali SumUp:

• Checkout ospitato
• Crea e recupera checkout
• Webhook sullo stato del pagamento
• Chiavi API
• Test dei pagamenti online

In Commerce Settings, seleziona SumUp, seleziona Sandbox e inserisci la chiave API e il codice commerciante. Le credenziali salvate vengono crittografate quando sono inattive e rimangono di sola scrittura. Le distribuzioni gestite dall'hosting possono imposta invece queste variabili di ambiente; hanno la precedenza e costituiscono i campi del modulo corrispondenti sola lettura:

Utilizza la chiave API segreta creata per il commerciante sandbox selezionato; non utilizzare la chiave pubblica di SumUp. Una chiave segreta di prova normalmente inizia con sk_test_. Non incollarlo nei blocchi CMS, nelle impostazioni del sito, screenshot, registri di supporto o chat normale. WebBlocks Commerce invia questa richiamata automaticamente quando crea ciascun checkout:

Per questo adattatore non è richiesta la registrazione manuale del webhook nella dashboard di SumUp. Il pubblico L'endpoint HTTPS deve comunque essere raggiungibile da SumUp e non deve essere bloccato da un firewall, pagina di manutenzione, password HTTP o regola proxy.

SumUp chiama lo return_url configurato con CHECKOUT_STATUS_CHANGED e un ID di pagamento. Quello il carico utile non è accettato come prova del pagamento. WebBlocks Commerce recupera il checkout da SumUp, quindi abbina l'ID, il codice commerciante, il riferimento dell'ordine, l'importo, la valuta, lo stato del terminale, e la transazione andata a buon fine prima di contrassegnare un ordine come pagato. Transizioni di stato non riuscite e scadute rilasciare l'inventario prenotato. I tipi di eventi sconosciuti vengono ignorati in modo sicuro.

Aperto:

La schermata delle impostazioni fornisce campi delle credenziali di sola scrittura e mostra intenzionalmente solo la diagnostica sicura:

• gateway attivo
• valuta predefinita e relativa origine di configurazione
• Modalità PayPal
• Modalità Riepilogo
• ID cliente configurato o mancante
• Segreto client configurato o mancante
• ID webhook configurato o mancante
• disponibilità cassa
• Predisposizione webhook
• URL webhook previsto
• Chiave API SumUp e codice commerciante configurati o mancanti
• Predisposizione dello schema plugin

Non deve visualizzare segreti PayPal grezzi, chiavi API SumUp, token di accesso, firme di payload webhook o credenziali di pagamento. I campi delle credenziali vuoti conservano i valori crittografati esistenti. I controlli di cancellazione espliciti rimuovono i valori memorizzati, mentre i valori gestiti dall'ambiente non possono essere modificati o cancellati dal CMS.

Aperto:

Crea un prodotto con:

• titolo
• slug
• descrizione
• stato
• importo prezzo
• valuta
• quantità di inventario opzionale
• opzionale SKU
• ambito del sito opzionale

Imposta lo stato del prodotto su Active quando dovrebbe essere disponibile per il pagamento. I prodotti bozza e archiviati non avviano il checkout pubblico.

La valuta predefinita viene memorizzata con le altre impostazioni di Commercio e viene utilizzata per i nuovi prodotti. WEBBLOCKS_COMMERCE_DEFAULT_CURRENCY rimane una sostituzione dell'ambiente opzionale; quando presente, il il selettore è di sola lettura. La valuta del prodotto viene selezionata dall'elenco supportato del gateway attivo e l'API del prodotto interno applica la stessa regola.

Il cambio dei gateway viene bloccato se un prodotto non archiviato utilizza una valuta non supportata dalla destinazione porta. I carrelli con valuta mista rimangono rifiutati. Checkout esegue una compatibilità finale del gateway controllare prima di creare un ordine o prenotare l'inventario.

I prezzi sono unità minori intere, ma la precisione delle unità minori è specifica della valuta anziché sempre due cifre. Le visualizzazioni pubblica e amministratore utilizzano le impostazioni internazionali CMS correnti tramite PHP intl NumberFormatter, quindi i simboli e i separatori sono localizzati per EUR, USD, GBP, JPY e ogni valuta selezionabile. Le richieste del gateway utilizzano la stessa precisione. Zero-decimale specifico per PayPal i requisiti per HUF e TWD sono rispettati.

Non esiste alcuna dipendenza Composer aggiuntiva. PHP ext-intl è un requisito della piattaforma e deve essere abilitato sia per il server web che per la CLI. Il risultato sullo stato del plugin avvisa quando non è disponibile. I codici supportati si basano sul funzionario Valuta di riferimento PayPal e SumUp Checkout API enum; paese mercantile e le restrizioni sull'account possono comunque restringere gli elenchi di fornitori.

La schermata dei dettagli del prodotto mostra l'URL di acquisto pubblico del prodotto:

Dopo che il plugin è abilitato e pronto per l'installazione, il selettore di blocchi del generatore di pagine mostra un blocco Commerce Buy Button di proprietà del plugin.

Flusso di lavoro consigliato:

1. Apri la pagina dell'opera d'arte, del portfolio o "Opere" nel generatore di pagine.
2. Aggiungi Commerce Buy Button allo slot desiderato.
3. Seleziona un prodotto commerciale attivo.
4. Opzionalmente è possibile modificare l'etichetta del pulsante, l'allineamento e la visualizzazione del prezzo.
5. Pubblica la pagina quando il contenuto circostante è pronto.

Il blocco esegue il rendering di un modulo pubblico nativo che aggiunge il prodotto selezionato a:

L'URL di acquisto del prodotto rimane utile per i collegamenti ai dettagli del prodotto ed espone un'azione di aggiunta al carrello. Il pagamento viene completato dal carrello, quindi i campi richiesti per il cliente e la consegna non possono essere saltati. Le visualizzazioni del carrello, della pagina del prodotto e dello stato del pagamento estendono tutte il CMS layout pubblico, preservando gli slot di intestazione e piè di pagina del sito attivo.

Non incollare gli URL di pagamento ospitati dal provider nel contenuto CMS. Vengono generati per ordine e dovrebbero provenire solo dal flusso di avvio del pagamento.

Quando un visitatore utilizza un blocco Commerce o una pagina di prodotto:

1. Il plug-in controlla la configurazione, lo stato del prodotto, lo stock tracciato e la valuta del carrello.
2. Il prodotto viene archiviato nel carrello lato server supportato dalla sessione; non vengono raccolti dati di pagamento.
3. Il visitatore fornisce nome, e-mail, indirizzo di consegna e aggiunta facoltativa di telefono/indirizzo.
4. Al momento del pagamento, WebBlocks Commerce blocca i metadati del cliente/consegna, i titoli delle righe localizzate, i prezzi, l'IVA e i totali su un ordine in sospeso e prenota le scorte in modo atomico.
5. Nella modalità ordine di prova, il visitatore ritorna direttamente a una pagina di stato firmata e nessun fornitore di servizi di pagamento viene contattato. Con PayPal o SumUp, l'adattatore attivo crea un checkout ospitato e reindirizza il visitatore.
6. Una pagina di reso firmata può segnalare che l'elaborazione continua, ma non contrassegna mai l'ordine pagato.
7. I webhook PayPal sono verificati con la firma e gli ordini PayPal approvati vengono acquisiti.
8. Le notifiche sullo stato di SumUp attivano un nuovo recupero dell'API di pagamento e una corrispondenza completa dell'ordine/transazione.
9. Solo il risultato del fornitore verificato sposta l'ordine e il tentativo di pagamento su paid/succeeded.

Gli eventi del webhook vengono archiviati dal gateway e dall'ID evento, pertanto il recapito ripetuto è idempotente.

Aperto:

Gli ordini sono di sola lettura. La schermata dei dettagli dell'ordine mostra:

• numero ordine
• nome del cliente, email richiesta, telefono opzionale e indirizzo di consegna acquisiti dal carrello pubblico
• stato dell'ordine
• Articoli pubblicitari
• tentativi di pagamento
• Checkout gateway e riferimenti di pagamento
• timestamp

La modifica manuale dello stato, i rimborsi, il calcolo delle tariffe di spedizione e i flussi di lavoro di evasione vengono rinviati intenzionalmente. Vengono implementati l'acquisizione dell'indirizzo del cliente e della consegna, gli snapshot IVA e la prenotazione dell'inventario.

Seleziona Test order (no payment) in Commerce Settings quando il proprietario di un negozio desidera verificare il completare il modulo del negozio e il flusso di registrazione degli ordini senza contattare PayPal o SumUp. Il pubblico il carrello etichetta chiaramente la modalità, richiede i dettagli del cliente e della consegna, crea un ordine in sospeso, riserva le scorte tracciate, registra un tentativo di pagamento falso in sospeso per la continuità dell'audit e reindirizza a una pagina di conferma firmata in cui si dichiara che non è stato riscosso alcun pagamento. Torna a un configurato vero fornitore prima di accettare gli ordini dei clienti pagati.

Utilizzare questo elenco di controllo prima di passare alla modalità live:

• WebBlocks Commerce è installato, abilitato e pronto per la configurazione.
• Commerce Settings mostra lo schema pronto.
• Commerce Settings mostra il gateway paypal.
• L'ID cliente PayPal è configurato.
• Il segreto client PayPal è configurato.
• L'ID webhook PayPal è configurato.
• L'URL del webhook utilizza HTTPS e punta a /plugins/webblocks-commerce/webhooks/paypal.
• Un prodotto è attivo e ha il prezzo/valuta previsto.
• L'URL di acquisto del prodotto si apre pubblicamente.
• Una pagina con Commerce Buy Button aggiunge il prodotto previsto a /plugins/webblocks-commerce/cart.
• L'avvio del pagamento reindirizza a PayPal.
• Un acquirente sandbox può approvare il pagamento.
• Il visitatore ritorna alla pagina di successo firmata.
• L'ordine rimane in sospeso prima della conferma del webhook.
• PayPal consegna CHECKOUT.ORDER.APPROVED.
• Il webhook viene verificato correttamente.
• L'acquisizione dell'ordine PayPal è stata completata.
• L'ordine CMS diventa paid.
• Il tentativo di pagamento diventa succeeded.
• Il reinvio dello stesso webhook non duplica i tentativi di pagamento.
• Le firme webhook non valide vengono rifiutate e non contrassegnano gli ordini pagati.
• Nessun segreto PayPal viene visualizzato nelle schermate di amministrazione, nelle pagine pubbliche, nei registri, negli screenshot o nei documenti.

• Il commerciante sandbox è selezionato nella dashboard di SumUp.
• L'ID commerciante e la chiave segreta sk_test_ appartengono allo stesso account sandbox.
• Commerce Settings mostra il gateway sumup, la modalità sandbox e il checkout pronto.
• La chiave API di prova e il codice commerciante sandbox sono configurati, ma il valore della chiave non viene visualizzato.
• Un blocco Commercio aggiunge il prodotto EUR attivo a /plugins/webblocks-commerce/cart.
• Quantità, IVA e importo finale sono corretti prima del pagamento.
• L'avvio del checkout crea un ordine in sospeso e reindirizza a checkout.sumup.com.
• Il riferimento al pagamento di SumUp corrisponde al numero dell'ordine CMS.
• Il completamento di un pagamento sandbox produce CHECKOUT_STATUS_CHANGED in /plugins/webblocks-commerce/webhooks/sumup.
• Il gestore recupera il checkout da SumUp e conferma una transazione riuscita.
• L'ordine CMS diventa paid e il relativo tentativo di pagamento diventa succeeded.
• Il reinvio della stessa notifica di pagamento non crea un altro tentativo di pagamento.
• Un codice commerciante, un riferimento, un importo o una valuta non corrispondenti non contrassegnano mai un ordine pagato.
• I check-out SumUp non riusciti o scaduti rilasciano l'inventario prenotato.
• La scheda di prova documentata con successo 4200 0000 0000 0091 viene completata con qualsiasi data di scadenza futura e qualsiasi CVV a tre cifre.

Prima di passare a WEBBLOCKS_COMMERCE_PAYPAL_MODE=live:

• Conferma che l'operatore possiede un conto PayPal Business ove richiesto da PayPal.
• Crea o seleziona l'app REST live nella dashboard per sviluppatori PayPal.
• Sostituisci l'ID client sandbox, il segreto client e l'ID webhook con valori live.
• Configura l'URL del webhook live con il dominio HTTPS di produzione.
• Confermare che il sito di produzione può ricevere richieste webhook PayPal pubbliche.
• Esegui un pagamento in tempo reale di basso valore, se accettabile per l'operatore.
• Rivedi l'ordine nell'amministrazione CMS.

Mantieni sandbox e credenziali live separate. Non riutilizzare gli ID webhook sandbox in modalità live.

Per la modalità live di SumUp, seleziona il conto commerciante reale verificato, crea un sk_live_ separato chiave API segreta, utilizza l'ID commerciante attivo di quell'account, imposta WEBBLOCKS_COMMERCE_SUMUP_MODE=live, aggiornare la configurazione dell'applicazione ed eseguire un pagamento accettabile di basso valore. Non riutilizzare mai o mescolare un commerciante sandbox, una chiave di prova, un commerciante live o una chiave live.

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

• Aperto Commerce Settings.
• Conferma che il gateway selezionato è paypal o sumup.
• Per PayPal, verificare che l'ID cliente e il segreto cliente siano configurati.
• Per SumUp, conferma che la chiave API e il codice commerciante sono configurati.
• Conferma che il prodotto è attivo e ha un prezzo valido.
• Conferma che le migrazioni dei plugin sono state eseguite.

Se il pagamento viene reindirizzato a PayPal ma l'ordine rimane in sospeso:

• Conferma che l'URL del webhook PayPal sia corretto.
• Conferma che WEBBLOCKS_COMMERCE_PAYPAL_WEBHOOK_ID corrisponde al webhook configurato in PayPal.
• Conferma PayPal invia CHECKOUT.ORDER.APPROVED.
• Conferma che il sito è raggiungibile da PayPal tramite HTTPS.
• Confermare che la verifica della firma del webhook non abbia esito negativo.

Se un webhook viene rifiutato:

• Verifica che l'evento webhook provenga dalla modalità PayPal corrispondente.
• Verificare che le credenziali sandbox non siano mescolate con gli ID webhook live.
• Verifica che l'ID webhook appartenga alla stessa app REST PayPal delle credenziali del cliente.

Se un ordine SumUp rimane in sospeso:

• Conferma che l'URL HTTPS pubblico /plugins/webblocks-commerce/webhooks/sumup è raggiungibile.
• Conferma che la chiave API può leggere il checkout e appartiene al codice commerciante configurato.
• Confermare che il riferimento del checkout, l'importo e la valuta corrispondano ancora all'ordine CMS.
• Conferma SumUp riporta PAID e include una transazione SUCCESSFUL.

Ie la pagina ospitata di SumUp segnala un checkout scaduto o mancante, avvia un nuovo checkout dal carrello. Le sessioni di Hosted Checkout scadono dopo circa 30 minuti e i relativi URL non devono essere aggiunti ai segnalibri o riutilizzato.

Il plugin attuale non include ancora:

• spedizione
• coupon
• abbonamenti
• rimborsi da CMS
• conti cliente
• flussi di lavoro di adempimento
• Onboarding dell'account fornitore (le credenziali di pagamento possono essere modificate in Impostazioni commerciali)

Queste funzionalità rimangono separate anziché nascoste all'interno delle integrazioni del provider.

Lo stato dell'ordine viene modificato solo tramite Support\Orders\OrderStateMachine, mai aggiornamento grezzo. Applica il grafico di transizione consentito (pending → paid|failed|cancelled|expired, paid → refunded), è idempotente per i webhook riconsegnati e blocca la riga dell'ordine in modo le richiamate del gateway racing non possono applicare due volte una transizione.

Lo stock tracciato (inventory_quantity non nullo) viene riservato atomicamente all'avvio del pagamento, che impedisce la vendita eccessiva di acquirenti simultanei e viene rilasciato nuovamente nel catalogo quando un l'ordine viene annullato, scade, fallisce o viene rimborsato. Prodotti con inventory_quantity nullo non vengono tracciati (illimitati) e non vengono mai decrementati.

Agli ordini abbandonati pending mantengono la loro prenotazione fino alla scadenza. Corri php artisan webblocks-commerce:expire-stale-orders --minutes=30 su un programma per rilasciare il le scorte detenute dalle casse che l'acquirente non ha mai completato. Collegalo al kernel della console dell'app host, ad esempio $schedule->command('webblocks-commerce:expire-stale-orders')->everyFifteenMinutes();.

Cart sono lato server, persistenti e a valuta singola. Un carrello memorizza solo il prodotto referenze + quantità; i prezzi e l'IVA vengono risolti in tempo reale solo dal catalogo attuale congelato nell'ordine alla cassa (StartCheckout::forCart), che crea un ordine multilinea, riserva lo stock atomicamente per ogni riga e contrassegna il carrello converted. Aggiungendo lo stesso il prodotto unisce le quantità; l'aggiunta di una valuta diversa o di più azioni monitorate viene rifiutata.

I visitatori utilizzano il carrello pubblico supportato dalla sessione senza un token API. Prima del checkout, il modulo pubblico richiede il nome, l'e-mail, la via, il codice postale, la città e il codice paese di due lettere del cliente; telefono e una seconda riga di indirizzo rimangono facoltative. I dettagli vengono memorizzati nei metadati del carrello/ordine e visualizzati nelle schermate dello stato dell'ordine e dei dettagli dell'ordine di amministrazione.

Percorsi pubblici:

• GET /plugins/webblocks-commerce/cart: esamina le righe del carrello, l'IVA e il totale
• POST /plugins/webblocks-commerce/cart/items/{product} — aggiungi un prodotto da un blocco Commercio o acquista una pagina
• PATCH|DELETE /plugins/webblocks-commerce/cart/items/{product} — modifica la quantità o rimuovi una riga
• POST /plugins/webblocks-commerce/cart/checkout: salva i dettagli del cliente/consegna, crea l'ordine e continua al gateway configurato

Le pagine pubbliche del carrello, della pagina di acquisto e dello stato del pagamento estendono il layout pubblico del CMS e visualizzano il gli slot header e footer del sito attorno al loro contenuto, risolti dalla home page da Support\PublicStorefrontShell. Un'intestazione contenuta in un Shared Slot funziona allo stesso modo, quindi modificando il file l'intestazione del sito cambia con essa la vetrina. Il Commerce Buy Button è un blocco plug-in nativo e messaggi nel carrello; non richiede un blocco HTML attendibile.

Tutto ciò che fa il carrello è disponibile tramite l'API interna di proprietà del plug-in — montato nel Gruppo API interno CMS (/webadmin/api, autenticazione bearer-token) tramite l'hook apiRoutes() del plugin, in questo modo gli agenti IA ottengono le stesse funzionalità che il pannello di amministrazione offre agli esseri umani. Endpoint (capacità in parentesi):

• POST /webadmin/api/commerce/cart — crea un carrello (commerce.cart.write)
• GET /webadmin/api/commerce/cart/{token}: leggi un carrello con totali in tempo reale (commerce.cart.read)
• POST /webadmin/api/commerce/cart/{token}/items — aggiungi {product_id, quantity} (commerce.cart.write)
• PATCH /webadmin/api/commerce/cart/{token}/items/{product} — imposta {quantity} (0 rimuove) (commerce.cart.write)
• DELETE /webadmin/api/commerce/cart/{token}/items/{product} — rimuovi una riga (commerce.cart.write)
• DELETE /webadmin/api/commerce/cart/{token}/items — svuota il carrello (commerce.cart.write)
• POST /webadmin/api/commerce/cart/{token}/checkout: avvia il pagamento ospitato, restituisce redirect_url (commerce.cart.write)

Prodotti e ordini vengono esposti allo stesso modo (questi endpoint sono di proprietà del plug-in, non del CMS core e sono presenti solo quando il plugin è abilitato):

• GET|POST /webadmin/api/commerce/products, PATCH /webadmin/api/commerce/products/{id} — catalogo incl. tax_class (commerce.read / commerce.products.write)
• GET /webadmin/api/commerce/orders, GET /webadmin/api/commerce/orders/{id} — di sola lettura, con la suddivisione completa di netto/imposta/lordo (commerce.orders.read)

Tutti questi si autoproclamano: mentre il plugin è abilitato appaiono nella scoperta dell'API CMS (Percorsi GET /webadmin/api _links, GET /webadmin/api/openapi.json e guida all'individuazione) tramite il contributo apiDiscovery() del plugin e scompaiono quando il plugin viene disabilitato.

Non esiste un token commerciale separato: il plug-in utilizza il token API CMS condiviso . Suo Le funzionalità commerce.* vengono fornite al set concedibile del CMS tramite apiCapabilities() (appaiono come gruppo "Commercio" nell'interfaccia utente di amministrazione dei token mentre il plug-in è abilitato), quindi a è possibile limitare l'ambito di un singolo token con privilegi minimi solo alle funzionalità commerciali.

Il contenuto del prodotto Storefront condivide il sistema CMS Site+Locale anziché uno parallelo. Il la riga del prodotto base contiene il valore predefinito/fallback title/description; una riga di traduzione per locale (webblocks_commerce_product_translations, codificato per prodotto + locale CMS) li sovrascrive. Questo è l'asse linguistico content del pannello di amministrazione, distinto dal linguaggio UI del pannello di amministrazione, che rimane nei file Laravel resources/lang.

ProductLocalizer risolve il titolo/descrizione mostrato per una locale, tornando alla base. I carrelli portano un locale, quindi i riepiloghi del carrello e, soprattutto, l'istantanea del titolo della riga dell'ordine su checkout utilizza il testo localizzato che l'acquirente ha effettivamente visto. La pagina di acquisto pubblica viene localizzata tramite a Query ?locale=<code>, tornando alla base.

Modifica traduzioni nel modulo del prodotto amministratore (per locale non predefinito abilitato) o tramite l'API (capacità tra parentesi):

• GET /webadmin/api/commerce/products/{product}/translations — elenco base + traduzioni (commerce.read)
• PUT /webadmin/api/commerce/products/{product}/translations/{locale} — aggiungi {title?, description?} (commerce.products.write)
• DELETE /webadmin/api/commerce/products/{product}/translations/{locale}: rimuovi una lingua (commerce.products.write)