VibeFox Shippo 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 Shippo: crea un account Shippo, collega o attiva i corrieri (USPS, UPS, FedEx, DHL e altri) e copia il token API da Shippo > Settings > Advanced > API. Shippo addebita le etichette acquistate, non le richieste di tariffe. I nuovi account Shippo potrebbero dover essere verificati da Shippo prima che vengano restituite tariffe in tempo reale. Senza token vengono usati solo i prezzi di riserva.

Prodotti: i prodotti dovrebbero avere peso e dimensioni. I prodotti senza dimensioni usano la dimensione di scatola predefinita.

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un 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_shippo-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_shippo.ocmod.zip. Installa solo il pacchetto per la 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_shippo-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non devi aggiornare Extensions > Modifications. In alternativa all'Installer, puoi copiare il contenuto della cartella upload del pacchetto nella cartella principale del tuo negozio.

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

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

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

5. Incolla il tuo token API di Shippo e compila l'indirizzo Ship from. Il codice postale è obbligatorio per le tariffe in tempo reale.

6. Scegli la Shippo rate currency (USD se spedisci dagli Stati Uniti) e, se la valuta predefinita del tuo negozio è diversa, inserisci il Exchange rate.

7. Facoltativamente, inserisci i prezzi di riserva, attiva Enable Shippo shipping e clicca su Save.

OpenCart 4

1. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_shippo.ocmod.zip. Non rinominare il file: OpenCart 4 prende 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 Shippo, clicca su Install (il pulsante verde +), poi su Edit (il pulsante con la matita).

4. Inserisci la chiave di licenza e le impostazioni come nei passaggi da 4 a 7 per OpenCart 3. La pagina delle impostazioni e i suoi campi sono uguali in entrambe le versioni.

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

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox Shippo > Edit. Le sezioni sono elencate a sinistra. Un pulsante Save salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella anche le tariffe Shippo in cache. Solo gli amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.

Gli avvisi in cima alla pagina ti segnalano quando il metodo non potrà mai essere mostrato o quando non è possibile usare le tariffe in tempo reale: token API mancante, codice postale o paese di spedizione mancanti, tasso di cambio mancante, oppure un'unità di peso o di lunghezza del negozio non riconosciuta dall'estensione (usa kg, g, lb o oz e cm, mm, m o in in System > Settings, scheda Local). Un avviso ti ricorda quando è impostato un token di prova. Al salvataggio, un nome non valido, un valore che non è un numero, un numero o una cella di prezzo negativi, un Minimum weight (kg) maggiore di Maximum weight (kg) o un ordine di visualizzazione che non è un numero intero vengono segnalati come errore, e non si salva nulla finché non li correggi.

Generali

Enable Shippo shipping: offre il metodo al checkout. È lo stato dell'estensione in Extensions > Extensions > Shipping.

Name: il nome del metodo di spedizione mostrato al cliente al checkout. Predefinito: Shippo Shipping. Obbligatorio, massimo 64 caratteri, senza i caratteri < > ; = # { }.

Tax class: la classe fiscale del costo di spedizione, oppure No tax. Le tariffe di Shippo non includono l'imposta sulle vendite. No tax le mostra così come sono quotate; una classe fiscale aggiunge l'imposta sulla spedizione secondo le tue regole fiscali.

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

Account Shippo

API token: il tuo token API di Shippo. Usa il token live (shippo_live_...) per tariffe reali nel negozio in produzione, oppure un token di test (shippo_test_...) per le tariffe di prova di Shippo. Il token viene inviato solo a Shippo e non viene mai registrato. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per cambiarlo.

Remove the saved API token: attivalo e salva per eliminare il token salvato.

Allowed carriers / services: facoltativo, separato da virgole. Inserisci un corriere come lo chiama Shippo (USPS, UPS, FedEx, DHL Express) oppure un token di livello di servizio Shippo (usps_priority, ups_ground). Viene mostrata la tariffa consentita più economica. Lascialo vuoto per mostrare la tariffa più economica di qualsiasi corriere.

Ship from (l'indirizzo da cui vengono spediti i tuoi pacchi)

Quando il paese di spedizione è il paese del tuo negozio, un nome del mittente e uno stato vuoti vengono ripresi dal nome del negozio e dalla regione in System > Settings. OpenCart non ha una via, una città o un codice postale strutturati per il negozio, quindi inseriscili qui.

Sender name / company: il nome del mittente. Viene usato anche per firmare la dichiarazione doganale. Se è vuoto, viene usato il nome del negozio.

Street address: la via del mittente.

City: la città del mittente.

State / province: il codice dello stato a due lettere, per esempio CA o NY. Alcuni corrieri lo richiedono.

Postal / ZIP code: obbligatorio per le tariffe in tempo reale, per esempio 94105.

Country: il paese da cui spedisci. Predefinito: Stati Uniti.

Tariffe

Parcels: come il carrello viene inviato a Shippo.

Default box size: lunghezza x larghezza x altezza nell'unità di lunghezza del tuo negozio (indicata nel nome del campo), per esempio 30 x 20 x 10. Shippo richiede la dimensione della scatola. Viene usata quando un prodotto nel carrello non ha dimensioni. Lascialo vuoto per usare 30 x 20 x 10 cm. Un valore non leggibile viene ignorato con un avviso dopo il salvataggio, e le altre impostazioni vengono salvate.

Shippo rate currency: la valuta in cui Shippo quota i tuoi corrieri, cioè la valuta del paese di spedizione: USD (USA), CAD (Canada), GBP (Regno Unito), EUR (area euro) o AUD (Australia). Predefinito: USD. Le tariffe che Shippo restituisce nella valuta predefinita del tuo negozio vengono sempre usate così come sono.

Exchange rate: il prezzo di 1 unità della valuta delle tariffe Shippo nella valuta predefinita del tuo negozio, per esempio 0.92. Non serve se le due valute coincidono. Senza di esso, le tariffe nell'altra valuta non vengono usate e si applicano i prezzi di riserva. L'estensione non converte automaticamente le valute.

Prezzi di riserva (usati quando non c'è una tariffa in tempo reale: nessun token API, Shippo non raggiungibile, token rifiutato o nessuna tariffa di corriere per l'indirizzo; prezzi nella valuta predefinita del negozio, IVA esclusa; lascia vuoti entrambi i campi per nascondere il metodo in quel caso)

Country prices: una tabella dei prezzi per paese e peso del carrello. Clicca su Add country per aggiungere una riga. Le colonne sono Price e le fasce di peso XS (fino a 1 kg), S (da 1 a 2 kg), M (da 2 a 3 kg), L (da 3 a 5 kg) e XL (oltre 5 kg). Una fascia vuota o pari a 0 usa la colonna Price. La riga * Default si applica ai paesi che non hanno una riga propria. Una riga salvata con tutte le celle vuote addebita 0, quindi elimina le righe che non compilerai.

Other countries: il prezzo per i paesi che non sono nella tabella sopra (quando non esiste una riga * Default). Lascialo vuoto per nascondere il metodo per questi paesi.

Condizioni

Free shipping from: il subtotale dei prodotti che richiedono spedizione (dopo il coupon, prima delle imposte) da cui la spedizione è gratuita. In quel caso non viene fatta alcuna richiesta a Shippo. Lascialo vuoto per disattivarla.

Minimum subtotal: mostra il metodo solo se il subtotale dei prodotti che richiedono spedizione (dopo il coupon, prima delle imposte) è almeno questo importo. Lascialo vuoto per mostrarlo sempre.

Minimum weight (kg): il peso minimo del carrello per mostrare il metodo. 0 significa nessun limite (predefinito).

Maximum weight (kg): il metodo viene nascosto sopra questo peso del carrello. Predefinito: 30. 0 significa nessun limite. Un campo vuoto viene salvato come 30.

Disponibilità senza zone di spedizione

Normalmente la geo zone decide dove viene offerto il metodo. In alternativa, può essere offerto per paese, indipendentemente dalla geo zone.

Geo zone: offri il metodo solo per gli indirizzi in questa geo zone. All zones (predefinito) significa nessun limite. Non viene usata finché Ignore shipping zones è attivo. Le geo zone si gestiscono in System > Localisation > Geo Zones.

Ignore shipping zones: offri il metodo per i paesi indicati sotto, che siano o meno nella geo zone.

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

Avanzate

Debug log: registra le richieste a Shippo in storage/logs/vfd_shpo_debug.log.php (in OpenCart 4, system/storage/logs/vfd_shpo_debug.log.php). Il file non è leggibile dal web. Gli errori dell'API vengono sempre registrati, anche con questa opzione disattivata. Il token API e gli indirizzi dei clienti non vengono mai registrati. Quando il file raggiunge 5 MB, viene spostato in vfd_shpo_debug.old.log.php e si avvia un nuovo registro.

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

Remove data on uninstall: se attivo, disinstallando l'estensione vengono eliminate le impostazioni Shippo e il registro. Se disattivo (predefinito), vengono conservati per una reinstallazione. Le tariffe in cache vengono sempre rimosse. Il corriere e il servizio salvati con gli ordini fanno parte dello storico degli ordini e vengono conservati.

Importa / Esporta

Export: clicca su Download JSON per salvare le impostazioni in un file JSON. Il token API non viene esportato.

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 normale salvataggio. Il token API salvato non viene modificato.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo Shippo. Se è impostata una Geo zone (e Ignore shipping zones è disattivato) e l'indirizzo è al di fuori, il metodo non viene offerto. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non sono inclusi nel subtotale. L'estensione controlla poi le condizioni: i paesi di Ignore shipping zones, il peso del carrello e il subtotale minimo. Buoni regalo, punti fedeltà e credito del negozio non vengono considerati. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata alcuna richiesta a Shippo.

L'estensione invia poi a Shippo l'indirizzo di spedizione del negozio, l'indirizzo del cliente e il pacco. Per i paesi in cui OpenCart richiede un codice postale, la richiesta attende che il cliente lo abbia inserito. Per le spedizioni internazionali viene aggiunta una dichiarazione doganale con i nomi degli articoli (con le opzioni scelte), le quantità, i pesi e i valori. Shippo restituisce le tariffe dei tuoi corrieri e l'estensione usa la tariffa consentita più economica. Il prezzo viene calcolato nella valuta predefinita del tuo negozio, arrotondato ai suoi decimali e mostrato al cliente nella sua valuta con l'imposta della Tax class selezionata.

Nella modalità per ordine, gli articoli vengono impilati in una scatola: il lato più lungo e quello intermedio degli articoli più grandi, e i lati più corti di tutte le unità sommati. Se un prodotto non ha dimensioni, per l'intero pacco viene usata la dimensione di scatola predefinita. Nella modalità per articolo, ogni prodotto viene tariffato come pacco a sé e la tariffa viene moltiplicata per la sua quantità.

Ogni risposta viene memorizzata nella cache per 1 ora per indirizzo e pacco. Quando Shippo risponde senza una tariffa utilizzabile, l'indirizzo viene ricordato per 10 minuti. Dopo un timeout, un token rifiutato, un errore del server o un limite di frequenza, l'estensione sospende le richieste per 5 minuti e usa i prezzi di riserva. Il timeout della richiesta è di 10 secondi.

Se non c'è una tariffa in tempo reale, il prezzo viene preso dalla tabella dei prezzi di riserva e poi da Other countries. Se nessuno dei due si applica, il metodo viene nascosto. Il cliente non vede mai un errore. Il motivo viene scritto nel registro di debug.

L'estensione calcola solo tariffe. Non acquista etichette, non traccia i pacchi, non convalida gli indirizzi, non offre punti di ritiro o consegna, assicurazioni, opzioni di firma o etichette di reso. Viene mostrata solo la tariffa consentita più economica, non un elenco di tutti i servizi. Non c'è un confezionamento delle scatole oltre all'impilamento descritto sopra, né maggiorazioni della tariffa o commissioni di gestione.

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

Ordini

Quando un ordine viene effettuato con una tariffa Shippo in tempo reale, l'estensione conserva il Carrier / service scelto e, per un pacco per ordine, i Estimated delivery days. Apri l'ordine in Sales > Orders: compaiono nel riquadro Shippo, sopra lo storico dell'ordine, così puoi acquistare in Shippo l'etichetta corrispondente. I dati vengono salvati con l'ordine: le modifiche successive al carrello o alle impostazioni non li cambiano. Il riquadro viene mostrato anche dopo aver disattivato il metodo. Gli ordini con prezzo di riserva o spedizione gratuita non hanno un riquadro Shippo.

OpenCart 4 mantiene un unico ordine per il checkout e lo aggiorna ogni volta che il cliente conferma di nuovo. La tariffa Shippo salvata viene aggiornata con esso. Se il cliente passa a un altro metodo di spedizione, o se ora si applica il prezzo di riserva, la tariffa salvata viene rimossa dall'ordine.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Shippo è il primo blocco di Extensions > Extensions > Shipping > VibeFox Shippo > Edit, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (per esempio la data fino a cui 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-shippo e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo gli amministratori con il permesso Modify per l'estensione possono cambiare la chiave. I testi del blocco seguono la lingua dell'amministrazione (sono inclusi inglese e russo).

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 o License expired on con una data. Dopo una modifica 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, l'estensione continua a funzionare con l'ultimo stato noto.

Una chiave funziona su un dominio: l'indirizzo del negozio dalla 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, il metodo di spedizione Shippo non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Un amministratore che ha effettuato l'accesso all'amministrazione nello stesso browser vede comunque il metodo nel negozio, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e provare l'estensione prima di acquistare una chiave. Su OpenCart 4 questa anteprima non è disponibile: il negozio non vede l'accesso dell'amministratore, quindi senza una chiave attiva il metodo è nascosto a tutti. Dopo aver aperto una volta la pagina Edit, compare un promemoria nel Dashboard dell'amministrazione. 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 un rinnovo. Lo stato viene controllato di nuovo automaticamente quando apri il Dashboard dell'amministrazione o la pagina Edit: 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 l'estensione rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Shippo non compare al checkout: controlla che la licenza sia attiva e che Enable Shippo shipping sia attivo. Controlla Geo zone (oppure, con Ignore shipping zones attivo, Countries), i limiti di peso e Minimum subtotal. Senza una tariffa in tempo reale, verifica che il paese, * Default o Other countries abbia un prezzo. Controlla che i prodotti abbiano Requires Shipping impostato su Yes.

Le tariffe in tempo reale non compaiono: attiva il Debug log, ricarica il checkout e guarda il campo Log nella pagina dell'estensione. Motivi frequenti: manca il token API o il codice postale di spedizione; la valuta predefinita del negozio è diversa da quella delle tariffe Shippo senza un tasso di cambio; il cliente non ha ancora inserito il codice postale; nessun corriere del tuo account Shippo serve l'indirizzo; oppure l'account Shippo non è ancora verificato.

Tariffe di prova nel negozio in produzione: un token di prova (shippo_test_...) restituisce tariffe di prova di Shippo. Usa il token live (shippo_live_...).

Spedizione gratuita per paesi inattesi: controlla la tabella dei prezzi per una riga vuota, soprattutto una riga * Default vuota. Una riga con tutte le celle vuote addebita 0.

Pesi o dimensioni di scatola errati: se la pagina avvisa di un'unità di peso o di lunghezza sconosciuta, imposta una classe di peso in kg, g, lb o oz e una classe di lunghezza in cm, mm, m o in in System > Settings, scheda Local.

Le tariffe sembrano obsolete dopo una modifica: clicca su Save nella pagina dell'estensione. Questo cancella le tariffe Shippo in cache.

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

Per gli sviluppatori: l'indirizzo dell'API di Shippo può essere sostituito con l'impostazione vfd_shpo_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 Shippo. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable Shippo shipping, Sort order, Tax class e Geo zone. Le tariffe in cache vengono sempre rimosse. Se Remove data on uninstall è attivo, vengono eliminate anche le impostazioni Shippo e il registro di debug. Se è disattivo, le altre impostazioni restano e vengono riutilizzate quando reinstalli l'estensione. Gli ordini esistenti mantengono il loro metodo di spedizione, il loro costo e i dati Shippo di corriere e servizio.

Su 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 Shippo nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per rimuovere il pacchetto caricato.

Shippo è un marchio del rispettivo titolare. Questa estensione non è affiliata né approvata da Shippo.