VibeFox USPS for OpenCart — Guida

Requisiti

OpenCart: 3.0.x (testato con la 3.0.5.0) o 4.0.2 e successive (testato con la 4.1.0.3).

PHP: 8.0 o successivo, con l'estensione cURL.

App nel portale sviluppatori USPS (solo per tariffe in tempo reale): accedi al portale sviluppatori USPS (developers.usps.com) con un account business USPS gratuito, crea un'app e copia il suo Consumer Key e il suo Consumer Secret. L'estensione usa le API USPS attuali con OAuth 2.0. Il vecchio Web Tools User ID non funziona con esse. Senza chiavi vengono usati solo i prezzi fissi.

Codice ZIP di spedizione: 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

Il download è un unico file ZIP con i pacchetti per entrambe le versioni di OpenCart. Decomprimilo sul tuo computer. Contiene README.txt, il pacchetto per OpenCart 3 vfd_usps-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_usps.ocmod.zip. Installa solo il pacchetto per la tua versione di OpenCart. La chiave di licenza è la stessa per entrambe le versioni.

OpenCart 3

1. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_usps-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non devi aggiornare Extensions > Modifications. Invece dell'Installer, puoi copiare il contenuto della cartella upload di questo pacchetto nella cartella principale del tuo negozio.

2. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox USPS e clicca su Install (il pulsante verde +).

3. Clicca su Edit (il pulsante con la matita) per aprire la pagina delle impostazioni.

4. Inserisci la tua chiave di licenza VibeFox in License key nel blocco della licenza in cima alla pagina Edit e clicca su Activate (vedi License key).

5. Inserisci il Consumer Key e il Consumer Secret, il Ship from ZIP code a 5 cifre e scegli i Services. Se la valuta predefinita del tuo negozio non è USD, inserisci lo USD exchange rate.

6. Facoltativamente inserisci i prezzi fissi come alternativa, attiva Enable USPS shipping e clicca su Save.

OpenCart 4

1. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_usps.ocmod.zip. Non rinominare il file: OpenCart 4 ricava il codice dell'estensione dal nome del file, e un pacchetto rinominato non funziona.

2. Il pacchetto compare nell'elenco delle estensioni installate, nella stessa pagina. Clicca su Install (il pulsante verde +) accanto ad esso.

3. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox USPS, clicca su Install (il pulsante verde +), poi su Edit (il pulsante con la matita).

4. Inserisci la chiave di licenza e le impostazioni come nei passaggi da 4 a 6 per OpenCart 3. La pagina delle impostazioni e i suoi campi sono gli stessi in entrambe le versioni.

Dopo l'installazione il metodo resta disattivato finché non attivi Enable USPS shipping e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono usate di nuovo le impostazioni USPS che hai conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox USPS > Edit. Le sezioni sono elencate a sinistra. Un pulsante Save in fondo salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella il token e le tariffe USPS in cache. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni, svuotare la cache o svuotare il log.

Un valore non valido non viene salvato: la pagina indica il campo, ripristina il valore precedente e mostra The other settings were saved. Questo vale per un nome vuoto, troppo lungo o con caratteri vietati, un numero negativo o non numerico, un codice ZIP che non ha 5 cifre, una dimensione di scatola errata, un Min weight (kg) superiore a Max weight (kg) (entrambi i limiti mantengono i loro valori), un ordine di visualizzazione che non è un numero intero, e una classe fiscale o una zona geografica sconosciute. I prezzi per paese che non sono numeri vengono cancellati ed elencati. Gli avvisi sopra le impostazioni ti indicano quando è impostata solo una delle due chiavi, quando non ci sono chiavi né prezzi fissi (in tal caso il metodo non viene mai mostrato), quando manca il codice ZIP, quando non è selezionato alcun servizio, quando manca il tasso di cambio USD, quando l'ambiente di test è attivo o quando l'unità di peso o di lunghezza del negozio non è riconosciuta dall'estensione.

Generale

Le impostazioni si applicano a tutte le zone geografiche. USPS viene offerto come un'unica opzione di spedizione al checkout.

Enable USPS shipping: offre la spedizione USPS al checkout. Predefinito: disattivato.

Name: il nome del metodo di spedizione mostrato al cliente al checkout. Predefinito: USPS. Obbligatorio, massimo 64 caratteri, senza < > ; = # { }.

Tax class: la classe fiscale del costo di spedizione. Le tariffe USPS non includono le tasse. No tax (predefinito) significa che la spedizione non è tassata.

Sort order: la posizione di USPS tra i metodi di spedizione al checkout. Un numero intero.

API USPS (tariffe in tempo reale)

Consumer Key: il Consumer Key (client_id) della tua app sviluppatore USPS. Svuotarlo rimuove anche il Consumer Secret salvato.

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. Clearing the Consumer Key removes it too. Inserisci un nuovo valore solo se vuoi cambiarlo.

Test environment: usa l'USPS Testing Environment per i mittenti. Solo per le app che vi hanno accesso. Lascialo disattivato per i prezzi reali. Predefinito: disattivato.

Prices: quale listino prezzi USPS viene usato.

Services: i servizi USPS che possono essere quotati. Viene mostrato il servizio selezionato più economico che USPS offre per il pacco. Scegli tra USPS Ground Advantage, Priority Mail / Priority Mail International, Priority Mail Express / Priority Mail Express International, First-Class Package International Service, Media Mail (books and media only) e Library Mail (libraries and schools only). Predefinito: Ground Advantage, Priority Mail e First-Class Package International. Le tariffe Flat Rate, Cubic, Hold for Pickup e Sunday non vengono mai usate. Se non è selezionato alcun servizio, le tariffe in tempo reale non vengono usate.

USD exchange rate: i prezzi USPS sono in USD. Se la valuta predefinita del tuo negozio non è USD, inserisci il prezzo di 1 USD nella tua valuta, per esempio 0.92. Deve essere maggiore di 0. Senza di esso le tariffe in tempo reale non vengono usate e si applicano i prezzi fissi. Se la valuta del tuo negozio è USD, non serve. Il tasso non viene aggiornato automaticamente.

Cache: le quotazioni sono in cache per 1 ora e una quotazione 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. Clicca su Clear cached USPS token and rates per svuotare subito la cache.

Spedizione e pacco (le tariffe USPS dipendono dal codice ZIP di partenza, dal peso e dalla dimensione del pacco; il carrello è quotato come un unico pacco)

Ship from ZIP code: il codice ZIP statunitense a 5 cifre da cui vengono spediti i pacchi. Lo ZIP+4 viene troncato a 5 cifre. OpenCart non ha un codice postale del negozio, quindi inseriscilo qui.

Box size (L x W x H): dimensioni facoltative della scatola nell'unità di lunghezza del tuo negozio (indicata nel nome del campo), per esempio 30x20x15. Lascia vuoto per usare le dimensioni del prodotto: la lunghezza maggiore, la larghezza maggiore e le altezze sovrapposte. I prodotti senza dimensioni sono quotati come una scatola di 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. Vuoto significa anche 0,5 kg.

Prezzi fissi (prezzi nella valuta predefinita del tuo negozio, tasse escluse; usati quando non sono inserite chiavi API e come alternativa quando USPS non restituisce alcuna tariffa; lascia vuoti entrambi per nascondere il metodo in quel caso)

Country prices: prezzi per paese di destinazione e peso del carrello. Clicca su Add country per aggiungere una riga e sul pulsante di rimozione per eliminarne una. Le fasce di peso sono 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. * Default (any other country) si applica a tutti gli altri paesi.

Fallback cost: un prezzo fisso quando nessun prezzo per paese corrisponde. Lascialo vuoto per nascondere il metodo in quel caso.

Fixed price is: Per order (predefinito) addebita il prezzo una sola volta, in base al peso dell'intero carrello. Per item (each item priced by its own weight x quantity) prezza ogni prodotto in base al proprio peso e lo moltiplica per la quantità. Le tariffe USPS in tempo reale sono sempre quotate per l'intero pacco.

Condizioni

Free shipping from: il subtotale dei prodotti che richiedono spedizione (dopo il coupon, prima delle tasse) a partire dal quale questo metodo è gratuito. In tal caso non viene inviata alcuna richiesta a USPS. Lascia vuoto per non offrire mai la spedizione gratuita.

Minimum subtotal: mostra il metodo solo quando il subtotale dei prodotti che richiedono spedizione (dopo il coupon, prima delle tasse) è almeno pari a questo importo. Lascia vuoto per mostrarlo sempre.

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

Max weight (kg): il metodo è nascosto sopra questo peso del carrello. Predefinito: 30. Vuoto significa 30 kg, 0 significa nessun limite. USPS accetta fino a 70 lb (31,7 kg): i pacchi più pesanti ricevono i prezzi fissi.

Geo zone: offri USPS solo per gli indirizzi in questa zona geografica. All zones (predefinito) significa nessun limite. Le zone geografiche si gestiscono in System > Localisation > Geo Zones. Non usato con Ignore shipping zones.

Disponibilità senza zone di spedizione

Ignore shipping zones: non verifica la zona geografica. Il metodo viene offerto per i paesi indicati di seguito.

Countries: i paesi di destinazione per questa modalità. Lascia vuoto per consentire tutti i paesi. Questo campo viene usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: registra le richieste API e il calcolo delle tariffe in storage/logs/vfd_usps_debug.log.php (su OpenCart 4 system/storage/logs/vfd_usps_debug.log.php). Il file non può essere letto dal web. Gli errori API vengono sempre registrati, anche quando questa opzione è disattivata. Chiavi, token, codici ZIP e indirizzi dei clienti non vengono mai registrati. Quando il file raggiunge 5 MB viene spostato in vfd_usps_debug.old.log.php e si avvia un nuovo log.

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

Remove data on uninstall: se attivo, la disinstallazione dell'estensione elimina le impostazioni USPS e il log. Le tariffe in cache vengono sempre rimosse. I servizi USPS degli ordini effettuati vengono sempre conservati. Se disattivo, le impostazioni vengono conservate per una reinstallazione.

Importazione / Esportazione

Export: clicca su Download JSON per salvare le impostazioni in un file JSON. Il Consumer Secret non viene esportato.

Import: incolla il JSON esportato in precedenza e clicca su Import per ripristinare le impostazioni, per esempio su un altro negozio. I valori vengono controllati come in un normale salvataggio. Il Consumer Secret salvato viene mantenuto.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo USPS. Se è impostata una Geo zone e l'indirizzo è al di fuori di essa, USPS non viene offerto (con Ignore shipping zones decide invece l'elenco dei paesi). Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri prodotti non aggiungono peso e non sono inclusi nel subtotale. Buoni regalo, punti fedeltà e crediti del negozio non vengono considerati. L'estensione controlla poi le condizioni: peso del carrello e subtotale minimo. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata alcuna richiesta a USPS.

L'estensione ottiene un token OAuth da USPS e lo conserva fino a poco prima della scadenza. Per le destinazioni negli Stati Uniti e nei suoi territori (Porto Rico, Isole Vergini americane, Guam, Samoa americane, Isole Marianne settentrionali, Micronesia, Isole Marshall e Palau) richiede le tariffe nazionali e ha bisogno del codice ZIP a 5 cifre del cliente: senza di esso non viene fatta alcuna richiesta. Per gli altri paesi richiede le tariffe internazionali.

La richiesta contiene il codice ZIP di spedizione, il peso del carrello, la dimensione del pacco 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. Il prezzo in USD viene convertito nella tua valuta predefinita, arrotondato alle sue cifre decimali e mostrato nella valuta del cliente con la tassa della Tax class selezionata.

Ogni quotazione è in 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 alcuna tariffa, il prezzo viene preso da Country prices e poi da Fallback cost. Se nessuno dei due si applica, il metodo è nascosto. Il cliente non vede mai i testi di errore di USPS. Il motivo viene scritto nel log di debug.

L'estensione calcola solo le tariffe. Non acquista francobolli 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 una sola opzione, non più servizi USPS. Non c'è imballaggio in scatole: il carrello è quotato come un unico pacco. Assicurazione e altri servizi extra non sono inclusi.

Su OpenCart 4 il cliente clicca su Choose nel blocco del metodo di spedizione della pagina di checkout e sceglie USPS nella finestra Shipping method options. Il metodo funziona come su OpenCart 3.

Ordini

Quando un ordine viene effettuato con USPS, l'estensione salva come è stato determinato il prezzo di spedizione. La pagina dell'ordine in Sales > Orders mostra un pannello USPS con il USPS service (per una tariffa in tempo reale, per esempio USPS Ground Advantage), la Price source (USPS live rate, Fixed price o Free shipping) e il Calculated price (excl. tax). Questi valori vengono salvati quando l'ordine viene effettuato.

OpenCart 4 mantiene un unico ordine per il checkout e lo aggiorna ogni volta che il cliente conferma di nuovo. I valori salvati vengono aggiornati insieme ad esso. Se il cliente passa a un altro metodo di spedizione, vengono rimossi dall'ordine. Su OpenCart 4 il pannello USPS è mostrato sopra la sezione History.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza License — VibeFox USPS è il primo blocco di Extensions > Extensions > Shipping > VibeFox USPS > Edit, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Poi 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: opencart-shipping-usps e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo gli utenti amministratori con il permesso Modify per l'estensione possono cambiare la chiave. I testi del blocco seguono la lingua dell'amministrazione (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 oppure 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, l'estensione continua a funzionare con l'ultimo stato noto.

Una chiave funziona su un solo dominio: l'indirizzo del negozio nella configurazione di OpenCart. Rimuovere la chiave dal negozio non libera il suo posto per il dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, USPS non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Un utente amministratore che ha effettuato l'accesso all'amministrazione nello stesso browser vede ancora il metodo nel negozio, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e testare l'estensione prima di acquistare una chiave. Su OpenCart 4 questa anteprima non è disponibile: il negozio non vede l'accesso dell'amministratore, quindi senza una chiave attiva il metodo è nascosto a tutti. Dopo aver aperto una volta la pagina Edit, nella Dashboard dell'amministrazione compare un promemoria. Chiudilo con × per nasconderlo per 7 giorni. Gli ordini esistenti non sono interessati.

Quando una licenza scade, l'estensione continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene controllato di nuovo automaticamente quando apri la Dashboard dell'amministrazione o la pagina Edit: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve alcun cron job. La disinstallazione dell'estensione rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

USPS non appare al checkout: verifica che la licenza sia attiva e che Enable USPS shipping sia attivo. Controlla la Geo zone, oppure attiva Ignore shipping zones e controlla Countries. Controlla i limiti di peso e il Minimum subtotal. Senza chiavi USPS funzionanti il metodo richiede un prezzo fisso (Country prices o Fallback cost). Verifica che i prodotti abbiano Requires Shipping impostato su Yes.

Le tariffe in tempo reale non appaiono: controlla gli avvisi in cima alla pagina Edit: entrambe le chiavi, il codice ZIP, almeno un servizio e, per i negozi non in USD, il tasso di cambio. I clienti statunitensi devono inserire un codice ZIP. Attiva Debug log, ricarica il checkout e controlla il campo Log nella pagina dell'estensione.

Le tariffe non sono prezzi reali: disattiva Test environment.

La pagina avvisa dell'unità di peso o di lunghezza: senza una classe di peso con unità kg, le unità di peso sconosciute vengono lette come kg. Aggiungi una classe di peso in kg in System > Localisation > Weight Classes. Un'unità di lunghezza sconosciuta del negozio viene trattata come cm. Usa cm, mm, m o in come classe di lunghezza del negozio (System > Settings, scheda Option).

Le tariffe sembrano obsolete dopo una modifica: clicca su Save nella pagina dell'estensione o su Clear cached USPS token and rates.

La pagina mostra "Warning: You do not have permission to modify VibeFox USPS!": il tuo gruppo di utenti amministratori potrebbe poter solo visualizzare le impostazioni. Dai al gruppo il permesso di modifica per extension/shipping/vfd_usps (OpenCart 3) o extension/vfd_usps/shipping/vfd_usps (OpenCart 4) in System > Users > User Groups.

Per gli sviluppatori: l'indirizzo dell'API USPS può essere sostituito con l'impostazione vfd_usps_api_url (per i test); non ha un campo nella pagina delle impostazioni.

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox USPS. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable USPS shipping, Sort order, Tax class e Geo zone. Il token e le tariffe USPS in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, vengono eliminate anche le impostazioni USPS e il log di debug. Se è disattivo, le altre impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. I dati USPS degli ordini effettuati non vengono mai rimossi, e gli ordini esistenti conservano il loro metodo di spedizione e il loro costo.

Su OpenCart 4, per rimuovere anche i file dell'estensione, vai su Extensions > Installer dopo la disinstallazione e clicca su Uninstall (il pulsante arancione −) accanto a VibeFox USPS nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per rimuovere il pacchetto caricato.

USPS è un marchio di proprietà del suo titolare. Questa estensione non è affiliata né approvata da USPS.