VibeFox Cargoson for WooCommerce — Guida
Requisiti
WordPress: 5.8 o successivo.
WooCommerce: 5.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.
PHP: 8.0 o successivo.
Account Cargoson (solo per le tariffe in tempo reale): le tariffe in tempo reale usano l'API delle tariffe di trasporto di Cargoson. Le richieste di tariffe di trasporto richiedono un abbonamento Cargoson con accesso alle API (piano Advanced o superiore al momento della stesura). La chiave API viene rilasciata nel tuo account Cargoson; se il tuo piano non mostra le impostazioni API, chiedi al supporto Cargoson. Le tariffe provengono dai corrieri e dai listini collegati a quell'account. Se usi solo i prezzi fissi, non ti serve un account Cargoson.
Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un solo dominio.
Installazione
1. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e fai clic su Install Now. Puoi anche caricare la cartella vfd_cargoson in /wp-content/plugins/ via FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox Cargoson, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugins.
4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.
5. Scegli come viene calcolato il costo di spedizione e compila le sezioni corrispondenti: i prezzi fissi e, per le tariffe in tempo reale, la chiave API e il CAP di ritiro (vedi Configurazione).
6. Aggiungi VibeFox Cargoson a una zona di spedizione in WooCommerce > Settings > Shipping > Shipping zones, oppure attiva Ignore shipping zones e scegli i paesi.
Configurazione
Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox Cargoson. Valgono per tutte le zone di spedizione. Quando aggiungi il metodo a una zona, la finestra della zona ha un solo campo:
Title (zone): il nome mostrato al cliente per questa zona. Lascialo vuoto per usare il Method title globale.
Ogni volta che salvi le impostazioni, le tariffe Cargoson in cache vengono cancellate. I numeri decimali si possono scrivere con il punto o con la virgola.
General
Enable/Disable: attiva o disattiva il metodo in tutte le zone contemporaneamente.
Method title: il nome del metodo di spedizione mostrato nel carrello e al checkout. Predefinito: Cargoson. Una zona può sostituirlo.
Shipping cost: come viene calcolato il prezzo.
Il motivo di un prezzo in tempo reale mancante viene scritto nel log di WooCommerce. Non viene mai mostrato al cliente.
Cargoson API (richiesta solo per le tariffe in tempo reale)
API key: la chiave API del tuo account Cargoson. Viene inviata solo a cargoson.com e non viene mai mostrata ai clienti né scritta nel log.
Carrier: quali prezzi vengono usati. Il cliente vede una sola tariffa.
Package type code: il tipo di pacco Cargoson inviato con la richiesta di prezzo. Predefinito: CLL. Gli esempi dell'API Cargoson usano EUR (pallet EUR) e FIN (pallet FIN). Per i pacchi usa il codice pacco del tuo account Cargoson. L'ordine viene inviato come un unico pacco con il peso totale del carrello.
Price currency: la valuta dei prezzi nel tuo account Cargoson, come codice a 3 lettere. Predefinito: EUR. L'API restituisce importi senza codice valuta.
Currency conversion rate: serve solo se la valuta dei prezzi è diversa dalla valuta del negozio: 1 unità della valuta Cargoson = X unità della valuta del negozio. Lascialo vuoto per rifiutare tali prezzi, così un cliente non paga mai nella valuta sbagliata.
Ship from (collection address) (usato per le tariffe in tempo reale)
Collection country: il paese da cui spedisci. Per impostazione predefinita è il paese del tuo negozio.
Collection postcode: il CAP da cui spedisci. Cargoson lo richiede. Se è vuoto e il paese di ritiro è quello del negozio, viene usato il CAP del negozio impostato in WooCommerce > Settings > General.
La data di ritiro inviata a Cargoson è oggi, oppure il lunedì successivo se è un fine settimana.
Fixed prices (usati quando Shipping cost è Fixed prices, e come alternativa per le tariffe in tempo reale)
Price per country and size: una tabella di paesi con una colonna Price e prezzi per peso del carrello nella valuta del negozio: XS fino a 1 kg, S fino a 2 kg, M fino a 3 kg, L fino a 5 kg, XL oltre 5 kg. Un prezzo per taglia vuoto o 0 usa la colonna Price; una colonna Price vuota significa che per quella taglia non c'è una tariffa fissa. Fai clic su Add country per aggiungere una riga e sulla croce per rimuoverne una. La riga * Default si applica a tutti i paesi senza una riga propria. I paesi senza riga (quando non c'è una riga *) non hanno una tariffa fissa, quindi per loro il metodo viene nascosto.
Fixed price applies: Per order addebita il prezzo una sola volta. Per item (price × quantity) lo moltiplica per il numero di articoli nel carrello. Le tariffe Cargoson in tempo reale si applicano sempre per spedizione.
Conditions
Minimum weight (kg): nasconde il metodo sotto questo peso del carrello. 0 significa nessun limite.
Maximum weight (kg): nasconde il metodo sopra questo peso del carrello. Predefinito: 25. 0 significa nessun limite.
Minimum order amount: mostra il metodo solo quando il subtotale del carrello (dopo gli sconti, prima delle tasse) è almeno questo importo. Lascialo vuoto per mostrarlo sempre.
Excluded shipping classes: nasconde il metodo se il carrello contiene un prodotto appartenente a una di queste classi di spedizione di WooCommerce.
Free shipping: attiva la spedizione gratuita quando viene raggiunto l'importo d'ordine indicato sotto.
Free shipping from: il subtotale del carrello (dopo gli sconti, prima delle tasse) da cui la spedizione è gratuita. Viene usato solo quando Free shipping è attivo.
Tax status: Taxable aggiunge l'IVA sulla spedizione secondo le impostazioni fiscali di WooCommerce, None non la aggiunge. Le tariffe dei corrieri in Cargoson sono di solito al netto dell'IVA. Scegli None se i tuoi prezzi includono già le tasse.
Availability without shipping zones
Ignore shipping zones: offre Cargoson per i paesi indicati sotto anche se non è aggiunto a una zona di spedizione.
Countries: i paesi di destinazione per questa modalità. Lascialo vuoto per usare tutti i paesi in cui spedisci. Questo campo viene usato solo quando Ignore shipping zones è attivo.
Advanced
Debug log: registra ogni calcolo di tariffa in WooCommerce > Status > Logs, origine vfd_cargoson. Gli errori delle API vengono sempre registrati, anche quando questa opzione è disattivata. La chiave API e il CAP del cliente non vengono mai registrati.
Remove data on uninstall: se attivo, eliminando il plugin vengono rimosse tutte le impostazioni Cargoson, i metodi di zona e le tariffe in cache. La disattivazione del plugin non elimina mai nulla.
Come funziona al checkout
Quando il cliente inserisce un indirizzo di consegna, WooCommerce chiede al plugin una tariffa. Il plugin controlla prima le condizioni: paese di consegna, peso del carrello, importo minimo dell'ordine e classi di spedizione escluse. Se si applica la spedizione gratuita, il cliente ottiene una tariffa gratuita e non viene inviata alcuna richiesta a Cargoson.
In modalità prezzi fissi, il prezzo viene preso dalla tabella. Nelle modalità in tempo reale, il plugin invia a Cargoson la data di ritiro, il paese e il CAP di ritiro, il paese e il CAP di consegna, e un pacco con il codice tipo pacco e il peso totale del carrello (almeno 0,1 kg). I pesi dei prodotti vengono convertiti dall'unità del negozio in chilogrammi. Una tariffa in tempo reale viene richiesta solo dopo che il cliente ha inserito un CAP. Cargoson restituisce i prezzi dei tuoi corrieri; il plugin sceglie il più economico (tra il corriere selezionato, se impostato) e, se necessario, lo converte nella valuta del negozio.
Ogni risposta viene memorizzata nella cache per 1 ora, così lo stesso carrello non genera una nuova richiesta. Una richiesta non riuscita viene memorizzata nella cache per 10 minuti, così il checkout non attende Cargoson a ogni aggiornamento. Il timeout delle API è di 10 secondi. Se Cargoson restituisce un errore, nessun prezzo per la tratta, oppure un prezzo in un'altra valuta senza un tasso di conversione, il cliente non vede alcun errore. Il metodo viene nascosto oppure, nella modalità di ripiego, viene usato il prezzo fisso.
Il metodo funziona con il checkout classico e con i blocchi Carrello e Checkout. È compatibile con WooCommerce High-Performance Order Storage (HPOS).
Il plugin calcola solo le tariffe. Non crea spedizioni o prenotazioni in Cargoson, non stampa etichette e non traccia i pacchi, e i clienti non possono scegliere un armadietto automatico né un punto di ritiro. Il carrello viene quotato come un unico pacco con il peso totale; le dimensioni del pacco non vengono inviate. Viene mostrato solo il prezzo più economico, non un elenco di corrieri.
Ordini
Quando si usa una tariffa in tempo reale, la riga di spedizione dell'ordine salva il Carrier, il Service e il Cargoson service ID proposti. Sono mostrati nella schermata di modifica dell'ordine, così sai cosa prenotare in Cargoson. Prenota la spedizione in Cargoson o con le sue integrazioni.
Chiave di licenza
Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Shipping > VibeFox Cargoson. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, per esempio la data fino alla quale la licenza è attiva, e il tuo dominio. Usa Check now per controllare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuoverla da questo sito. Il link Manage licenses and domains in your account apre il tuo account vibefox.net.
Una chiave funziona su un solo dominio. Rimuovere la chiave da un sito non libera il suo slot di dominio. Libera lo slot nel tuo account vibefox.net.
Senza una chiave attiva, Cargoson non viene mostrato ai clienti al checkout. I gestori del negozio che hanno effettuato l'accesso lo vedono ancora, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugins e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati.
Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene controllato di nuovo automaticamente in background.
Risoluzione dei problemi
Cargoson non compare al checkout: controlla che la licenza sia attiva, che Enable/Disable sia attivo e che il metodo sia aggiunto alla zona del paese del cliente (oppure che Ignore shipping zones sia attivo e il paese sia consentito). Controlla i limiti di peso, Minimum order amount e Excluded shipping classes. In modalità prezzi fissi, verifica che il paese o * Default abbia un prezzo per la dimensione del carrello.
Le tariffe in tempo reale non compaiono: apri WooCommerce > Status > Logs, origine vfd_cargoson. Gli errori delle API vengono sempre registrati; attiva Debug log per vedere ogni calcolo. Cause tipiche: non è ancora stato inserito un CAP di consegna, manca il CAP di ritiro, la chiave API è stata rifiutata (chiave errata o scaduta, oppure nessun accesso API nel tuo piano Cargoson), nessun corriere per la tratta o per il peso, oppure un prezzo in un'altra valuta. Con Cargoson live prices, fixed prices if the API fails i clienti ricevono comunque il prezzo fisso mentre risolvi il problema.
Cargoson rifiuta il tipo di pacco: usa il codice pacco che il tuo account Cargoson utilizza in Package type code. Il motivo compare nel log.
Un prezzo in un'altra valuta viene rifiutato: imposta Price currency sulla valuta dei tuoi prezzi Cargoson e inserisci il Currency conversion rate.
Le tariffe sembrano obsolete dopo una modifica: salva la pagina delle impostazioni. Così si cancellano le tariffe Cargoson in cache.
Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera uno slot nel tuo account vibefox.net e fai clic su Check now. Se l'indirizzo del sito è cambiato, fai clic su Check now per attivare la chiave per il nuovo dominio. Se il server delle licenze non è raggiungibile, il plugin continua a funzionare con l'ultimo stato noto.
Disinstallazione
Disattivare il plugin conserva tutti i dati. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi. Impostazioni, metodi di zona e tariffe in cache vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano per una reinstallazione successiva. Gli ordini esistenti conservano le loro righe di spedizione.
Cargoson è un marchio del rispettivo proprietario. Questo plugin non è affiliato a Cargoson né approvato da Cargoson.