VibeFox UPS for PrestaShop — Guida
Requisiti
PrestaShop: da 8.0 a 9.x.
PHP: 8.0 o successivo, con l'estensione cURL. Il modulo non si installa su versioni precedenti di PHP o senza cURL.
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 conto UPS e copia il Client ID e il Client Secret. Il modulo 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. Nel back office vai su Modules > Module Manager e fai clic su Upload a module. Scegli il file ZIP del modulo.
2. Al termine del caricamento, fai clic su Configure, oppure trova più tardi VibeFox UPS nell'elenco dei moduli e fai clic su Configure.
3. Inserisci la tua chiave di licenza VibeFox nel campo License key del blocco licenza in alto nella pagina Configure e fai clic su Activate (vedi Chiave di licenza).
4. 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 di provincia/stato a 2 lettere.
5. Se la valuta del tuo conto UPS è diversa dalla valuta predefinita del negozio, inserisci UPS account currency e Exchange rate.
6. Facoltativamente inserisci i prezzi fissi come alternativa e fai clic su Save.
All'installazione il modulo crea il corriere UPS con il testo dei tempi di consegna UPS delivery. Il corriere è assegnato a tutte le zone e a tutti i gruppi di clienti. Puoi modificare 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 UPS > Configure. Si applicano a tutte le zone del corriere. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio svuota il token UPS e le tariffe in cache. Puoi anche fare clic su Clear cached UPS token and rates nella sezione UPS API.
Gli avvisi sopra le impostazioni ti segnalano quando è impostato solo uno tra Client ID e Client Secret, quando non ci sono credenziali né prezzi fissi (il corriere in quel caso non viene mai mostrato), quando manca il codice postale o la provincia di partenza, quando sono scelte tariffe del conto senza numero di conto, quando manca il tasso di cambio, oppure quando il modulo non riconosce l'unità di peso o di dimensione del negozio. I numeri non validi, una dimensione della scatola errata e un Min weight superiore a Max weight vengono segnalati al salvataggio e il valore precedente viene mantenuto.
Generali
Enable UPS 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: UPS. Obbligatorio, massimo 64 caratteri.
Tax status: la regola fiscale del corriere, oppure None. Le tariffe UPS sono indicate senza tasse. Con una regola fiscale il negozio aggiunge sopra la propria imposta sulla spedizione.
API UPS (tariffe in tempo reale)
Test mode: usa l'ambiente di test UPS. Le tariffe di test non sono prezzi reali. Disattivalo per le tariffe reali. Predefinito: off.
Client ID: il Client ID della tua app nel UPS Developer Portal. Se lo svuoti, viene rimosso anche il Client Secret salvato.
Client Secret: il 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 se vuoi cambiarlo.
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: on.
Box size: dimensioni facoltative della scatola nell'unità di dimensione del tuo negozio, per esempio 30x20x15. UPS applica quindi il peso volumetrico. Lascia vuoto per calcolare solo in base al peso.
UPS account currency: UPS calcola nella 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 dalla valuta predefinita del negozio. Inserisci il prezzo di 1 unità della valuta del conto 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 si aggiornano automaticamente.
Indirizzo di spedizione (l'indirizzo da cui UPS ritira o dove consegni i pacchi; usato per le tariffe in tempo reale)
Country: il paese da cui spedisci. Per impostazione predefinita è il paese del negozio.
State / province code: la sigla a 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 lo richiede 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 i campi per nascondere il corriere in quel caso)
Country prices: prezzi nella valuta predefinita del negozio, tasse escluse, per paese di destinazione. Fai clic su Add country per aggiungere una riga e sul pulsante di rimozione per eliminarne una. Il paese * si applica a tutti gli altri paesi. 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. 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 predefinita del negozio, quando non corrisponde nessun prezzo per paese. Lascialo vuoto per nascondere il corriere in quel caso.
Fixed price is: Per order addebita il prezzo una sola volta, per il peso dell'intero carrello. Per item (each item priced by its own weight x quantity) calcola ogni prodotto in base al proprio peso (il peso predefinito se non ne ha uno) e lo moltiplica per la quantità. Se un prodotto non ha un prezzo fisso, il corriere viene nascosto. Le tariffe UPS in tempo reale sono sempre calcolate per il peso totale del carrello.
Condizioni
Free shipping from: il subtotale del carrello (prodotti da spedire, dopo gli sconti, prima delle tasse) da cui questo corriere è gratuito. In quel caso non viene inviata alcuna richiesta a UPS. Lascia vuoto per non offrire mai la spedizione gratuita.
Minimum subtotal: mostra il corriere solo quando il subtotale del carrello è almeno pari a questo importo. Lascia 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: 70, il limite UPS per collo (70 kg / 150 lbs). 0 significa nessun limite, vuoto significa 70. Min weight non può essere superiore a Max weight.
Default product weight: il peso in kg usato per i prodotti senza peso, nelle tariffe UPS, nelle colonne di peso e nei limiti di peso. Predefinito: 0.5.
Disponibilità senza zone di spedizione
Normalmente il corriere viene offerto nelle zone a cui è assegnato in Shipping > Carriers.
Ignore shipping zones: offre il corriere per i paesi indicati sotto, qualunque zona corrisponda. Al salvataggio il corriere viene aggiunto a tutte le zone, comprese quelle create in seguito. Disattivandolo, quelle zone vengono di nuovo rimosse.
Countries: i paesi di destinazione per questa modalità. Lascia vuoto per usare tutti i paesi attivi 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 logs/vfd_upsx_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Gli errori API vengono sempre registrati, anche quando questa opzione è disattivata. Credenziali, token e indirizzi dei clienti non vengono mai registrati.
Log: mostra la dimensione e le ultime voci del log. Fai clic su Clear log per svuotarlo.
Remove data on uninstall: se attivo, disinstallando il modulo vengono eliminati impostazioni, corriere, token e tariffe in cache, log e servizi UPS salvati con gli ordini. Gli ordini stessi vengono conservati. Se disattivo, tutto viene conservato per una nuova installazione.
Come funziona al checkout
Nel passaggio di spedizione PrestaShop chiede al modulo il prezzo UPS. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nel subtotale. Il modulo verifica prima le condizioni: i paesi di Ignore shipping zones, il peso del carrello e il subtotale minimo. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata alcuna richiesta a UPS.
Il modulo ottiene da UPS un token OAuth e lo conserva fino alla scadenza. Un token rifiutato da UPS viene rinnovato automaticamente. Poi chiede all'API Rating di UPS tutti i servizi dal tuo indirizzo di partenza fino all'indirizzo del cliente, per il carrello come un unico collo. Per i paesi con codice postale, la richiesta attende che il cliente lo abbia inserito. 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. Il prezzo viene calcolato nella valuta predefinita del negozio e poi mostrato nella valuta del carrello del cliente. UPS Access Point Economy non viene quotata, perché il modulo non raccoglie un indirizzo di Access Point.
Ogni tariffa è memorizzata nella cache per 1 ora. Una richiesta fallita viene ricordata per 10 minuti, e una richiesta di token fallita per 5 minuti, così che un'interruzione non rallenti 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, poi da Fallback cost. Se nessuno dei due si applica, il corriere viene nascosto. Il cliente non vede mai i testi di errore di UPS.
Se modifichi il corriere in Shipping > Carriers dopo che ha degli ordini, PrestaShop lo salva come nuova versione del corriere. Il modulo segue automaticamente la nuova versione.
Il modulo 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'opzione, non più servizi UPS. Non c'è il confezionamento in scatole: il carrello viene quotato come un unico collo. I tassi di cambio non sono automatici.
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 nel back office mostra un blocco UPS con il UPS service, per esempio UPS Ground, e la Live rate (excl. tax). Le modifiche successive al carrello nel back office non lo cambiano. Gli ordini con prezzo fisso o spedizione gratuita non hanno questo blocco.
Chiave di licenza
Il modulo funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco licenza License — VibeFox UPS è il primo blocco di Modules > Module Manager > VibeFox UPS > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic 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 si trovano la riga Product: presta-shipping-ups 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 ne indica il motivo, per esempio Key not found, This key belongs to another product, Domain limit reached o License expired on seguito da una data. Dopo aver cambiato l'indirizzo del negozio, o dopo aver liberato un posto per il dominio nel tuo account, fai clic 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 multinegozio. Rimuovere la chiave dal negozio non libera il posto per il dominio. Libera il posto nel tuo account vibefox.net.
Senza una chiave attiva, il corriere UPS non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Lo storefront di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il corriere è nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non puoi testarlo 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 a settimana. Non serve alcun cron job. Disinstallare o ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.
Risoluzione dei problemi
UPS non compare al checkout: verifica che la licenza sia attiva e che Enable UPS shipping sia attivo. In Shipping > Carriers verifica che il corriere copra la zona del paese del cliente e il gruppo di clienti, oppure attiva Ignore shipping zones e controlla Countries. Controlla i limiti di peso e il Minimum subtotal. Senza credenziali UPS funzionanti, il corriere ha bisogno di un prezzo fisso (Country prices o Fallback cost). Inoltre, i prodotti possono essere limitati a determinati corrieri dalla pagina del prodotto.
Le tariffe in tempo reale non compaiono: controlla gli avvisi in alto nella pagina Configure. Attiva Debug log, ricarica il checkout e guarda il campo Log nella pagina del modulo. 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.
La pagina avvisa che l'unità di peso o di dimensione del negozio non è nota: i pesi vengono letti in kg e la dimensione della scatola in cm. Imposta un'unità standard (kg, g, lb o oz; cm, mm, m o in) in International > Localization, sezione Local units.
Le tariffe sembrano obsolete dopo una modifica: fai clic su Save nella pagina del modulo oppure su Clear cached UPS token and rates.
La pagina indica che il corriere UPS non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Reimposta il modulo in Modules > Module Manager per ricrearlo.
Per gli sviluppatori: gli hook actionVfdUpsxAllowedServices e actionVfdUpsxExcludedServices limitano i servizi UPS che possono essere mostrati. actionVfdUpsxRateRequest modifica la richiesta di tariffa, actionVfdUpsxApiBaseUrl l'indirizzo dell'API e actionVfdUpsxCurrencyCodes associa i codici valuta restituiti da UPS.
Disinstallazione
Vai in Modules > Module Manager, apri il menu accanto a VibeFox UPS e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. Il token UPS e le tariffe in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini mantengono lo storico), e vengono rimossi impostazioni, log e servizi UPS salvati con gli ordini. Se è disattivo, il corriere viene solo disabilitato e le impostazioni vengono conservate. Reinstallare il modulo, oppure un ripristino, riporta il corriere allo stato che aveva prima.
UPS è un marchio del rispettivo proprietario. Questo modulo non è affiliato né approvato da UPS.