VibeFox USPS 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.

App nello USPS Developer Portal (solo per le tariffe in tempo reale): accedi allo USPS Developer Portal (developers.usps.com) con un account business USPS gratuito, crea un'app e copia il suo Consumer Key e il suo Consumer Secret. Il plugin usa le API USPS attuali con OAuth 2.0. USPS ha disattivato la vecchia API Web Tools (User ID e XML) il 25 gennaio 2026, quindi uno User ID di Web Tools non funziona più. Senza chiavi vengono usati solo i prezzi fissi.

Ship-from ZIP code: per le tariffe in tempo reale serve il codice ZIP statunitense a 5 cifre da cui vengono spediti i pacchi.

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_usps in /wp-content/plugins/ tramite FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox USPS, 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. Inserisci il Consumer Key e il Consumer Secret, il Ship from ZIP code a 5 cifre e scegli i servizi. Se la valuta del negozio non è USD, inserisci lo USD exchange rate.

6. Aggiungi VibeFox USPS a una zona di spedizione in WooCommerce > Settings > Shipping > Shipping zones, oppure attiva Ignore shipping zones e scegli i paesi.

7. Facoltativo: inserisci i prezzi fissi come riserva.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox USPS. Si applicano a tutte le zone di spedizione. Quando aggiungi il metodo a una zona, la finestra della zona ha un solo campo:

Title (zone): il nome di questa opzione al checkout. Lascialo vuoto per usare il Name globale.

Ogni volta che salvi le impostazioni, il token USPS e le tariffe in cache vengono cancellati. Puoi anche fare clic su Clear cached USPS token and rates nella sezione USPS API. Gli avvisi sopra le impostazioni ti segnalano quando è impostata solo una delle chiavi, non ci sono chiavi né prezzi fissi, manca il Ship from ZIP code, non è selezionato alcun servizio, manca lo USD exchange rate o è attivo l'ambiente di test.

Generali

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

Name: il nome del metodo di spedizione mostrato al checkout. Predefinito: USPS.

Tax status: le tariffe USPS non includono le imposte. Taxable consente a WooCommerce di aggiungere l'imposta sulla spedizione al costo, None non la aggiunge.

USPS API (tariffe in tempo reale)

Consumer Key: il Consumer Key (client_id) della tua app per sviluppatori USPS.

Consumer Secret: il Consumer Secret (client_secret) della stessa app.

Test environment: usa lo USPS Testing Environment for Mailers. Solo per le app che vi hanno accesso. Lascialo disattivato per tariffe reali. Predefinito: disattivato.

Prices: quali prezzi USPS vengono usati.

Services: i servizi USPS che possono essere offerti. Viene mostrato il servizio selezionato più economico che USPS offre per il pacco. Le tariffe Flat Rate, Cubic, Hold for Pickup e Sunday non vengono mai usate. Predefiniti: USPS Ground Advantage, Priority Mail e First-Class Package International Service.

USD exchange rate: le tariffe USPS sono in USD. Se la valuta del negozio non è USD, inserisci il prezzo di 1 USD nella valuta del negozio, per esempio 0.92. Senza di esso le tariffe in tempo reale non vengono usate e si applicano i prezzi fissi. Non serve se la valuta del negozio è USD.

Partenza della spedizione e pacco (le tariffe USPS dipendono dal codice ZIP di partenza, dal peso e dalla misura del pacco)

Ship from ZIP code: il codice ZIP statunitense a 5 cifre da cui vengono spediti i pacchi. Un codice ZIP+4 viene troncato a 5 cifre. Gli altri valori vengono rifiutati con un messaggio.

Box size: dimensioni facoltative della scatola nell'unità di misura del tuo negozio, per esempio 30x20x15. Lascialo vuoto per ricavare la misura dalle dimensioni del prodotto: la lunghezza maggiore, la larghezza maggiore e le altezze sovrapposte. Se un prodotto non ha dimensioni, viene usata una scatola da 10 x 8 x 4 pollici.

Default product weight (kg): il peso usato per i prodotti senza peso, nelle tariffe USPS, nei limiti di peso e nelle fasce di peso. Predefinito: 0.5.

Prezzi fissi (prezzi nella valuta del negozio; usati quando non viene inserita alcuna chiave API e come riserva quando USPS non restituisce una tariffa: API non disponibile, chiavi errate, nessun servizio o una destinazione senza codice ZIP statunitense; lascia vuoti entrambi i campi per nascondere il metodo in questo caso)

Country prices: prezzi per paese di destinazione 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 (1–2 kg), M (2–3 kg), L (3–5 kg) e XL (oltre 5 kg). Una fascia vuota o 0 usa Price. La riga * Default si applica a qualsiasi altro paese. I valori che non sono numeri vengono cancellati con un messaggio.

Fallback cost: un prezzo fisso quando non corrisponde alcun prezzo per paese. Lascialo vuoto per nascondere il metodo in questo caso.

Fixed price is: Per order addebita il prezzo una sola volta. Per item (each item priced by its own weight x quantity) valuta ogni articolo in base al proprio peso (il peso predefinito se non ne ha) e lo moltiplica per la quantità. Le tariffe USPS in tempo reale vengono sempre richieste per l'intero pacco.

Condizioni

Free shipping from: il subtotale del carrello da cui questo metodo è gratuito. In tal caso non viene inviata alcuna richiesta a USPS. Lascialo vuoto per non offrire mai la spedizione gratuita.

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

Min weight (kg): il peso minimo del carrello perché questo metodo appaia. 0 significa nessun limite.

Max weight (kg): il metodo viene nascosto sopra questo peso del carrello. Predefinito: 30. USPS accetta fino a 70 lb (31,7 kg). 0 significa nessun limite.

Excluded 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 anche senza averlo aggiunto a una zona di spedizione.

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

Avanzate

Debug log: registra le richieste API e il calcolo delle tariffe in WooCommerce > Status > Logs, origine vfd-usps. Gli errori API vengono sempre registrati, anche con questa opzione disattivata. Chiavi, token e indirizzi dei clienti non vengono mai registrati.

Remove data on uninstall: se attiva, eliminando il plugin vengono rimosse tutte le sue impostazioni e i metodi nelle zone. La disattivazione 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 escluse. Se si applica la spedizione gratuita, il metodo viene mostrato con prezzo 0 e non viene inviata alcuna richiesta a USPS.

Il plugin ottiene un token OAuth da USPS e lo conserva fino alla scadenza. Un token rifiutato da USPS viene rinnovato e la richiesta ripetuta. Per le destinazioni negli Stati Uniti e nei loro territori (inclusi Porto Rico, Isole Vergini americane e Guam) interroga la Domestic Prices API e richiede il codice ZIP a 5 cifre del cliente. Per gli altri paesi interroga la International Prices API con paese e codice postale.

La richiesta contiene il codice ZIP di partenza, il peso del carrello in libbre, la misura del pacco in pollici e il tipo di prezzo. I pacchi oltre 70 lb ricevono i prezzi fissi. Il cliente vede un'opzione con il servizio selezionato più economico, convertito nella valuta del tuo negozio.

Ogni tariffa è memorizzata nella cache per 1 ora. Una tariffa non riuscita viene ricordata per 10 minuti. Dopo un timeout, un errore del server, un limite di richieste o chiavi rifiutate, USPS non viene interrogato per 5 minuti. Il timeout HTTP è di 10 secondi. Disattivando il plugin vengono cancellati il token e le tariffe in cache.

Se USPS non restituisce una tariffa, il prezzo viene preso da Country prices e poi da Fallback cost. Se nessuno dei due si applica, il metodo viene nascosto. Il cliente non vede mai i testi di errore di USPS.

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 affrancatura o etichette di spedizione, non prenota ritiri, non traccia i pacchi e non permette al cliente di scegliere un ufficio postale o un punto di ritiro. Mostra un'unica opzione, non più servizi USPS. Non c'è confezionamento in scatole: il carrello viene quotato come un unico pacco. Assicurazione e altri servizi extra non sono inclusi.

Ordini

Per una tariffa in tempo reale, la riga di spedizione dell'ordine salva il USPS service, per esempio USPS Ground Advantage. Il gestore del negozio lo vede nella schermata di amministrazione dell'ordine.

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 USPS. 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 per il dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, USPS non viene mostrato ai clienti al checkout. I gestori 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. Sulla pagina Plugins e sulle pagine di WooCommerce compare un promemoria. Gli ordini esistenti non sono interessati.

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

Risoluzione dei problemi

USPS non compare al checkout: verifica 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, il Minimum subtotal e le Excluded shipping classes. Senza chiavi USPS funzionanti, il metodo richiede un prezzo fisso (Country prices o Fallback cost).

Le tariffe in tempo reale non compaiono: controlla gli avvisi in cima alla pagina delle impostazioni. Attiva Debug log e apri WooCommerce > Status > Logs, origine vfd-usps. Vi vengono registrati chiavi errate, ambiente sbagliato e messaggi di errore USPS. Le tariffe nazionali richiedono il codice ZIP a 5 cifre del cliente.

Il mio negozio non usa USD: USPS quota solo in USD. Inserisci lo USD exchange rate. Senza di esso la tariffa in tempo reale non viene usata e al suo posto viene mostrato il prezzo fisso.

Uno User ID di Web Tools non funziona: la vecchia API Web Tools è stata disattivata. Crea un'app nello USPS Developer Portal e usa il suo Consumer Key e Consumer Secret.

Le tariffe sembrano obsolete dopo una modifica: la cache viene cancellata al salvataggio delle impostazioni. Puoi anche fare clic su Clear cached USPS token and rates.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per 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

Disattivare il plugin conserva le impostazioni e cancella solo il token e le tariffe in cache. Per rimuoverlo, disattivalo ed eliminalo dalla pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin, così come il token e le tariffe in cache, vengono sempre rimossi. Impostazioni e metodi delle zone vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano disponibili per una reinstallazione successiva. Gli ordini esistenti mantengono le loro righe di spedizione.

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