VibeFox UPS 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 nel UPS Developer Portal (solo per le tariffe in tempo reale): accedi al UPS Developer Portal (developer.ups.com), crea un'app con il prodotto "Rating", collega il tuo account UPS e copia il Client ID e il Client Secret. Il plugin usa OAuth 2.0. Non servono Access Key, nome utente o password. Per le tariffe negoziate ti serve anche il numero di conto 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
1. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e fai clic su Install Now. In alternativa puoi caricare la cartella vfd_ups in /wp-content/plugins/ tramite FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox UPS, oppure fai clic su Settings sotto il nome del plugin nella pagina dei Plugin.
4. Inserisci la tua chiave di licenza VibeFox nel blocco della licenza in cima alla pagina e fai clic su Activate.
5. Inserisci il Client ID e il Client Secret, il tuo numero di conto UPS (per le tariffe negoziate) e l'indirizzo Ship from: il codice postale e, per Stati Uniti e Canada, la sigla dello stato di 2 lettere.
6. Se la valuta del tuo conto UPS è diversa dalla valuta del negozio, inserisci UPS account currency e Exchange rate.
7. Aggiungi VibeFox UPS a una zona di spedizione in WooCommerce > Settings > Shipping > Shipping zones, oppure attiva Ignore shipping zones e scegli i paesi.
8. Facoltativamente, inserisci dei prezzi fissi come alternativa.
Configurazione
Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox UPS. 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 di questa opzione nel checkout. Lascialo vuoto per usare il Name globale.
Ogni volta che salvi le impostazioni, il token UPS e le tariffe in cache vengono cancellati. Puoi anche fare clic su Clear cached UPS token and rates nella sezione UPS API. Gli avvisi sopra le impostazioni ti segnalano quando è compilato solo uno tra Client ID e Client Secret, quando non ci sono credenziali né prezzi fissi, quando mancano il codice postale o lo stato di partenza, quando si scelgono tariffe del conto senza numero di conto o quando manca il tasso di cambio.
General
Enable/Disable: attiva o disattiva il metodo in tutte le zone contemporaneamente.
Name: il nome del metodo di spedizione mostrato nel checkout. Predefinito: UPS.
Tax status: Taxable fa aggiungere a WooCommerce la sua imposta sulla spedizione, None non la aggiunge. Le tariffe UPS sono indicate al netto delle imposte, quindi l'imposta non viene addebitata due volte.
UPS API (tariffe in tempo reale)
Test mode: usa l'ambiente di test di UPS. Le tariffe di test non sono prezzi reali. Disattivalo per le tariffe in tempo reale. Predefinito: disattivato.
Client ID: il Client ID della tua app nel UPS Developer Portal.
Client Secret: il Client Secret della stessa app.
UPS account number: il tuo numero di mittente UPS di 6 caratteri, per esempio A1B2C3. Serve per le tariffe del conto (negoziate), è facoltativo per le tariffe pubbliche.
Rates: quali prezzi UPS vengono usati.
Measurement units: le unità inviate a UPS. Pesi e dimensioni del negozio vengono convertiti.
Residential delivery: calcola gli indirizzi dei clienti come residenziali, con la maggiorazione residenziale UPS. Disattivalo se spedisci soprattutto ad aziende. Predefinito: attivo.
Box size: dimensioni facoltative del collo nell'unità di misura delle dimensioni del tuo negozio, per esempio 30x20x15. UPS applica quindi il peso volumetrico. Lascialo vuoto per calcolare solo in base al peso.
UPS account currency: UPS calcola in valuta del paese del conto mittente, per esempio USD per gli Stati Uniti, CAD per il Canada o EUR per l'area euro. Predefinito: USD.
Exchange rate: serve solo quando la valuta del conto UPS è diversa da quella del negozio. Inserisci il prezzo di 1 unità della valuta del conto nella valuta del tuo negozio, per esempio 0.92. Senza di esso queste tariffe non vengono usate e si applicano i prezzi fissi. I tassi di cambio non si aggiornano automaticamente.
Indirizzo di partenza (l'indirizzo da cui UPS ritira i pacchi o presso cui li consegni; 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 Stati Uniti e Canada, per esempio NY, CA o ON.
City: la città da cui spedisci.
ZIP / postal code: il codice postale da cui spedisci. UPS ne ha bisogno per calcolare le tariffe.
Prezzi fissi (usati quando non sono inserite credenziali API e come alternativa quando UPS non restituisce alcuna tariffa; lascia vuoti entrambi per nascondere il metodo in quel caso)
Country prices: prezzi nella valuta del tuo negozio per paese di destinazione. Fai clic su + Add country per aggiungere una riga e sulla croce per rimuoverne una. La riga * Default si applica a qualsiasi altro paese. Una colonna di peso (XS fino a 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL oltre 5 kg) sostituisce Price per quel peso del carrello. Le celle vuote usano Price. 0 significa spedizione gratuita. Le righe senza alcun prezzo vengono rimosse al salvataggio, e i valori che non sono numeri vengono rifiutati con un messaggio.
Fallback cost: un prezzo fisso nella valuta del tuo negozio quando nessun prezzo per paese corrisponde. Lascialo vuoto per nascondere il metodo in quel caso.
Fixed price is: Per order addebita il prezzo una sola volta. Per item (each item priced by its own weight x quantity) calcola ogni articolo 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 calcolate sul peso totale del carrello.
Condizioni
Free shipping from: il subtotale del carrello a partire dal quale questo metodo è gratuito. Il cliente vede il nome del metodo con "(Free)" e non viene inviata alcuna richiesta a UPS. Lascialo vuoto per non offrire mai la spedizione gratuita.
Minimum subtotal: mostra il metodo solo quando il subtotale del carrello è almeno questo importo. Lascialo vuoto per mostrarlo sempre.
Min weight (kg): il peso minimo del carrello perché questo metodo compaia. 0 significa nessun limite.
Max weight (kg): il metodo viene nascosto sopra questo peso del carrello. Predefinito: 70, il limite UPS per collo (70 kg / 150 lbs). 0 significa nessun limite.
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.
Excluded shipping classes: nasconde il metodo se il carrello contiene un prodotto appartenente a una di queste classi di spedizione di WooCommerce.
Disponibilità senza zone di spedizione
Ignore shipping zones: offre il metodo per i paesi indicati qui 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-ups. Gli errori API vengono sempre registrati, anche con questa opzione disattivata. Credenziali, token e indirizzi dei clienti non vengono mai registrati.
Remove data on uninstall: se attivo, eliminando il plugin vengono rimosse tutte le sue impostazioni e i metodi di zona. Disattivarlo non cancella mai le impostazioni.
Come funziona nel checkout
Quando il cliente inserisce un indirizzo di consegna, WooCommerce chiede al plugin una tariffa. Il plugin verifica prima le condizioni: peso del carrello, subtotale minimo e classi di spedizione escluse. Se si applica la spedizione gratuita, il metodo viene mostrato come gratuito e non viene inviata alcuna richiesta a UPS.
Il plugin ottiene un token OAuth da UPS e lo conserva finché non scade. Un token rifiutato da UPS viene rinnovato automaticamente. Poi chiede all'API Rating di UPS tutti i servizi dal tuo indirizzo di partenza all'indirizzo del cliente, per il carrello come un unico collo. Per i paesi con codice postale, la richiesta attende che il cliente ne inserisca uno. Per le spedizioni dagli Stati Uniti verso Canada o Porto Rico viene inviato il valore della merce, come richiede UPS.
Il cliente vede un'unica opzione con il servizio UPS più economico, convertita nella valuta del tuo negozio. UPS Access Point Economy non viene calcolato, perché il plugin non raccoglie un indirizzo di Access Point.
Ogni tariffa viene memorizzata nella cache per 1 ora. Una richiesta fallita viene ricordata per 10 minuti, e una richiesta di token fallita per 5 minuti, così un'interruzione non rallenta ogni aggiornamento del checkout. Il timeout HTTP è di 15 secondi. Disattivare il plugin cancella il token e le tariffe in cache.
Se UPS non fornisce una tariffa (API non disponibile, credenziali errate, nessun servizio), 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 messaggi di errore di UPS.
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 offre la scelta di un UPS Access Point, non crea etichette di spedizione 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 calcolato come un unico collo. I tassi di cambio non sono automatici.
Ordini
Per una tariffa in tempo reale, la riga di spedizione dell'ordine memorizza il UPS service, per esempio UPS Ground. Il gestore del negozio lo vede nella schermata dell'ordine nell'area di amministrazione.
Chiave di licenza
Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza si trova in cima a WooCommerce > Settings > Shipping > VibeFox UPS. 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 verificare 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. Liberalo nel tuo account vibefox.net.
Senza una chiave attiva, UPS non viene mostrato ai clienti nel checkout. I gestori del negozio con accesso lo vedono ancora, contrassegnato da (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Nella pagina dei Plugin e nelle 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 verificato di nuovo automaticamente in background.
Risoluzione dei problemi
UPS non compare nel 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 credenziali UPS funzionanti, il metodo ha bisogno di 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 il Debug log e apri WooCommerce > Status > Logs, origine vfd-ups. Mostra gli errori OAuth (controlla Client ID, Client Secret e Test mode), i messaggi di errore di UPS e i problemi di valuta.
La tariffa è in USD ma il negozio no: UPS restituisce le tariffe nella valuta del conto mittente. Imposta UPS account currency e 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, oppure scegli le unità che UPS si aspetta per il tuo paese di partenza.
Le tariffe sembrano obsolete dopo una modifica: salva la pagina delle impostazioni o fai clic su Clear cached UPS token and rates.
Per gli sviluppatori: i filtri vfd_upsx_allowed_services e vfd_upsx_excluded_services limitano i servizi UPS che possono essere mostrati. vfd_upsx_rate_request modifica la richiesta di tariffa, vfd_upsx_api_base_url l'indirizzo dell'API e vfd_upsx_currency_codes associa i codici valuta restituiti da UPS.
Il blocco della 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 mantiene le impostazioni e cancella solo il token e le tariffe in cache. Per rimuoverlo, disattivalo ed eliminalo nella 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 di zona vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano per una reinstallazione successiva. Gli ordini esistenti conservano le loro righe di spedizione.
UPS è un marchio del rispettivo proprietario. Questo plugin non è affiliato a UPS né approvato da UPS.