VibeFox Cargoson for OpenCart — Guida

Requisiti

OpenCart: 3.0.x (testato su 3.0.5.0) o 4.0.2 e successive (testato su 4.1.0.3).

PHP: 8.0 o successivo.

Account Cargoson (solo per i prezzi in tempo reale): i prezzi in tempo reale usano l'API dei prezzi di trasporto merci di Cargoson. Le richieste di prezzo del trasporto richiedono un abbonamento Cargoson con accesso all'API (piano Advanced o superiore al momento della stesura). La chiave API viene rilasciata nel tuo account Cargoson; chiedi al supporto Cargoson se il tuo piano non mostra le impostazioni API. I prezzi provengono dai vettori e dai listini collegati a quell'account. Se usi solo prezzi fissi, non ti serve un account Cargoson.

Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un solo dominio.

Installazione

Il download è un unico file zip con i pacchetti per entrambe le versioni di OpenCart. Decomprimilo sul tuo computer. Contiene README.txt, il pacchetto per OpenCart 3 vfd_cargoson-oc3-(versione).ocmod.zip e il pacchetto per OpenCart 4 vfd_cargoson.ocmod.zip. Installa solo il pacchetto della tua versione di OpenCart. La chiave di licenza è la stessa per entrambe le versioni.

OpenCart 3

1. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_cargoson-oc3-(versione).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non devi aggiornare Extensions > Modifications. Invece dell'Installer puoi copiare il contenuto della cartella upload di questo pacchetto nella cartella principale del tuo negozio.

2. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox Cargoson e clicca su Install (il pulsante verde +).

3. Clicca su Edit (il pulsante a forma di matita) per aprire la pagina delle impostazioni.

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

5. Scegli come viene calcolato il costo di spedizione e compila le sezioni corrispondenti: i prezzi fissi e, per i prezzi in tempo reale, la chiave API e il CAP di ritiro (vedi Configurazione). Attiva Enable Cargoson e clicca su Save.

OpenCart 4

1. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_cargoson.ocmod.zip. Non rinominare il file: OpenCart 4 ricava il codice dell'estensione dal nome del file, e un pacchetto rinominato non funziona.

2. Il pacchetto compare nell'elenco delle estensioni installate nella stessa pagina. Clicca su Install (il pulsante verde +) accanto ad esso.

3. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox Cargoson, clicca su Install (il pulsante verde +), poi su Edit (il pulsante a forma di matita).

4. Inserisci la chiave di licenza e le impostazioni come nei passaggi 4 e 5 per OpenCart 3. La pagina delle impostazioni e i suoi campi sono gli stessi in entrambe le versioni.

Dopo l'installazione il metodo resta disattivato finché non attivi Enable Cargoson e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono usate di nuovo le impostazioni Cargoson che avevi conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox Cargoson > Edit. Le sezioni sono elencate a sinistra. Un unico pulsante Save in fondo salva l'intera pagina senza ricaricarla. Dopo il salvataggio vedi Settings saved. Cached Cargoson prices were cleared. I numeri decimali possono essere digitati con un punto o una virgola. Non viene salvato nulla e la pagina elenca gli errori se Method title è vuoto o supera 64 caratteri, se un campo numerico contiene testo o un numero negativo, se Currency conversion rate è 0, se Minimum weight (kg) è maggiore di Maximum weight (kg), se Price currency non è un codice di 3 lettere, se una riga della tabella prezzi ha un paese o un prezzo non validi, oppure se Sort order non è un numero intero. Se l'unità di peso del negozio non è nota all'estensione, un avviso dopo il salvataggio segnala che i pesi dei prodotti vengono considerati in chilogrammi; aggiungi una classe di peso con unità kg in System > Localisation > Weight Classes. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.

Generali

Il cliente vede un'unica tariffa Cargoson. Puoi limitare il metodo a una zona geografica o a paesi in Availability.

Enable Cargoson: mostra o nasconde Cargoson al checkout. Predefinito: disattivato.

Method title: il nome del metodo di spedizione mostrato al cliente nel carrello e al checkout, massimo 64 caratteri. Predefinito: Cargoson. Obbligatorio.

Shipping cost: come viene calcolato il prezzo.

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

Sort order: la posizione di Cargoson tra i metodi di spedizione al checkout. Un numero intero.

API Cargoson (richiesta solo per i prezzi 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 modificarla.

Remove the saved API key: attivalo e salva per eliminare la chiave salvata.

Carrier: quali prezzi vengono usati. Il cliente vede un'unica tariffa.

Package type code: il tipo di pacco di Cargoson inviato con la richiesta di prezzo. Predefinito: CLL. Gli esempi dell'API Cargoson usano EUR (bancale EUR) e FIN (bancale 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 di 3 lettere. Predefinito: EUR. L'API restituisce importi senza codice di valuta.

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

Spedizione da (indirizzo di ritiro) (per i prezzi in tempo reale)

Collection country: il paese da cui spedisci. La prima opzione, Store country, usa il paese del tuo negozio.

Collection postcode: il CAP da cui spedisci. Cargoson lo richiede per i prezzi in tempo reale. L'indirizzo del negozio in OpenCart è testo libero, quindi il CAP non viene mai ricavato da lì: inseriscilo qui.

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

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

Price per country and size: un elenco di righe con un Country, un Price e prezzi in base al peso del carrello, nella valuta predefinita del negozio e senza tasse: 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 taglia vuoto o pari a 0 usa la colonna Price; un Price vuoto significa che non c'è una tariffa fissa per quella taglia. Clicca su Add country per aggiungere una riga. Scegli * All other countries per i prezzi validi per ogni paese senza una riga propria. I paesi senza riga (quando non esiste una riga *) non hanno una tariffa fissa, quindi il metodo viene nascosto per loro. I prezzi devono essere numeri maggiori o uguali a 0. Una riga vuota viene ignorata.

Fixed price applies: Per order (predefinito) addebita il prezzo una sola volta. Per item (price × quantity) lo moltiplica per il numero di articoli nel carrello. I prezzi in tempo reale di Cargoson sono sempre per spedizione.

Condizioni

Minimum weight (kg): nasconde il metodo sotto questo peso del carrello. 0 significa nessun limite (predefinito).

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 dei prodotti che richiedono spedizione (dopo il coupon, senza tasse) raggiunge questo importo. Lascialo vuoto per mostrarlo sempre.

Free shipping: attiva la spedizione gratuita Cargoson a partire dall'importo indicato sotto.

Free shipping from: il subtotale dei prodotti che richiedono spedizione (dopo il coupon, senza tasse) a partire dal quale la spedizione è gratuita. Usato solo quando Free shipping è attivo.

Tax class: la classe fiscale del costo di spedizione, oppure No tax (predefinito). I prezzi dei vettori in Cargoson sono di solito netti (senza IVA). Scegli No tax se i tuoi prezzi includono già le tasse.

Disponibilità

Geo zone: offre Cargoson solo per gli indirizzi in questa zona geografica. All zones (predefinito) significa nessun limite. Le zone geografiche si gestiscono in System > Localisation > Geo Zones.

Ignore shipping zones: non verifica la zona geografica; decide l'elenco di paesi sotto.

Countries: i paesi di destinazione per questa modalità. Lascialo vuoto per consentire tutti i paesi. Questo campo viene usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: registra ogni calcolo di tariffa in storage/logs/vfd_cgs_debug.log.php. Il file non può essere letto dal web. Gli errori dell'API e i prezzi rifiutati vengono sempre registrati, anche con questa opzione disattivata. La chiave API e il codice postale del cliente non vengono mai registrati. Quando il file raggiunge 5 MB viene spostato in vfd_cgs_debug.old.log.php e ne viene avviato uno nuovo.

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

Remove data on uninstall: se attivo, la disinstallazione dell'estensione elimina le impostazioni Cargoson, i prezzi in cache e il log. Se disattivo (predefinito), vengono conservati per una reinstallazione. Le quotazioni Cargoson degli ordini effettuati vengono sempre conservate.

Importa / Esporta

Export: clicca su Download JSON per salvare le impostazioni in un file JSON. La chiave API non viene esportata.

Import: incolla un JSON esportato in precedenza e clicca su Import per ripristinare le impostazioni, per esempio su un altro negozio. I valori vengono controllati come in un salvataggio normale. La chiave API salvata viene mantenuta.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di Cargoson. Se è impostata una Geo zone, Ignore shipping zones è disattivo e l'indirizzo è fuori dalla zona, Cargoson non viene offerto. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non rientrano nell'importo dell'ordine. I pesi dei prodotti vengono convertiti dalla loro classe di peso in chilogrammi. Poi l'estensione verifica le condizioni: paesi consentiti, peso del carrello e importo minimo dell'ordine. L'importo dell'ordine è il prezzo dei prodotti che richiedono spedizione, dopo lo sconto del coupon e prima delle tasse. Buoni regalo, punti premio e credito del negozio non vengono considerati. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata alcuna richiesta a Cargoson.

In modalità fissa, il prezzo viene preso dalla tabella. Nelle modalità in tempo reale, l'estensione 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). Un prezzo in tempo reale viene richiesto solo quando l'indirizzo di consegna ha un CAP. Cargoson restituisce i prezzi dei tuoi vettori; l'estensione sceglie il più economico (del vettore selezionato, se impostato) e, se necessario, lo converte nella valuta predefinita. Il prezzo viene calcolato nella valuta predefinita, arrotondato alle sue cifre decimali e mostrato al cliente nella sua valuta con la tassa della Tax class selezionata.

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 dell'API è di 10 secondi. Se Cargoson restituisce un errore, nessun prezzo per il percorso o un prezzo in un'altra valuta senza tasso di conversione, il cliente non vede alcun errore: il metodo viene nascosto, oppure in modalità di riserva si usa il prezzo fisso.

L'estensione calcola solo le tariffe. Non crea spedizioni o prenotazioni in Cargoson, non stampa etichette e non traccia i pacchi; 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 vettori.

In OpenCart 4 il cliente clicca su Choose nel blocco dei metodi di spedizione della pagina di checkout e sceglie Cargoson nella finestra Shipping method options. Il metodo funziona come in OpenCart 3.

Ordini

Quando un cliente effettua un ordine con Cargoson, la tariffa calcolata al checkout viene salvata con l'ordine. Nella pagina dell'ordine in Sales > Orders compare un pannello Cargoson shipping:

Carrier, Service e Cargoson service ID: il vettore 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.

Il pannello viene mostrato anche quando il metodo è disattivato. In OpenCart 4 l'ordine viene creato una volta nella fase di conferma e aggiornato ogni volta che il cliente vi torna, quindi la quotazione salvata è l'ultima calcolata al checkout; se il cliente passa a un altro metodo di spedizione, la quotazione Cargoson dell'ordine viene rimossa. Modificare l'ordine nel pannello di amministrazione non cambia la quotazione, che non cambia nemmeno in seguito. Prenota la spedizione in Cargoson o con le sue integrazioni.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox Cargoson è il primo blocco di Extensions > Extensions > Shipping > VibeFox Cargoson > Edit, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Poi il blocco mostra la chiave mascherata, lo stato (per 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: opencart-shipping-cargoson e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo gli utenti amministratori con il permesso Modify per l'estensione possono cambiare la chiave. I testi del blocco seguono la lingua dell'amministrazione (sono incluse le lingue inglese e russa).

Se la chiave non viene accettata, il blocco indica il motivo, per esempio Key not found, This key belongs to another product, Domain limit reached oppure License expired on con una data. Dopo aver cambiato l'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, l'estensione continua a funzionare con l'ultimo stato noto.

Una chiave funziona su un solo dominio: l'indirizzo del negozio nella configurazione di OpenCart. Rimuovere la chiave dal negozio 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 e non viene calcolata alcuna tariffa. Un utente amministratore che ha effettuato l'accesso all'amministrazione nello stesso browser vede ancora il metodo nel negozio, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e testare l'estensione prima di acquistare una chiave. In OpenCart 4 questa anteprima non è disponibile: il negozio non vede l'accesso dell'amministratore, quindi senza una chiave attiva il metodo viene nascosto a tutti. Dopo aver aperto una volta la pagina Edit, nella Dashboard dell'amministrazione compare un promemoria. Chiudilo con × per nasconderlo per 7 giorni. Gli ordini esistenti non sono interessati.

Quando una licenza scade, l'estensione continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene controllato di nuovo automaticamente quando apri la Dashboard dell'amministrazione o la pagina Edit: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve alcun cron job. La disinstallazione dell'estensione 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. Controlla la Geo zone (oppure Ignore shipping zones e Countries), i limiti di peso e il Minimum order amount. In modalità fissa, verifica che il paese o * All other countries abbia un prezzo per la taglia del carrello. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.

I prezzi in tempo reale non compaiono: guarda il campo Log nella pagina dell'estensione. Gli errori dell'API vengono sempre registrati; attiva Debug log per vedere ogni calcolo. Motivi tipici: non è ancora stato inserito il CAP di consegna, manca il Collection postcode, la chiave API viene rifiutata (chiave errata o scaduta, oppure il piano Cargoson non ha accesso all'API), nessun vettore per il percorso 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 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 la Currency conversion rate.

La tassa sulla spedizione viene addebitata due volte: i tuoi prezzi Cargoson includono già l'IVA. Imposta Tax class su No tax.

Le tariffe sembrano obsolete dopo una modifica: clicca su Save nella pagina dell'estensione. Questo svuota la cache dei prezzi Cargoson.

La pagina dice "Warning: You do not have permission to modify VibeFox Cargoson!": il tuo gruppo utenti amministratori potrebbe poter solo visualizzare le impostazioni. Dai al gruppo il permesso di modifica per extension/shipping/vfd_cargoson (OpenCart 3) o extension/vfd_cargoson/shipping/vfd_cargoson (OpenCart 4) in System > Users > User Groups.

Per gli sviluppatori: l'indirizzo dell'API Cargoson può essere sostituito con l'impostazione vfd_cgs_api_url (per i test); non ha un campo nella pagina delle impostazioni.

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox Cargoson. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable Cargoson, Sort order, Tax class e Geo zone. Le tariffe in cache vengono sempre rimosse. Se Remove data on uninstall è attivo, vengono eliminati anche le impostazioni Cargoson e il log di debug. Se è disattivo, le altre impostazioni vengono conservate e riutilizzate alla reinstallazione dell'estensione. Le quotazioni Cargoson degli ordini effettuati non vengono mai eliminate, e gli ordini esistenti mantengono il loro metodo di spedizione e il loro costo.

In OpenCart 4, per rimuovere anche i file dell'estensione, vai su Extensions > Installer dopo la disinstallazione e clicca su Uninstall (il pulsante arancione −) accanto a VibeFox Cargoson nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso del cestino) per eliminare il pacchetto caricato.

Cargoson è un marchio del rispettivo proprietario. Questa estensione non è affiliata né approvata da Cargoson.