VibeFox Shippo for WooCommerce — Guida

Requisiti

WordPress: 5.8 o successivo.

WooCommerce: 7.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.

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 devono 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. 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_shippo in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox Shippo, 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. Incolla il token API di Shippo e compila l'indirizzo Ship from. Il codice postale è obbligatorio.

6. Scegli la Shippo rate currency (USD se spedisci dagli USA) e, se il tuo negozio usa un'altra valuta, inserisci il tasso di cambio.

7. Facoltativamente, inserisci i prezzi di riserva nella tabella per paese e peso.

8. Aggiungi VibeFox Shippo 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 Shippo. 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 che il cliente vede per questa zona. Lascialo vuoto per usare il Name globale.

Ogni volta che salvi le impostazioni, le tariffe Shippo in cache vengono cancellate. Gli avvisi sopra le impostazioni ti segnalano quando il metodo non può mai essere mostrato o quando non si possono usare le tariffe in tempo reale: nessun token API, nessun codice postale o paese di spedizione, oppure manca il tasso di cambio. Un avviso ti ricorda quando è impostato un token di test.

Generali

Enable/Disable: attiva o disattiva il metodo in tutte le zone contemporaneamente.

Name: il nome del metodo di spedizione mostrato nel checkout. Una zona può sostituirlo con il proprio Title. Predefinito: Shippo Shipping.

Account Shippo

API token: il tuo token API di Shippo. Usa il token live (shippo_live_...) per tariffe reali sul negozio attivo, oppure un token di test (shippo_test_...) per le tariffe di test di Shippo.

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 di Shippo (usps_priority, ups_ground). Viene mostrata la tariffa consentita più economica. Lascia vuoto per mostrare la tariffa più economica di qualsiasi corriere.

Ship from (l'indirizzo da cui vengono spediti i pacchi; i campi vuoti vengono presi dall'indirizzo del negozio in WooCommerce > Settings > General se si trova nello stesso paese)

Sender name / company: il nome del mittente. Viene usato anche per firmare la dichiarazione doganale.

Street address: la via del mittente.

City: la città del mittente.

State / province: il codice di 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: United States.

Tariffe

Parcels: come il carrello viene inviato a Shippo.

Default box size: lunghezza x larghezza x altezza nell'unità di misura del tuo negozio, per esempio 30 x 20 x 10. Shippo richiede la dimensione della scatola. Viene usata quando un prodotto nel carrello non ha dimensioni. Lascia vuoto per usare 30 x 20 x 10 cm.

Shippo rate currency: la valuta in cui Shippo quota i 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 del negozio vengono sempre usate così come sono.

Exchange rate: il prezzo di 1 unità della Shippo rate currency nella valuta 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. Il plugin non converte le valute automaticamente.

Tax status: Taxable consente a WooCommerce di applicare le tasse sulla spedizione secondo le tue regole fiscali, None no. Le tariffe Shippo non includono l'imposta sulle vendite.

Prezzi di riserva (usati 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 del negozio; lascia vuoti entrambi i campi per nascondere il metodo 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 sulla croce 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 inizia 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 che non sono nella tabella sopra (quando non c'è una riga * Default). Lascia vuoto per nascondere il metodo per questi paesi.

Condizioni

Free shipping from: il subtotale del carrello da cui la spedizione è gratuita. In quel caso non viene inviata alcuna richiesta a Shippo. Lascia vuoto per disattivarla.

Minimum subtotal: mostra il metodo solo se il subtotale del carrello è almeno questo importo. Lascia vuoto per mostrarlo sempre.

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

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

Disabled shipping classes: nasconde il metodo se il carrello contiene un prodotto di una di queste classi di spedizione di WooCommerce.

Disponibilità senza zone di spedizione

Ignore shipping zones: offre il metodo per i paesi indicati sotto, che sia aggiunto o meno a una zona.

Countries: i paesi di destinazione per questa modalità. Lascia vuoto per usare tutti i paesi verso cui il negozio spedisce. Questo campo viene usato solo quando Ignore shipping zones è attivo. Un metodo aggiunto a una zona di spedizione funziona sempre per i paesi della sua zona.

Avanzate

Debug log: registra le richieste a Shippo in WooCommerce > Status > Logs, origine vfd-shippo. Gli errori API vengono sempre registrati, anche con questa opzione disattivata. Il token API e gli indirizzi dei clienti non vengono mai registrati.

Remove data on uninstall: se attiva, eliminando il plugin vengono rimosse le sue impostazioni e i suoi metodi nelle zone di spedizione. La disattivazione del plugin non elimina mai le impostazioni.

Come funziona al checkout

Quando il cliente inserisce un indirizzo di consegna, WooCommerce chiede al plugin una tariffa. Il plugin controlla prima le condizioni: peso del carrello, subtotale minimo e classi di spedizione disattivate. Se si applica la spedizione gratuita, il metodo viene mostrato con prezzo 0 e non viene inviata alcuna richiesta a Shippo.

Il plugin invia poi a Shippo l'indirizzo di spedizione, l'indirizzo del cliente e il pacco. Per i paesi in cui WooCommerce richiede un 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 plugin mostra la tariffa consentita più economica nella valuta del negozio, sotto il nome del metodo.

In modalità per ordine, gli articoli vengono impilati in un'unica scatola: il lato più lungo e quello intermedio degli articoli più grandi, più i lati più corti di tutte le unità sommati. Se un prodotto non ha dimensioni, per l'intero pacco si usa 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 plugin 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 dalla tabella di riserva, poi da Other countries. Se nessuna delle due si applica, il metodo viene nascosto. Il cliente non vede mai un errore.

Il metodo funziona nel checkout classico e nei blocchi Carrello e Checkout. È compatibile con WooCommerce High-Performance Order Storage (HPOS).

Il plugin 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 in scatole oltre all'impilamento descritto sopra, né maggiorazione della tariffa o commissione di gestione.

Ordini

La riga di spedizione dell'ordine memorizza il Carrier / service scelto e, per un pacco per ordine, i Estimated delivery days. Li vedi nella schermata di amministrazione dell'ordine e puoi acquistare l'etichetta corrispondente in Shippo.

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 Shippo. 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 collegamento Manage licenses and domains in your account apre il tuo account vibefox.net.

Una chiave funziona su un 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, Shippo non viene mostrato ai clienti nel checkout. I gestori del negozio che hanno effettuato l'accesso lo vedono ancora, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Nella pagina Plugins e nelle pagine di WooCommerce compare un promemoria. Gli ordini esistenti non sono interessati.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e assistenza richiedono un rinnovo. Lo stato viene controllato di nuovo automaticamente in background.

Risoluzione dei problemi

Shippo non compare nel 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 subtotal e Disabled shipping classes. Senza una tariffa in tempo reale, verifica che il paese, * Default o Other countries abbia un prezzo.

Le tariffe in tempo reale non compaiono: attiva Debug log, ricarica il checkout e apri WooCommerce > Status > Logs, origine vfd-shippo. Cause frequenti: nessun token API o codice postale di spedizione, una valuta del negozio diversa dalla Shippo rate currency 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 sul negozio attivo: un token di test (shippo_test_...) restituisce tariffe di test 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.

Le tariffe sembrano obsolete dopo una modifica: salva la pagina delle impostazioni. Questo cancella le tariffe Shippo in cache.

Per sviluppatori: i filtri vfd_shpo_shipment_request, vfd_shpo_customs_declaration, vfd_shpo_selected_rate e vfd_shpo_api_url modificano il corpo della richiesta, la dichiarazione doganale, la tariffa scelta e l'URL dell'API.

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 dalla pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin, così come le tariffe in cache, vengono sempre rimossi. Le impostazioni e i metodi nelle zone 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.

Shippo è un marchio del rispettivo proprietario. Questo plugin non è affiliato a Shippo né approvato da Shippo.