VibeFox UPS for OpenCart — Guida

Requisiti

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

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

Applicazione nel UPS Developer Portal (solo per le tariffe in tempo reale): accedi al UPS Developer Portal (developer.ups.com), crea un'applicazione con il prodotto «Rating», collega il tuo account UPS e copia il Client ID e il Client Secret. L'estensione usa OAuth 2.0. Non servono Access Key, nome utente o password. Per le tariffe negoziate ti serve anche il numero di account UPS di 6 caratteri. Senza credenziali vengono usati solo i prezzi fissi.

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_ups-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_ups.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_ups-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non serve aggiornare Extensions > Modifications. In alternativa all'Installer, puoi copiare il contenuto della cartella upload di questo pacchetto nella cartella radice del negozio.

2. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox UPS 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 nel campo License key, nel blocco di licenza in cima alla pagina Edit, e clicca su Activate (vedi License key).

5. Inserisci il Client ID e il Client Secret, il tuo numero di account UPS (per le tariffe negoziate) e l'indirizzo Ship from: il codice postale e, per gli Stati Uniti e il Canada, la sigla dello stato di 2 lettere.

6. Se la valuta del tuo account UPS è diversa dalla valuta predefinita del negozio, inserisci la UPS account currency e l'Exchange rate.

7. Facoltativamente, inserisci dei prezzi fissi come alternativa, attiva Enable UPS shipping e clicca su Save.

OpenCart 4

1. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_ups.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 UPS, 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 7 per OpenCart 3. La pagina delle impostazioni e i suoi campi sono uguali in entrambe le versioni.

Dopo l'installazione il metodo resta disattivato finché non attivi Enable UPS shipping e salvi. Il paese di Ship from parte come il paese del tuo negozio. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni UPS mantenute.

Configurazione

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

Se il nome, la classe fiscale, l'ordinamento o la zona geografica non sono validi, non viene salvato nulla e la pagina mostra il motivo, per esempio Enter a valid name (64 characters max, without < > ; = # { }). Nothing was saved. I numeri non validi (per esempio negativi), una dimensione del collo errata, un Min weight (kg) superiore a Max weight (kg) e le celle di prezzo che non sono numeri vengono segnalati al salvataggio: quel campo mantiene il vecchio valore e il resto viene salvato. Gli avvisi sopra le impostazioni indicano quando è impostato solo uno tra Client ID e Client Secret, quando non ci sono credenziali né prezzi fissi (in tal caso il metodo non viene mai mostrato), quando manca il codice postale o lo stato di spedizione, quando si scelgono tariffe di account senza numero di account, quando manca il tasso di cambio, 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. UPS viene offerto come un'unica opzione di spedizione al checkout.

Enable UPS shipping: mostra o nasconde UPS al checkout. Predefinito: disattivato.

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

Tax class: la classe fiscale del costo di spedizione, oppure None (predefinito). Le tariffe UPS sono quotate senza tasse. Con una classe fiscale OpenCart aggiunge sopra la propria imposta sulla spedizione.

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

API UPS (tariffe in tempo reale)

Test mode: usa l'ambiente di test di UPS. Le tariffe di prova non sono prezzi reali. Disattivalo per le tariffe in tempo reale. Predefinito: disattivato.

Client ID: il Client ID della tua applicazione nel UPS Developer Portal. Svuotarlo elimina anche il Client Secret salvato.

Client Secret: il Client Secret della stessa applicazione. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per cambiarlo.

UPS account number: il tuo numero di spedizioniere UPS di 6 caratteri, per esempio A1B2C3. Necessario per le tariffe di account (negoziate), facoltativo per quelle pubblicate.

Rates: quali prezzi UPS vengono usati.

Measurement units: le unità inviate a UPS. Pesi e dimensioni del negozio vengono convertiti.

Residential delivery: quota gli indirizzi dei clienti come residenziali, con la maggiorazione residenziale di UPS. Disattivalo se spedisci soprattutto ad aziende. Predefinito: attivo.

Box size (L x W x H): dimensioni facoltative del collo nell'unità di lunghezza del tuo negozio (mostrata nel nome del campo), per esempio 30x20x15. UPS applica allora il peso volumetrico. Lascia vuoto per quotare solo per peso.

UPS account currency: UPS quota nella valuta del paese dell'account dello spedizioniere, per esempio USD per gli Stati Uniti, CAD per il Canada o EUR per l'area euro. Predefinito: USD.

Exchange rate: necessario solo quando la valuta dell'account UPS è diversa dalla valuta predefinita del negozio. Inserisci il prezzo di 1 unità della valuta dell'account nella tua valuta predefinita, per esempio 0.92. Senza di esso queste tariffe non vengono usate e si applicano i prezzi fissi. I tassi di cambio non vengono aggiornati automaticamente.

Cache: i token UPS sono memorizzati nella cache fino alla scadenza (al massimo la durata della cache di OpenCart), le tariffe per 1 ora, le richieste fallite per 5–10 minuti. Clicca su Clear cached UPS token and rates per svuotare subito la cache.

Ship from (l'indirizzo da cui UPS ritira i pacchi o in cui consegni i pacchi; usato per le tariffe in tempo reale)

Country: il paese da cui spedisci. Per impostazione predefinita è il paese del tuo negozio.

State / province code: la sigla di 2 lettere, obbligatoria per gli Stati Uniti e il Canada, per esempio NY, CA o ON. Viene inviata a UPS solo per questi due paesi.

City: la città da cui spedisci.

ZIP / postal code: il codice postale da cui spedisci. UPS lo richiede per quotare le tariffe. OpenCart non ha un codice postale del negozio, quindi inseriscilo qui.

Prezzi fissi (usati quando non sono inserite credenziali API e come alternativa quando UPS non restituisce una tariffa; lascia vuoti entrambi per nascondere il metodo in quel caso)

Country prices: prezzi nella valuta predefinita del negozio, senza tasse, per paese di destinazione. Clicca su Add country per aggiungere una riga e sul pulsante di rimozione per eliminarne una. * Default (all other countries) si applica a qualsiasi altro paese. Una colonna di peso (XS fino a 1 kg, S da 1 a 2 kg, M da 2 a 3 kg, L da 3 a 5 kg, XL oltre 5 kg) sostituisce Price per quel peso del carrello. Le celle vuote usano Price. 0 significa spedizione gratuita. Una riga di paese senza valore per il peso passa alla riga *. Le righe senza alcun prezzo non vengono salvate.

Fallback cost: un prezzo fisso nella valuta predefinita del negozio, quando nessun prezzo per paese corrisponde. Lascia 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 (il peso predefinito se non ne ha uno) e lo moltiplica per la quantità. Le tariffe UPS in tempo reale sono sempre quotate sul peso dell'intero carrello.

Condizioni

Free shipping from: il subtotale del carrello (prodotti che richiedono spedizione, dopo il coupon, prima delle tasse) da cui questo metodo è gratuito. In quel caso non viene inviata nessuna richiesta a UPS. Lascia vuoto per non offrire mai la spedizione gratuita.

Minimum subtotal: mostra il metodo solo quando il subtotale del carrello raggiunge almeno 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 viene nascosto sopra questo peso del carrello. Predefinito: 70, il limite di UPS per collo (70 kg / 150 lbs). 0 significa nessun limite, vuoto significa 70.

Default product weight (kg): il peso usato per i prodotti senza peso, nelle tariffe UPS, nelle colonne di peso e nei limiti di peso. Predefinito: 0.5. Vuoto significa anch'esso 0.5.

Geo zone: offri UPS 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 viene usato con Ignore shipping zones.

Disponibilità senza zone di spedizione

Ignore shipping zones: non verifica la zona geografica. Il metodo viene offerto nei paesi elencati qui sotto.

Countries: i paesi di destinazione per questa modalità. Lascia vuoto per usare tutti i paesi abilitati 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 storage/logs/vfd_upsx_debug.log.php (su OpenCart 4 system/storage/logs/vfd_upsx_debug.log.php). Il file non può essere letto dal web. Gli errori API vengono sempre registrati, anche con questa opzione disattivata. Credenziali, token e indirizzi dei clienti non vengono mai registrati. Quando il file raggiunge 5 MB viene spostato in vfd_upsx_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, disinstallare l'estensione elimina le impostazioni UPS, i token e le tariffe in cache e il log. I servizi UPS salvati con gli ordini vengono sempre conservati. Se disattivo, tutto viene mantenuto per una reinstallazione.

Importa / Esporta

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

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

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo UPS. Se è impostata una Geo zone e l'indirizzo è al di fuori, UPS 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 non aggiungono peso e non sono inclusi nel subtotale. Il subtotale è il prezzo di questi prodotti dopo lo sconto del coupon e prima delle tasse. Buoni regalo, punti fedeltà e credito del negozio non vengono considerati. Poi l'estensione verifica le condizioni: peso del carrello e subtotale minimo. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata alcuna richiesta a UPS.

L'estensione ottiene da UPS un token OAuth e lo conserva fino alla scadenza. Un token rifiutato da UPS viene rinnovato automaticamente e la richiesta viene ripetuta una volta. Poi chiede alla UPS Rating API tutti i servizi dal tuo indirizzo di spedizione all'indirizzo del cliente, per il carrello come un unico collo. Per i paesi in cui OpenCart richiede un codice postale, la richiesta attende che il cliente lo inserisca. Per le spedizioni dagli Stati Uniti verso il Canada o Porto Rico viene inviato il valore della merce, come richiesto da UPS.

Il cliente vede un'unica opzione con il servizio UPS più economico. Il prezzo viene calcolato nella valuta predefinita del negozio, arrotondato ai suoi decimali e mostrato nella valuta del cliente con la tassa della Tax class selezionata. UPS Access Point Economy non viene quotato, perché l'estensione non raccoglie un indirizzo di Access Point.

Ogni tariffa viene memorizzata nella cache per 1 ora. Una richiesta fallita viene ricordata per 10 minuti, una richiesta di token fallita per 5 minuti, così un'interruzione non rallenta ogni aggiornamento del checkout. Il timeout HTTP è di 15 secondi.

Se UPS non restituisce alcuna tariffa (API non disponibile, credenziali errate, nessun servizio, altra valuta senza tasso di cambio), 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 UPS. Il motivo viene scritto nel log di debug.

L'estensione calcola solo tariffe. Non offre la scelta di un punto UPS Access Point, non crea etichette o spedizioni UPS, non prenota ritiri e non traccia i pacchi. Mostra un'unica opzione, non più servizi UPS. Non c'è un confezionamento in colli: il carrello viene quotato come un unico collo. I tassi di cambio non sono automatici.

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

Ordini

Quando un ordine viene effettuato con una tariffa UPS in tempo reale, il servizio UPS viene salvato con l'ordine. La pagina dell'ordine in Sales > Orders mostra un pannello UPS con il UPS service, per esempio UPS Ground, e la Live rate (excl. tax). Questi valori vengono salvati quando l'ordine viene effettuato. Gli ordini con prezzo fisso o spedizione gratuita non hanno questo pannello.

OpenCart 4 mantiene un solo ordine per il checkout e lo aggiorna ogni volta che il cliente conferma di nuovo. Il servizio UPS salvato viene aggiornato insieme ad esso. Se il cliente passa a un altro metodo di spedizione, oppure il prezzo diventa un prezzo fisso o una spedizione gratuita, il servizio salvato viene rimosso dall'ordine. Su OpenCart 4 il pannello UPS è mostrato sopra la sezione History.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox UPS è il primo blocco di Extensions > Extensions > Shipping > VibeFox UPS > Edit, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopodiché 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-ups 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 seguito da una data. Dopo aver cambiato l'indirizzo del negozio, o dopo aver liberato uno slot di 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. Gestisci le tue licenze e i tuoi domini nel tuo account vibefox.net.

Senza una chiave attiva, UPS 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 provare 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 il rinnovo. Lo stato viene controllato di nuovo automaticamente quando apri la Dashboard o la pagina Edit dell'amministrazione: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta a settimana. Non serve alcun cron job. La disinstallazione dell'estensione rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

UPS does not appear at checkout: verifica che la licenza sia attiva e che Enable UPS shipping sia attivo. Controlla Geo zone, oppure attiva Ignore shipping zones e controlla Countries. Verifica i limiti di peso e Minimum subtotal. Senza credenziali UPS funzionanti il metodo ha bisogno di un prezzo fisso (Country prices o Fallback cost). Verifica che i prodotti abbiano Requires Shipping impostato su Yes.

Live rates do not appear: controlla gli avvisi in cima alla pagina Edit. Attiva il Debug log, ricarica il checkout e controlla il campo Log nella pagina dell'estensione. Mostra errori OAuth (controlla Client ID, Client Secret e Test mode), messaggi di errore di UPS e problemi di valuta.

The rate is in USD but the store is not: UPS restituisce le tariffe nella valuta dell'account dello spedizioniere. Imposta UPS account currency e l'Exchange rate. Senza tasso di cambio queste tariffe vengono ignorate e si usa il prezzo fisso.

«This measurement system is not valid for the selected country»: lascia Measurement units su Automatic (by ship-from country), oppure scegli le unità che UPS si aspetta per il tuo paese di spedizione.

The page warns about the weight or length unit: senza una classe di peso in 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 del negozio sconosciuta fa leggere Box size in cm. Usa cm, mm, m o in come classe di lunghezza del negozio (System > Settings, scheda Option).

Rates look outdated after a change: clicca su Save nella pagina dell'estensione o su Clear cached UPS token and rates.

The page says "Warning: You do not have permission to modify VibeFox UPS!": il tuo gruppo utenti amministratori potrebbe poter solo visualizzare le impostazioni. Concedi al gruppo il permesso di modifica per extension/shipping/vfd_ups (OpenCart 3) o extension/vfd_ups/shipping/vfd_ups (OpenCart 4) in System > Users > User Groups.

For developers: l'estensione attiva eventi di OpenCart a cui altre estensioni possono rispondere: vfd_ups/allowed_services e vfd_ups/excluded_services limitano i servizi UPS che possono essere mostrati, vfd_ups/rate_request modifica la richiesta di tariffa, vfd_ups/api_base_url l'indirizzo dell'API e vfd_ups/currency_codes associa i codici valuta restituiti da UPS.

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox UPS. OpenCart ripristina sempre Enable UPS shipping, Sort order, Tax class e Geo zone. Il token e le tariffe UPS in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, vengono eliminati anche le impostazioni UPS e il log di debug. Se è disattivo, le altre impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. I servizi UPS salvati con gli ordini non vengono mai rimossi, e gli ordini esistenti mantengono il loro metodo di spedizione e il loro costo.

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

UPS è un marchio del rispettivo titolare. Questa estensione non è affiliata né approvata da UPS.