VibeFox Cargoson for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni precedenti di PHP.

Account Cargoson (solo per le tariffe in tempo reale): le tariffe in tempo reale usano l'API dei prezzi di trasporto merci di Cargoson. Le richieste di prezzo per il trasporto merci richiedono un abbonamento Cargoson con accesso alle API (piano Advanced o superiore al momento della stesura). La chiave API viene rilasciata dal tuo account Cargoson; se il tuo piano non mostra le impostazioni API, chiedi al supporto Cargoson. I prezzi provengono dai corrieri e dai listini collegati a quell'account. Se usi solo 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. Nel back office vai su Modules > Module Manager e clicca su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, clicca su Configure, oppure trova VibeFox Cargoson più tardi nell'elenco dei moduli e clicca su Configure.

3. Inserisci la tua chiave di licenza VibeFox in License key nel blocco licenza in cima alla pagina Configure e clicca su Activate (vedi Chiave di licenza).

4. 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). Clicca su Save.

All'installazione il modulo crea il corriere Cargoson con il testo dei tempi di consegna Delivery by the cheapest Cargoson carrier. Il corriere è assegnato a tutte le zone e a tutti i gruppi di clienti. Puoi modificare zone, gruppi di clienti, tempi di consegna, logo e limiti di dimensione in Shipping > Carriers. Non impostare lì i prezzi: il prezzo arriva sempre dal modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Cargoson > Configure. Si applicano a tutte le zone del corriere. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Dopo il salvataggio vedi Settings saved. Cached Cargoson prices were cleared. I numeri decimali si possono digitare con il punto o con la virgola. Non viene salvato nulla e la pagina mostra un errore se un campo numerico contiene testo o un numero negativo, se Currency conversion rate è 0, se Minimum weight è maggiore di Maximum weight, se Method title supera i 64 caratteri, se Price currency non è un codice di 3 lettere, o se una riga della tabella dei prezzi ha un codice paese o un prezzo non validi. Se il modulo non riconosce l'unità di peso del negozio, dopo il salvataggio compare un avviso che indica che i pesi dei prodotti sono considerati in chilogrammi; imposta l'unità in International > Localization (Local units).

General

Enable Cargoson: attiva o disattiva il corriere. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.

Method title: il nome del corriere mostrato nel carrello e al checkout. Predefinito: Cargoson. Obbligatorio. È anche il nome del corriere in Shipping > Carriers.

Shipping cost: come viene calcolato il prezzo.

Il motivo di un prezzo in tempo reale mancante viene scritto nel log del modulo. Non viene mai mostrato al cliente.

API di Cargoson (necessaria solo per le tariffe in tempo reale)

API key: la chiave API del tuo account Cargoson. Viene inviata solo a Cargoson e non viene mai mostrata ai clienti né scritta nel log. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per cambiarla.

Remove the saved API key: compare quando una chiave è salvata. Attivala e salva per eliminare la chiave.

Carrier: quali prezzi vengono usati. Il cliente vede una sola tariffa.

Package type code: il codice del tipo di imballo 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 di imballo 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 di 3 lettere. Predefinito: EUR. L'API restituisce importi senza codice valuta.

Currency conversion rate: serve solo se la valuta dei prezzi è diversa dalla valuta predefinita del negozio: 1 unità della valuta Cargoson = X unità della valuta predefinita del negozio. Lascialo vuoto per rifiutare questi prezzi, così un cliente non paga mai nella valuta sbagliata.

Spedizione da (indirizzo di ritiro) (usato per le tariffe in tempo reale)

Collection country: il paese da cui spedisci. Per impostazione predefinita è il paese del negozio.

Collection postcode: il CAP da cui spedisci. Cargoson lo richiede. Se è vuoto e il paese di ritiro è il paese del negozio, viene usato il CAP del negozio in Shop Parameters > Contact > Stores.

La data di ritiro inviata a Cargoson è oggi nel fuso orario del negozio, oppure il lunedì successivo nel fine settimana.

Prezzi fissi (usati quando Shipping cost è Fixed prices, e come alternativa per le tariffe in tempo reale)

Price per country and size: una tabella con una colonna Country (codice di 2 lettere), una colonna Price e prezzi in base al peso del carrello nella valuta predefinita del negozio, IVA esclusa: 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 di dimensione vuoto o pari a 0 usa la colonna Price; un Price vuoto significa che per quella dimensione non c'è una tariffa fissa. Clicca su Add country per aggiungere una riga e sull'icona del cestino per rimuoverla. Usa * come codice paese per tutti i paesi senza una riga propria. I paesi senza riga (quando non c'è una riga *) non ricevono una tariffa fissa, quindi il corriere viene nascosto per loro. I prezzi devono essere numeri uguali o superiori a 0. Una riga vuota viene ignorata.

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 sono sempre per spedizione.

Condizioni

Minimum weight: nasconde il corriere sotto questo peso del carrello, in kg. 0 significa nessun limite.

Maximum weight: nasconde il corriere sopra questo peso del carrello, in kg. Predefinito: 25. 0 significa nessun limite.

Minimum order amount: mostra il corriere solo quando il subtotale del carrello (dopo gli sconti, prima delle tasse) raggiunge almeno questo importo. Lascialo vuoto per mostrarlo sempre.

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) a partire dal quale la spedizione è gratuita. Viene usato solo quando Free shipping è attivo.

Tax: la regola fiscale del corriere, oppure No tax. I prezzi di trasporto in Cargoson sono di solito al netto (senza IVA). Scegli No tax se i tuoi prezzi includono già le tasse.

Disponibilità senza zone di spedizione

Normalmente il corriere viene offerto nelle zone assegnate in Shipping > Carriers.

Ignore shipping zones: offre Cargoson per i paesi indicati sotto, indipendentemente dalle zone assegnate al corriere. Quando lo attivi e salvi, il corriere viene assegnato a tutte le zone; anche le zone create in seguito vengono assegnate. Quando lo disattivi e salvi, il corriere riottiene le sue zone precedenti.

Countries: i paesi di destinazione per quella modalità. Lascialo vuoto per usare tutti i paesi verso cui spedisci (paesi attivi). Questo campo viene usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: registra ogni calcolo di tariffa in logs/vfd_cgs_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori API e i prezzi rifiutati vengono sempre registrati, anche con questa opzione disattivata. La chiave API e il CAP del cliente non vengono mai registrati.

Log: mostra la dimensione e le ultime voci del log. Clicca su Clear log per svuotarlo.

Remove data on uninstall: se attiva, disinstallando il modulo vengono eliminate le impostazioni Cargoson, il corriere, i prezzi in cache, le quotazioni degli ordini e i log. Se disattiva, tutto viene conservato per una reinstallazione.

Come funziona al checkout

Nel passaggio della spedizione PrestaShop chiede al modulo il prezzo Cargoson. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nell'importo dell'ordine. I pesi dei prodotti vengono convertiti dall'unità del negozio in chilogrammi. Il modulo controlla prima le condizioni: paese di consegna, peso del carrello e importo minimo dell'ordine. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata alcuna richiesta a Cargoson.

In modalità prezzi fissi il prezzo viene preso dalla tabella. Nelle modalità in tempo reale il modulo 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 del tipo di imballo e il peso totale del carrello (almeno 0,1 kg). Un prezzo in tempo reale viene richiesto solo se l'indirizzo di consegna ha un CAP. Cargoson restituisce i prezzi dei tuoi corrieri; il modulo sceglie il più economico (quello del corriere selezionato, se impostato) e, se serve, lo converte nella valuta predefinita del negozio. Il prezzo viene calcolato nella valuta predefinita e poi mostrato nella valuta del carrello del cliente.

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 aspetta Cargoson a ogni aggiornamento. Il timeout delle API è di 10 secondi. Se Cargoson restituisce un errore, nessun prezzo per la tratta o un prezzo in un'altra valuta senza tasso di conversione, il cliente non vede alcun errore. Il corriere viene nascosto, oppure in modalità di ripiego si usa il prezzo fisso.

Se modifichi il corriere in Shipping > Carriers dopo che ha ricevuto ordini, PrestaShop lo salva come una nuova versione del corriere. Il modulo segue automaticamente la nuova versione.

Il modulo calcola solo le tariffe. Non crea spedizioni o prenotazioni in Cargoson, non stampa etichette né traccia i pacchi, e i clienti non possono scegliere un armadietto automatico o 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ù basso, non un elenco di corrieri.

Ordini

La pagina di un ordine Cargoson mostra un blocco Cargoson shipping con la tariffa calcolata al checkout:

Carrier, Service e Cargoson service ID: il corriere e il servizio Cargoson quotati, mostrati quando è stato usato un prezzo in tempo reale.

Price source: Cargoson live price, Fixed price oppure Free shipping threshold.

Calculated price (excl. tax): il prezzo nella valuta predefinita del negozio.

La quotazione viene salvata quando l'ordine viene effettuato e non cambia in seguito. Prenota la spedizione in Cargoson o con le sue integrazioni.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Cargoson è il primo blocco di Modules > Module Manager > VibeFox Cargoson > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopo, il blocco mostra la chiave mascherata, lo stato (ad esempio la data fino alla quale la licenza è attiva e il tuo dominio) e i pulsanti Check now per controllare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuovere la chiave da questo negozio. Sotto ci sono la riga Product: presta-shipping-cargoson e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo i dipendenti con l'autorizzazione di configurazione del modulo possono cambiare la chiave. I testi del blocco seguono la lingua del back office (sono inclusi inglese e russo).

Se la chiave non viene accettata, il blocco indica il motivo, ad esempio Key not found, This key belongs to another product, Domain limit reached o License expired on seguito da una data. Dopo un cambio dell'indirizzo del negozio, o dopo aver liberato uno slot di dominio nel tuo account, clicca su Check now. Se il server delle licenze non è raggiungibile, il modulo continua a funzionare con l'ultimo stato noto.

Una chiave funziona su un solo dominio: il dominio del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, il corriere Cargoson non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Lo storefront di PrestaShop non sa che sei connesso al back office, quindi il corriere viene nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non puoi testarlo al checkout. Un promemoria compare in Modules > Module Manager nella scheda Alerts. Gli ordini esistenti non vengono influenzati.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene ricontrollato automaticamente mentre lavori nel back office: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta a settimana. Non serve alcun cron job. Disinstallare o ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Cargoson non compare al checkout: verifica che la licenza sia attiva e che Enable Cargoson sia attivo. In Shipping > Carriers verifica che il corriere copra la zona del paese del cliente e il gruppo del cliente (oppure che Ignore shipping zones sia attivo e il paese sia in Countries). Controlla i limiti di peso e Minimum order amount. In modalità prezzi fissi verifica che il paese o * abbia un prezzo per la dimensione del carrello. I prodotti possono anche essere limitati a determinati corrieri nella pagina del prodotto.

I prezzi in tempo reale non compaiono: controlla il campo Log nella pagina del modulo. Gli errori API vengono sempre registrati; attiva Debug log per vedere ogni calcolo. Cause tipiche: nessun CAP di consegna inserito, nessun CAP di ritiro, chiave API rifiutata (chiave errata o scaduta, oppure nessun accesso alle API nel tuo piano Cargoson), nessun corriere per la tratta o 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 tu risolvi il problema.

Cargoson rifiuta il tipo di imballo: usa il codice di imballo 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.

L'IVA sulla spedizione viene applicata due volte: i tuoi prezzi Cargoson includono già l'IVA. Imposta Tax su No tax.

Le tariffe sembrano obsolete dopo una modifica: clicca su Save nella pagina del modulo. Così si cancellano i prezzi Cargoson in cache.

La pagina dice che il corriere Cargoson non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Ripristina il modulo in Modules > Module Manager per ricrearlo.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Cargoson e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. I prezzi in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini conservano la cronologia) e vengono rimosse le impostazioni, le quotazioni degli ordini e il log. Se è disattivo, il corriere viene solo disattivato, le impostazioni e le quotazioni degli ordini effettuati vengono conservate, e vengono rimosse solo le quotazioni dei carrelli senza ordine. Reinstallando il modulo, il corriere salvato riprende lo stato precedente, quindi Reset non riattiva un corriere che avevi disattivato.

Cargoson è un marchio registrato del suo titolare. Questo modulo non è affiliato a Cargoson né approvato da Cargoson.