VibeFox FedEx for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo con l'estensione cURL. Senza di esse il modulo non si installa.

Account FedEx e chiavi API (solo per le tariffe in tempo reale): nel FedEx Developer Portal (developer.fedex.com) crea un progetto con la Rate API, collega il tuo account di spedizione FedEx e copia la API Key e la Secret Key. Ti serve anche il numero di account FedEx a 9 cifre. Le chiavi di test funzionano solo con Sandbox attivo, quelle di produzione solo con Sandbox disattivato. Il modulo usa la REST API di FedEx con OAuth 2.0; non richiede meter number né password dei web services. Se usi solo prezzi fissi, non ti servono chiavi FedEx.

Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un 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 VibeFox FedEx più tardi nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la chiave di licenza VibeFox in License key, nel blocco licenza in cima alla pagina Configure, poi fai clic su Activate (vedi Chiave di licenza).

4. Inserisci la API Key, la Secret Key, il numero di account FedEx a 9 cifre e l'indirizzo Ship from (CAP e, per USA e Canada, la sigla dello stato a 2 lettere). Disattiva Sandbox se usi chiavi di produzione. Facoltativamente, inserisci prezzi fissi come alternativa. Fai clic su Save.

All'installazione il modulo crea il corriere FedEx con il testo dei tempi di consegna FedEx delivery. Il corriere viene 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 proviene sempre dal modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox FedEx > Configure. Si applicano a tutte le zone del corriere. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio svuota anche il token e le tariffe FedEx in cache.

In cima alla pagina il modulo mostra degli avvisi: sono compilate solo alcune delle tre credenziali API, non ci sono chiavi API né prezzi fissi (in tal caso il corriere non viene mai mostrato), manca il CAP di partenza, manca lo stato di partenza per USA o Canada, la valuta del negozio è diversa da quella dell'account FedEx senza un tasso di cambio, l'unità di peso del negozio (o, con una dimensione del collo, l'unità delle dimensioni) non è riconosciuta dal modulo, oppure il corriere è stato eliminato. I campi numerici accettano il punto o la virgola decimale. Un numero o una dimensione del collo non validi, un tasso di cambio pari a 0, una valuta dell'account che non è un codice di 3 lettere e un nome più lungo di 64 caratteri non vengono salvati e vengono segnalati; il campo mantiene il valore precedente e gli altri campi vengono salvati. Viene segnalato anche un peso minimo superiore al peso massimo, e in quel caso entrambi i pesi mantengono i valori precedenti.

Generale

Enable/Disable: attiva o disattiva la spedizione con FedEx. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.

Name: il nome del metodo di spedizione mostrato al cliente al checkout (il nome del corriere). Predefinito: FedEx. Obbligatorio.

Tax status: la regola fiscale del corriere, oppure No tax. Con una regola fiscale (e con le tasse attive nel negozio) PrestaShop aggiunge l'imposta al costo di spedizione, quindi si usa il costo FedEx senza tasse. Con No tax si usa il costo netto FedEx così com'è.

API FedEx (tariffe in tempo reale)

Senza chiavi si usano i prezzi fissi indicati sotto. La sezione contiene il pulsante Clear cached FedEx token and rates.

Sandbox: usa il sandbox di FedEx (apis-sandbox.fedex.com) con chiavi di test. Disattivalo per le tariffe reali (apis.fedex.com) con chiavi di produzione. Predefinito: attivo.

API Key: la API Key (client_id) del tuo progetto nel FedEx Developer Portal.

Secret Key: la Secret Key (client_secret) dello stesso progetto. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi modificarlo. Svuotare la API Key elimina anche la Secret Key salvata.

FedEx account number: il numero di account di spedizione FedEx a 9 cifre collegato al progetto. Le tariffe dell'account (negoziate) vengono quotate per questo account.

Rates: Account rates (your negotiated FedEx prices) (predefinito) oppure List rates (FedEx published prices).

Residential delivery: quota gli indirizzi dei clienti come residenziali (FedEx Home Delivery, supplemento per consegna residenziale). 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. In questo caso FedEx applica il peso volumetrico. Lascia vuoto il campo per quotare solo in base al peso.

FedEx account currency: la valuta del tuo account FedEx, per esempio USD per gli account statunitensi o CAD per il Canada. Predefinito: USD. A FedEx viene sempre chiesto di quotare anche nella valuta predefinita del negozio.

Exchange rate: serve solo quando FedEx restituisce tariffe unicamente nella valuta dell'account e la valuta predefinita del negozio è diversa: 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.

Spedizione da

L'indirizzo da cui FedEx ritira i pacchi o in cui li consegni. Viene usato per le tariffe in tempo reale.

Country: il paese da cui spedisci. Predefinito: United States.

State / province code: la sigla a 2 lettere, obbligatoria per USA e Canada, per esempio TN, CA o ON.

City: la città di partenza.

ZIP / postal code: il CAP di partenza. FedEx lo richiede per quotare le tariffe.

Prezzi fissi

Si usano quando non sono inserite chiavi API e come alternativa quando FedEx non restituisce alcuna tariffa (API non disponibile, chiavi errate, nessun servizio). Lascia vuoti entrambi i campi per nascondere il corriere in tal caso.

Country prices: una tabella con codici paese di destinazione a 2 lettere e prezzi nella valuta predefinita del tuo negozio, IVA esclusa. Fai clic su Add row per aggiungere un paese e sull'icona del cestino per rimuoverlo. Usa * come codice paese per tutti gli altri paesi. Le righe che non contengono un codice paese (o *) con un prezzo vengono ignorate e segnalate al salvataggio.

Fallback cost: un prezzo fisso quando nessun prezzo per paese corrisponde. Lascia vuoto il campo per nascondere il corriere.

Fixed price is: Per order addebita il prezzo una sola volta. Per item (price x number of items) lo moltiplica per il numero di articoli nel carrello. Questo vale solo per i prezzi fissi. Le tariffe FedEx in tempo reale vengono sempre quotate per il peso totale del carrello.

Condizioni

Free shipping from: il subtotale del carrello (dopo gli sconti, al netto delle tasse) a partire dal quale questo corriere è gratuito. Lascia vuoto il campo per non offrire mai la spedizione gratuita.

Minimum subtotal: mostra il corriere solo se il subtotale del carrello è almeno pari a questo importo. Lascia vuoto il campo per mostrarlo sempre.

Min weight: il peso minimo del carrello in kg affinché il corriere compaia. 0 significa nessun limite.

Max weight: il peso massimo del carrello in kg. Se viene superato, il corriere viene nascosto. 0 significa nessun limite.

Default product weight: il peso in kg usato per i prodotti senza peso, per le tariffe FedEx e per i limiti di peso sopra indicati. Predefinito: 0.5. I pesi dei prodotti vengono convertiti dall'unità di peso del tuo negozio (kg, g, lb o oz), impostata in International > Localization (Local units).

Disponibilità senza zone di spedizione

Ignore shipping zones: offre il corriere per i paesi indicati sotto anche se la loro zona non gli è assegnata. Al salvataggio il corriere viene collegato a tutte le zone, anche a quelle create in seguito. Disattivandolo, il corriere riottiene le sue zone precedenti.

Countries: i paesi di destinazione per questa modalità. Lascia vuoto per tutti i paesi del negozio. Viene usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: registra le richieste API e il calcolo delle tariffe in logs/vfd_fdx_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Gli errori API vengono sempre registrati. Chiavi, token e indirizzi dei clienti non vengono mai registrati.

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

Remove data on uninstall: se attivo, disinstallando il modulo vengono eliminate tutte le sue impostazioni, il corriere e i servizi FedEx memorizzati degli ordini. Se disattivo, tutto viene conservato per una reinstallazione.

Come funziona al checkout

Nella fase di spedizione PrestaShop chiede al modulo il prezzo FedEx. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nel subtotale. Il modulo verifica prima i paesi consentiti (con 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 FedEx.

Altrimenti il modulo ottiene un token OAuth e invia alla Rate API di FedEx l'indirizzo di partenza, l'indirizzo di consegna, il peso del carrello (in kg, o in lb per i negozi che usano lb o oz), la dimensione del collo se impostata e la tua valuta predefinita come valuta preferita. Per i paesi che richiedono un CAP, la richiesta viene fatta solo dopo che il cliente ne ha inserito uno. Per le spedizioni internazionali viene inviato il valore doganale del carrello. I codici di stato vengono inviati solo per USA e Canada.

FedEx restituisce i servizi disponibili. Per ogni servizio il modulo prende la tariffa dell'account o di listino che hai scelto, privilegia una tariffa nella tua valuta predefinita, converte una tariffa nella valuta dell'account FedEx con il tuo tasso di cambio e scarta le tariffe che non può convertire. Il servizio più economico determina il prezzo, e il prezzo viene mostrato nella valuta del carrello del cliente.

Il token è memorizzato nella cache per ambiente e chiave e viene richiesto di nuovo automaticamente quando FedEx lo rifiuta. Le quotazioni sono memorizzate nella cache per 1 ora. Una richiesta di tariffa non riuscita viene ricordata per 10 minuti e una richiesta di token non riuscita per 5 minuti, così che un'interruzione non rallenti ogni aggiornamento del checkout. Il timeout delle API è di 15 secondi. Se FedEx non risponde, il cliente non vede alcun errore: si usa il prezzo fisso oppure il corriere viene nascosto. Il motivo viene scritto nel registro di debug.

Se modifichi il corriere in Shipping > Carriers dopo che ha ricevuto ordini, PrestaShop lo salva come nuova versione del corriere. Il modulo segue automaticamente la nuova versione.

Il modulo calcola solo le tariffe. Non crea spedizioni FedEx, non stampa etichette, non prenota ritiri, non traccia i pacchi e non consente al cliente di scegliere un punto FedEx. Mostra un'unica opzione (il servizio più economico), non più di una, e non c'è un confezionamento in colli: il carrello viene quotato come un unico collo.

Ordini

Nella pagina dell'ordine nel back office, gli ordini con il corriere FedEx hanno un blocco FedEx shipping. Mostra il FedEx service della tariffa (per le tariffe in tempo reale), la Price source (FedEx live rate, Fixed price (no live rate) oppure Free shipping threshold) e il Calculated price (excl. tax) nella tua valuta predefinita. I valori vengono fissati al momento dell'ordine: le modifiche successive alle impostazioni non li cambiano.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox FedEx è il primo blocco di Modules > Module Manager > VibeFox FedEx > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Poi il blocco mostra la chiave mascherata, lo stato (per esempio la data fino a cui 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 compaiono la riga Product: presta-shipping-fedex 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 modificare 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 oppure License expired on con una data. Dopo aver cambiato l'indirizzo del negozio, o dopo aver liberato uno slot di 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 multistore. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, il corriere FedEx non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. La vetrina di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il corriere viene nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non 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 reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

FedEx non compare al checkout: verifica che la licenza sia attiva e che Enable/Disable 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 gli avvisi in cima alla pagina del modulo, i limiti di peso e Minimum subtotal. Senza una tariffa in tempo reale, il corriere ha bisogno di un prezzo per paese, di una riga * o di un Fallback cost. Inoltre, i prodotti possono essere limitati a determinati corrieri nella pagina del prodotto.

Le tariffe in tempo reale non compaiono: attiva il Debug log, ricarica il checkout e controlla il campo Log nella pagina del modulo. Vengono registrati lì le chiavi errate, l'ambiente sbagliato (chiavi di test con Sandbox disattivato, o chiavi di produzione con Sandbox attivo), un CAP di consegna mancante e i codici di errore FedEx.

Il mio negozio non usa USD: a FedEx viene chiesta la tariffa nella valuta predefinita del negozio. Se il tuo account restituisce solo la propria valuta, imposta FedEx account currency e Exchange rate. Senza tasso di cambio, tali tariffe vengono ignorate e si usa il prezzo fisso, così un importo in USD non viene mai mostrato in euro.

"Per item" moltiplica la tariffa FedEx? No. Per item si applica solo ai prezzi fissi.

Le tariffe sembrano obsolete dopo una modifica: salvare la pagina del modulo svuota la cache. Puoi anche fare clic su Clear cached FedEx token and rates.

La pagina dice che il corriere FedEx non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Ripristina il modulo in Modules > Module Manager per crearlo di nuovo.

Dovrebbero essere offerti solo alcuni servizi: gli sviluppatori possono limitare i servizi con l'hook actionVfdFdxAllowedServices. Gli hook actionVfdFdxRateRequest e actionVfdFdxApiBaseUrl modificano la richiesta di tariffa e l'indirizzo dell'API.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox FedEx e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. Token e tariffe in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini conservano lo storico), e vengono rimosse le impostazioni, il registro e i servizi FedEx memorizzati degli ordini. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni vengono conservate. Reinstallando il modulo (o con Reset), il corriere salvato riprende lo stato che aveva prima della disinstallazione.

FedEx è un marchio del rispettivo proprietario. Questo modulo non è affiliato a FedEx né approvato da FedEx.