VibeFox USPS for PrestaShop — Guida
Requisiti
PrestaShop: da 8.0 a 9.x.
PHP: 8.0 o successivo. Il modulo non si installa con versioni precedenti di PHP.
App nello USPS Developer Portal (solo per le tariffe in tempo reale): accedi allo USPS Developer Portal (developers.usps.com) con un account aziendale USPS gratuito, crea un'app e copia il suo Consumer Key e il suo Consumer Secret. Il modulo usa le API USPS attuali con OAuth 2.0. USPS ha chiuso la vecchia API Web Tools (User ID e XML) il 25 gennaio 2026, quindi un Web Tools User ID non funziona più. Senza chiavi vengono usati solo i prezzi fissi.
Ship-from ZIP code: le tariffe in tempo reale richiedono 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. Nel back office vai su Modules > Module Manager e clicca su Upload a module. Scegli il file ZIP del modulo.
2. Al termine del caricamento clicca su Configure, oppure trova più tardi VibeFox USPS nell'elenco dei moduli e clicca su Configure.
3. Inserisci la chiave di licenza VibeFox in License key, nel blocco licenza in cima alla pagina Configure, e clicca su Activate (vedi Chiave di licenza).
4. Inserisci il Consumer Key e il Consumer Secret, lo Ship from ZIP code a 5 cifre e scegli i servizi. Se la valuta predefinita del negozio non è USD, inserisci lo USD exchange rate. Facoltativamente, inserisci i prezzi fissi come riserva. Clicca su Save.
All'installazione il modulo crea il corriere USPS con il testo dei tempi di consegna Delivery by USPS. 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 dimensione in Shipping > Carriers. Non impostare lì i prezzi: il prezzo arriva sempre dal modulo.
Configurazione
Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox USPS > Configure. Valgono per tutte le zone del corriere. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella anche il token USPS e le tariffe in cache.
Un valore non valido non viene salvato: resta quello precedente e un errore indica il campo, mentre gli altri campi vengono salvati. Gli avvisi in cima alla pagina ti segnalano quando è impostata una sola delle chiavi, quando non ci sono chiavi né prezzi fissi (il corriere allora non viene mai mostrato), quando manca il codice ZIP di partenza, quando non è selezionato alcun servizio, quando manca il tasso di cambio USD, quando l'ambiente di test è attivo, quando l'unità di peso o di dimensione del negozio è sconosciuta (impostala in International > Localization, Local units) o quando il corriere USPS è stato eliminato.
Generale
Enable USPS shipping: attiva o disattiva il corriere. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.
Name: il nome del corriere mostrato al cliente al checkout. Predefinito: USPS. Obbligatorio, fino a 64 caratteri.
Tax status: la regola fiscale del corriere. Le tariffe USPS non includono le tasse. Scegli una regola fiscale per aggiungere l'imposta sulla spedizione, oppure None se la spedizione non è tassata.
API USPS (tariffe in tempo reale)
Consumer Key: il Consumer Key (client_id) della tua app sviluppatore USPS.
Consumer Secret: il Consumer Secret (client_secret) della stessa app. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per cambiarlo. Svuotare il Consumer Key elimina anche il segreto salvato.
Test environment: usa lo USPS Testing Environment for Mailers (apis-tem.usps.com). Solo per le app che vi hanno accesso. Lascialo disattivato per tariffe reali (apis.usps.com). Predefinito: disattivato.
Prices: quali tariffe USPS vengono usate.
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. Predefinito: USPS Ground Advantage, Priority Mail e First-Class Package International Service. Se non è selezionato alcun servizio, le tariffe in tempo reale non vengono usate.
USD exchange rate: le tariffe USPS sono in USD. Se la valuta predefinita del negozio non è USD, inserisci il prezzo di 1 USD in quella valuta, 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 predefinita è USD. Deve essere maggiore di 0.
Cache: il pulsante Clear cached USPS token and rates svuota subito la cache. Le tariffe sono memorizzate per 1 ora, una tariffa fallita per 10 minuti. Dopo un timeout, un errore del server, un limite di richieste o chiavi rifiutate, USPS non viene interrogato per 5 minuti.
Spedizione e pacco (le tariffe USPS dipendono dal codice ZIP di partenza, dal peso e dalla dimensione del pacco; il carrello viene quotato come un unico pacco, e i pacchi oltre 70 lb usano i prezzi fissi)
Ship from ZIP code: il codice ZIP statunitense a 5 cifre da cui vengono spediti i pacchi. Un ZIP+4 viene troncato a 5 cifre. Altri valori vengono rifiutati con un messaggio.
Box size: dimensioni facoltative della scatola nell'unità di misura del negozio, per esempio 30x20x15. Lascialo vuoto per ricavare la dimensione dalle dimensioni dei prodotti: la lunghezza maggiore, la larghezza maggiore e le altezze sovrapposte. Se un prodotto non ha dimensioni, viene usata una scatola di 10 x 8 x 4 pollici.
Default product weight: il peso in kg 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 predefinita del negozio, tasse escluse; usati quando non sono inserite chiavi 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 corriere in tal caso)
Country prices: prezzi per paese di destinazione e peso del carrello. Clicca 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 (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 (any other country) si applica a qualsiasi altro paese. Una riga di paese senza alcun prezzo manda quel paese a Fallback cost. I valori che non sono numeri vengono cancellati con un messaggio.
Fallback cost: un prezzo fisso quando nessun prezzo per paese corrisponde. Lascialo vuoto per nascondere il corriere in quel caso.
Fixed price is: Per order addebita il prezzo una sola volta, in base al peso dell'intero carrello. Per item (each item priced by its own weight x quantity) valuta ogni prodotto in base al peso di un'unità (il peso predefinito se non ne ha uno) e lo moltiplica per la quantità. Le tariffe USPS in tempo reale vengono sempre calcolate per l'intero pacco.
Condizioni
Free shipping from: il subtotale del carrello (dopo sconti, prima delle tasse) da cui questo corriere è gratuito. In quel caso non viene inviata alcuna richiesta a USPS. Lascialo vuoto per non offrire mai la spedizione gratuita.
Minimum subtotal: mostra il corriere solo se il subtotale del carrello è almeno questo importo. Lascialo vuoto per mostrarlo sempre.
Min weight: il peso minimo del carrello in kg perché questo corriere compaia. 0 significa nessun limite.
Max weight: il corriere viene nascosto sopra questo peso del carrello in kg. Predefinito: 30. USPS accetta fino a 70 lb (31,7 kg). 0 significa nessun limite. Se Min weight è maggiore di Max weight, viene mostrato un errore e restano i limiti precedenti.
Disponibilità senza zone di spedizione
Ignore shipping zones: offre il corriere in tutte le zone per i paesi indicati sotto. Il salvataggio collega il corriere a tutte le zone del negozio, anche a quelle create in seguito. Disattivandolo, il corriere riottiene le sue zone precedenti.
Countries: i paesi di destinazione per questa modalità. Lascialo vuoto per consentire tutti i paesi verso cui il negozio spedisce. Questo campo viene usato solo quando Ignore shipping zones è attivo.
Avanzate
Debug log: registra le richieste API e il calcolo delle tariffe in logs/vfd_usps_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. Chiavi, token e indirizzi dei clienti non vengono mai registrati.
Log: mostra la dimensione e le ultime voci del log. Clicca su Clear log per svuotarlo.
Remove data on uninstall: se attivo, disinstallando il modulo vengono eliminate le impostazioni USPS, il corriere, i servizi salvati degli ordini, le tariffe in cache e i log. Se disattivo, tutto viene conservato per una reinstallazione.
Come funziona al checkout
Nella fase di spedizione PrestaShop chiede al modulo il prezzo USPS. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nel subtotale. Il modulo controlla prima le condizioni: paesi consentiti (con Ignore shipping zones), peso del carrello e subtotale minimo. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata alcuna richiesta a USPS.
Il modulo ottiene da USPS un token OAuth e lo conserva fino a poco prima della scadenza. Un token rifiutato da USPS viene rinnovato e la quotazione ripetuta. Per le destinazioni negli Stati Uniti e nei loro territori (Porto Rico, Isole Vergini americane, Guam, Samoa americane, Isole Marianne settentrionali, Stati Federati di Micronesia, Isole Marshall e Palau) interroga l'API Domestic Prices e richiede il codice ZIP a 5 cifre del cliente. Per gli altri paesi interroga l'API International Prices con paese e codice postale.
La richiesta contiene lo ZIP di partenza, il peso del carrello in libbre, la dimensione del pacco in pollici e il tipo di prezzo. I pacchi oltre 70 lb ricevono i prezzi fissi. Il cliente vede un'unica opzione con il servizio selezionato più economico, convertita da USD nella valuta predefinita del negozio e poi mostrata nella valuta del carrello del cliente.
Ogni quotazione è memorizzata nella cache per 1 ora. Una quotazione fallita 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.
Se USPS non restituisce una tariffa, il prezzo viene preso da Country prices, poi da Fallback cost. Se nessuno dei due si applica, il corriere viene nascosto. Il cliente non vede mai i testi di errore di USPS. Il motivo viene scritto nel log.
Se modifichi il corriere in Shipping > Carriers dopo che ha degli ordini, PrestaShop lo salva come una nuova versione del corriere. Il modulo segue automaticamente la nuova versione.
Il modulo 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
Quando un ordine viene effettuato con il corriere USPS, il modulo salva come è stato determinato il prezzo di spedizione. La pagina dell'ordine nel back office mostra un blocco USPS con il USPS service (per una tariffa in tempo reale, per esempio USPS Ground Advantage) e il Price source: USPS live rate, Fixed price o Free shipping.
Chiave di licenza
Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox USPS è il primo blocco della pagina Modules > Module Manager > VibeFox USPS > 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 di essi ci sono la riga Product: presta-shipping-usps 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 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 aver cambiato l'indirizzo del negozio, o dopo aver liberato un posto per il 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 posto per il dominio. Liberalo nel tuo account vibefox.net.
Senza una chiave attiva, il corriere USPS non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Lo storefront di PrestaShop non sa che sei connesso al back office, quindi il corriere è nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non puoi provarlo 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 il rinnovo. Lo stato viene controllato di nuovo automaticamente mentre lavori nel back office: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve alcun cron job. Disinstallare o reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.
Risoluzione dei problemi
USPS non compare al checkout: verifica che la licenza sia attiva e che Enable USPS shipping sia attivo. In Shipping > Carriers verifica che il corriere copra la zona del paese del cliente e il gruppo del cliente, oppure attiva Ignore shipping zones e controlla Countries. Controlla i limiti di peso e il Minimum subtotal. Senza chiavi USPS funzionanti, il corriere ha bisogno di un prezzo fisso (Country prices o Fallback cost). I prodotti possono anche essere limitati a determinati corrieri nella pagina del prodotto.
Le tariffe in tempo reale non compaiono: controlla gli avvisi in cima alla pagina del modulo. Attiva Debug log, ricarica il checkout e guarda il campo Log. Lì vengono registrate le chiavi errate, l'ambiente sbagliato e i messaggi di errore di USPS. Le tariffe nazionali richiedono il codice ZIP a 5 cifre del cliente.
Il mio negozio non è in 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.
Un Web Tools User ID non funziona: la vecchia API Web Tools è stata chiusa. Crea un'app nello USPS Developer Portal e usa il suo Consumer Key e il suo Consumer Secret.
Le tariffe sembrano vecchie dopo una modifica: la cache viene svuotata quando salvi le impostazioni. Puoi anche cliccare su Clear cached USPS token and rates.
La pagina dice che il corriere USPS non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Reimposta il modulo in Modules > Module Manager per ricrearlo.
Disinstallazione
Vai su Modules > Module Manager, apri il menu accanto a VibeFox USPS e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. Anche il token e le tariffe in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini conservano la cronologia) e vengono rimosse le impostazioni, i servizi salvati degli ordini e il log. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni vengono conservate. Reinstallando il modulo, oppure con Reset, il corriere salvato riprende il suo stato precedente: un corriere attivo torna attivo, uno disattivato resta disattivato.
USPS è un marchio del suo rispettivo titolare. Questo modulo non è affiliato a USPS né approvato da USPS.