VibeFox EasyPost for WooCommerce — Guida

Requisiti

WordPress: 5.8 o successivo.

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

PHP: 8.0 o successivo.

Account EasyPost (solo per le tariffe in tempo reale): crea un account sul sito di EasyPost, collega i tuoi account dei vettori (USPS, UPS, FedEx e altri) nella dashboard di EasyPost e copia la chiave API da EasyPost Dashboard > Account Settings > API Keys. EasyPost addebita le etichette acquistate, non le richieste di tariffe. Se usi solo le tariffe di riserva, non ti serve un account EasyPost.

Prodotti: i prodotti devono avere un peso e, meglio ancora, le dimensioni.

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

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox EasyPost, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugin.

4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.

5. Incolla la tua chiave API EasyPost e compila l'indirizzo Ship from. Il CAP è obbligatorio per le tariffe in tempo reale.

6. Se la valuta del tuo negozio non è USD, inserisci l'USD exchange rate. Facoltativamente, inserisci le tariffe di riserva (vedi Configurazione).

7. Aggiungi VibeFox EasyPost 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 EasyPost. 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 del metodo di spedizione che i clienti vedono per questa zona. Lascialo vuoto per usare il Name globale.

In cima alla pagina il plugin mostra avvisi quando le tariffe in tempo reale non possono essere usate: nessuna chiave API, nessun CAP o paese di partenza, oppure una valuta del negozio diversa da USD senza tasso di cambio. Compare anche una nota quando è impostata una chiave API di test. Ogni volta che salvi le impostazioni, le tariffe EasyPost in cache vengono cancellate.

Generali

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

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

Account EasyPost

API key: la tua chiave API EasyPost da EasyPost Dashboard > Account Settings > API Keys. Una chiave di produzione (inizia con EZAK) restituisce tariffe reali. Una chiave di test (inizia con EZTK) restituisce tariffe di test EasyPost; usala solo per le prove.

Allowed carriers / services: facoltativo, separato da virgole. Inserisci un vettore (USPS) oppure un vettore e un servizio (USPS:Priority, UPS:Ground) così come EasyPost li denomina. Viene mostrata la tariffa consentita più economica. Lascialo vuoto per mostrare la tariffa più economica di qualsiasi vettore.

Spedizione da

L'indirizzo da cui vengono spediti i tuoi pacchi. Se il Country è il paese del tuo negozio, i campi vuoti vengono compilati con l'indirizzo del negozio in WooCommerce > Settings > General (e il nome del mittente con il titolo del sito).

Sender name / company: il nome del mittente o dell'azienda.

Street address: la via dell'indirizzo di spedizione.

City: la città di spedizione.

State: il codice di due lettere della provincia o dello stato, per esempio CA o NY.

ZIP code: il CAP o codice postale di spedizione. Obbligatorio per le tariffe in tempo reale.

Country: il paese da cui spedisci. Predefinito: United States.

Tariffe

Parcels: come il carrello viene inviato a EasyPost.

I pesi vengono convertiti dall'unità di peso del negozio in once (minimo 1 oz) e le dimensioni in pollici. Se un prodotto non ha dimensioni, il pacco viene tariffato solo in base al peso.

USD exchange rate: le tariffe EasyPost sono in USD. Inserisci il prezzo di 1 USD nella valuta del tuo negozio, per esempio 0.92. Senza questo valore non vengono usate le tariffe in tempo reale, ma solo quelle di riserva. Non serve se la valuta del negozio è USD. I negozi in USD e CAD chiedono a EasyPost di quotare nella propria valuta. Sono accettati sia il punto sia la virgola come separatore decimale.

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

Tariffe di riserva

Vengono usate quando non c'è una tariffa in tempo reale: nessuna chiave API, EasyPost non raggiungibile, chiave rifiutata oppure nessun vettore ha una tariffa per l'indirizzo. I prezzi sono nella valuta del negozio. Lascia vuoti entrambi i campi per nascondere il metodo in questo caso.

Country prices: una riga per paese: codice paese di due lettere, due punti e il prezzo, per esempio US:9.99. Le righe in un altro formato vengono ignorate e riportate in un messaggio di errore al salvataggio.

Other countries: il prezzo per i paesi non presenti nell'elenco sopra. Lascialo vuoto per nascondere il metodo per questi paesi.

Condizioni

Free shipping from: il subtotale del carrello da cui la spedizione è gratuita. In questo caso non viene inviata alcuna richiesta a EasyPost. Lascialo vuoto per disattivarlo.

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

Minimum weight: nasconde il metodo quando il carrello pesa meno, nell'unità di peso del negozio. 0 significa nessun limite.

Maximum weight: nasconde il metodo quando il carrello pesa di più, nell'unità di peso del negozio. 0 significa nessun limite.

Disabled shipping classes: nasconde il metodo quando 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 di seguito, indipendentemente dal fatto che sia aggiunto o meno a una zona.

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

Avanzate

Debug log: scrive le richieste a EasyPost in WooCommerce > Status > Logs, origine vfd-easypost. Gli errori API vengono sempre registrati, anche con questa opzione disattivata. La chiave 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 metodi nelle zone. La disattivazione del plugin non cancella mai le impostazioni.

Come funziona al checkout

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

Altrimenti il plugin invia a EasyPost l'indirizzo di partenza, l'indirizzo di consegna e il pacco, e riceve le tariffe di tutti i tuoi account dei vettori. Sceglie la tariffa consentita più economica, la converte nella valuta del negozio e la mostra sotto il nome del tuo metodo. Per i paesi che richiedono un CAP, la richiesta viene fatta solo dopo che il cliente lo ha inserito.

Ogni risposta viene memorizzata nella cache per 1 ora per lo stesso indirizzo e lo stesso pacco. Un indirizzo senza tariffe utilizzabili viene ricordato per 10 minuti. Dopo un timeout, una chiave rifiutata, un limite di richieste (rate limit) o un errore del server EasyPost, per 5 minuti non viene inviata alcuna richiesta. Il timeout delle API è di 10 secondi. In tutti questi casi il cliente non vede alcun errore: viene usata la tariffa di riserva oppure il metodo viene nascosto se non c'è una tariffa di riserva.

Il vettore e il servizio scelti e, in modalità un pacco, i giorni di consegna stimati vengono salvati nella riga di spedizione dell'ordine. Li vedi nella schermata dell'ordine nell'area di amministrazione.

Il metodo funziona con il checkout classico e con i blocchi Carrello e Checkout. È compatibile con l'archiviazione ad alte prestazioni degli ordini di WooCommerce (HPOS).

Il plugin calcola solo le tariffe. Non acquista etichette, non traccia i pacchi, non convalida gli indirizzi, non offre punti di ritiro o consegna, e non aggiunge opzioni di assicurazione o firma. Mostra una sola opzione (la tariffa consentita più economica), non un elenco di servizi. Non c'è un confezionamento in scatole oltre all'impilamento degli articoli in un pacco, né maggiorazioni sulla tariffa o costi di gestione.

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

Una chiave funziona su un solo dominio. Rimuovere la chiave da un sito non libera il suo posto di dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, EasyPost non viene mostrato ai clienti al checkout. Gli amministratori del negozio che hanno effettuato l'accesso lo vedono ancora, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugin e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati.

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

Risoluzione dei problemi

EasyPost non compare al 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, il metodo ha bisogno di una tariffa di riserva per il paese o per Other countries.

Le tariffe in tempo reale non compaiono: leggi gli avvisi in cima alla pagina delle impostazioni, poi attiva il Debug log, ricarica il checkout e apri WooCommerce > Status > Logs, origine vfd-easypost. Motivi comuni: nessuna chiave API o CAP di partenza, un negozio non in USD senza USD exchange rate, il cliente non ha ancora inserito un CAP, nessun vettore del tuo account EasyPost serve l'indirizzo, oppure i filtri Allowed carriers / services escludono tutte le tariffe.

Le tariffe sembrano prezzi di prova: è impostata una chiave di test (EZTK...). Usa una chiave di produzione (EZAK...) sul negozio attivo.

Le tariffe si sono fermate per alcuni minuti: dopo un timeout, una chiave rifiutata o un errore del server EasyPost, il plugin sospende le richieste per 5 minuti e usa le tariffe di riserva. Controlla la chiave API e il log.

L'imposta è inclusa? Le tariffe EasyPost non includono l'imposta sulle vendite. Con Tax status su Taxable, WooCommerce applica l'imposta sulla spedizione secondo le tue impostazioni fiscali.

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

Hook per sviluppatori: i filtri vfd_ep_shipment_request (corpo della richiesta), vfd_ep_selected_rate (tariffa scelta), vfd_ep_api_url (URL base delle API) e woocommerce_shipping_vfd_easypost_is_available personalizzano il plugin.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Ad esempio, se la chiave è già usata su un altro dominio, libera un posto 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

La disattivazione del plugin mantiene tutte le impostazioni e cancella solo le tariffe in cache. Per rimuoverlo, disattivalo ed eliminalo dalla pagina Plugins. La chiave di licenza e lo stato di licenza di questo plugin, le tariffe in cache e i vecchi file di log vengono sempre rimossi. Impostazioni e metodi di zona vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano per una reinstallazione futura. Gli ordini esistenti mantengono le loro righe di spedizione.

EasyPost è un marchio registrato del rispettivo titolare. Questo plugin non è affiliato né approvato da EasyPost.