VibeFox Shippo 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 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 usate solo le tariffe di riserva.

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

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 fai clic su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, fai clic su Configure, oppure trova più tardi VibeFox Shippo nell'elenco dei moduli e fai clic 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. Incolla il tuo token API Shippo e compila l'indirizzo Ship from. Il codice postale è obbligatorio per le tariffe in tempo reale.

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

6. Facoltativamente inserisci le tariffe di riserva nella tabella per paese e peso, poi fai clic su Save.

All'installazione il modulo crea il corriere Shippo Shipping con il testo dei tempi di consegna Shippo carriers (USPS, UPS, FedEx, DHL). Il corriere viene assegnato a tutte le zone e a tutti i gruppi di clienti. Puoi cambiare zone, gruppi di clienti, tempi di consegna, logo e limiti di dimensioni in Shipping > Carriers. Non impostare prezzi lì: il prezzo arriva sempre dal modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Shippo > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella anche le tariffe Shippo memorizzate nella cache.

Gli avvisi in cima alla pagina ti dicono quando il corriere non potrà mai essere mostrato o quando le tariffe in tempo reale non possono essere usate: manca il token API, manca il codice postale o il paese di partenza, manca il tasso di cambio, oppure l'unità di peso o di dimensioni del negozio non è una che il modulo conosce (imposta kg, g, lb o oz e cm, mm, m o in in International > Localization, Local units). Un avviso ti ricorda quando è impostato un token di test. Al salvataggio, un valore che non è un numero, un numero negativo o un Minimum weight (kg) maggiore di Maximum weight (kg) viene segnalato come errore, e nulla viene salvato finché non lo correggi.

Generale

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

Name: il nome del corriere mostrato al cliente nel checkout. Predefinito: Shippo Shipping. Obbligatorio, massimo 64 caratteri.

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

Account Shippo

API token: il tuo token API 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 test di Shippo. Il token viene inviato solo a Shippo e non viene mai registrato nei log. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un valore nuovo solo per cambiarlo, oppure spunta Remove the saved API token per eliminarlo.

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. Lascia vuoto per mostrare la tariffa più economica di qualsiasi corriere.

Indirizzo di partenza (l'indirizzo da cui vengono spediti i pacchi; i campi vuoti vengono presi dall'indirizzo del negozio in Shop Parameters > Contact > Stores quando è nello stesso paese)

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.

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 dimensione del tuo negozio (mostrata nel nome del campo), per esempio 30 x 20 x 10. Shippo richiede le dimensioni della scatola. Viene usata quando un prodotto nel carrello non ha dimensioni. Lascia vuoto per usare 30 x 20 x 10 cm. Un valore che non può essere letto viene ignorato con un avviso dopo il salvataggio.

Shippo rate currency: la valuta in cui Shippo quota i tuoi corrieri, cioè la valuta del paese di partenza: USD (USA), CAD (Canada), GBP (Regno Unito), EUR (eurozona) 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 quando le due valute sono uguali. Senza di esso, le tariffe nell'altra valuta non vengono usate e si applicano le tariffe di riserva. Il modulo non converte le valute automaticamente.

Tariffe di riserva (usate quando non c'è una tariffa in tempo reale: nessun token API, Shippo non raggiungibile, token rifiutato o nessuna tariffa dei corrieri per l'indirizzo; prezzi nella valuta predefinita del tuo negozio, imposte escluse; lascia vuoti entrambi i campi per nascondere il corriere in quel caso)

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

Other countries: il prezzo per i paesi non presenti nella tabella sopra (quando non esiste una riga * Default). Lascia vuoto per nascondere il corriere per questi paesi.

Condizioni

Free shipping from: il subtotale del carrello (dopo gli sconti, prima delle imposte) da cui la spedizione è gratuita. In quel caso non viene fatta alcuna richiesta a Shippo. Lascia vuoto per disattivarla.

Minimum subtotal: mostra il corriere solo se il subtotale del carrello (dopo gli sconti, prima delle imposte) è almeno questo importo. Lascia vuoto per mostrarlo sempre.

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

Maximum weight (kg): il corriere 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 il corriere viene offerto nelle sue zone di spedizione in Shipping > Carriers. In alternativa può essere offerto per paese, indipendentemente dalle zone.

Ignore shipping zones: offre il corriere per i paesi indicati qui sotto, indipendentemente dal fatto che la loro zona sia assegnata. Finché è attivo, il corriere viene aggiunto a tutte le zone, comprese quelle create in seguito. Disattivandolo, le zone aggiunte vengono rimosse e il corriere mantiene le sue zone.

Countries: i paesi di destinazione per questa modalità. Lascia 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 logs/vfd_shpo_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori API vengono sempre registrati, anche con questa opzione disattivata. Il token API e gli indirizzi dei clienti non vengono mai registrati.

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

Remove data on uninstall: se attiva, disinstallando il modulo vengono eliminate le impostazioni del modulo, il corriere e il log. Se disattiva, tutto viene conservato per una nuova installazione. Le tariffe in cache vengono sempre rimosse. Il corriere e il servizio salvati con gli ordini fanno parte dello storico ordini e vengono conservati.

Come funziona nel checkout

Nel passaggio della spedizione PrestaShop chiede al modulo il prezzo Shippo. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nel subtotale. Il modulo controlla prima le condizioni: i paesi di Ignore shipping zones, il peso del carrello e il subtotale minimo. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata alcuna richiesta a Shippo.

Il modulo invia poi a Shippo l'indirizzo di partenza, l'indirizzo del cliente e il pacco. Per i paesi in cui PrestaShop richiede il codice postale, la richiesta attende che il cliente lo inserisca. Per le spedizioni internazionali viene aggiunta una dichiarazione doganale con nomi, quantità, pesi e valori degli articoli. Shippo restituisce le tariffe dei tuoi corrieri e il modulo usa la tariffa consentita più economica. Il prezzo viene calcolato nella valuta predefinita del tuo negozio e poi mostrato nella valuta del carrello del cliente.

In modalità per ordine, gli articoli vengono impilati in un'unica scatola: i lati più lunghi e intermedi 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 scatola predefinita. In modalità per articolo, ogni prodotto viene tariffato come pacco separato 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 richieste, il modulo sospende le richieste per 5 minuti e usa le tariffe di riserva. Il timeout della richiesta è di 10 secondi.

Se non c'è una tariffa in tempo reale, il prezzo arriva dalla tabella di riserva, poi da Other countries. Se nessuna delle due si applica, il corriere viene nascosto. Il cliente non vede mai un errore. Il motivo viene scritto nel log di debug.

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

Il modulo calcola solo le tariffe. Non acquista etichette, non traccia i pacchi, non convalida gli indirizzi e non offre punti di ritiro o consegna, assicurazione, 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.

Ordini

Quando un ordine viene effettuato con una tariffa Shippo in tempo reale, il modulo conserva il Carrier / service scelto e, per un pacco per ordine, i Estimated delivery days. Compaiono nel blocco Shippo nella pagina dell'ordine nel back office, così puoi acquistare l'etichetta corrispondente in Shippo. I dati vengono congelati con l'ordine: le modifiche successive del carrello non li cambiano. Gli ordini con tariffa di riserva o spedizione gratuita non hanno il blocco Shippo.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Shippo è il primo blocco della pagina Modules > Module Manager > VibeFox Shippo > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopo, 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: presta-shipping-shippo e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo i dipendenti con il permesso Configure per il 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 spiega il motivo, per esempio Key not found, This key belongs to another product, Domain limit reached oppure License expired on con 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: quello 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 Shippo non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Il front office di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il corriere è nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non testarlo al checkout. Un promemoria compare in Modules > Module Manager nella scheda Alerts. Gli ordini esistenti non sono interessati.

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

Shippo non compare nel checkout: verifica che la licenza sia attiva e che Enable Shippo shipping 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 consentito). Controlla i limiti di peso e il Minimum subtotal. Senza una tariffa in tempo reale, verifica che il paese, * Default o Other countries abbia un prezzo. I prodotti possono anche essere limitati a determinati corrieri nella pagina del prodotto.

Le tariffe in tempo reale non compaiono: attiva il Debug log, ricarica il checkout e guarda il campo Log nella pagina del modulo. Motivi comuni: manca il token API o il codice postale di partenza, una valuta predefinita del negozio diversa dalla valuta delle tariffe Shippo senza tasso di cambio, il codice postale del cliente non ancora inserito, nessun corriere del tuo account Shippo serve l'indirizzo, oppure l'account Shippo non è ancora verificato.

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

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

Le tariffe sembrano obsolete dopo una modifica: fai clic su Save nella pagina del modulo. Questo cancella le tariffe Shippo in cache.

La pagina dice che il corriere Shippo 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 Shippo e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. Le tariffe in cache vengono sempre rimosse. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini conservano lo storico) e vengono rimosse le impostazioni e il log. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni vengono conservate. Reinstallare il modulo ridà al corriere lo stato che aveva prima. Gli ordini esistenti conservano i dati del corriere e del servizio Shippo.

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