VibeFox FedEx 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.

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 disattivo. L'estensione usa la API REST di FedEx con OAuth 2.0; non servono un numero di contatore (meter number) né una password per i servizi web. Se usi solo tariffe fisse, non servono le chiavi FedEx.

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_fedex-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_fedex.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_fedex-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 radice del tuo negozio.

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

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

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

5. Inserisci la API Key, la Secret Key, il numero di account FedEx a 9 cifre e l'indirizzo Ship from (CAP e, per gli Stati Uniti e il Canada, la sigla dello stato a 2 lettere). Disattiva Sandbox quando usi chiavi di produzione. Facoltativamente, inserisci prezzi fissi come riserva. Attiva Enable/Disable e clicca su Save.

OpenCart 4

1. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_fedex.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 FedEx, clicca su Install (il pulsante verde +), poi su Edit (il pulsante a forma di matita).

4. Inserisci la chiave di licenza e le impostazioni come nei passaggi 4 e 5 per OpenCart 3. La pagina delle impostazioni e i suoi campi sono uguali in entrambe le versioni.

Dopo l'installazione il metodo è disattivato finché non attivi Enable/Disable e salvi. Se reinstalli l'estensione dopo la disinstallazione, vengono usate di nuovo le impostazioni FedEx che hai conservato.

Configurazione

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

In cima alla pagina l'estensione mostra degli avvisi: sono compilate solo alcune delle tre credenziali API, non ci sono chiavi API né prezzi fissi (in quel caso il metodo non viene mai mostrato), manca il CAP di partenza, manca lo stato di partenza per gli Stati Uniti o il Canada, la valuta del negozio non ha un tasso di cambio per tariffe nella valuta dell'account FedEx, un'unità di peso che l'estensione non riconosce quando non c'è una classe di peso in kg (aggiungine una in System > Localisation > Weight Classes) oppure, con una dimensione del collo, un'unità di lunghezza che non riconosce. I campi numerici accettano il punto o la virgola decimale. Al salvataggio, 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, un nome o un ordine di visualizzazione non validi vengono segnalati e non salvati; il campo mantiene il valore precedente e gli altri campi vengono salvati (The other settings were saved.). Viene segnalato anche un peso minimo maggiore di quello massimo, e i due pesi mantengono i valori precedenti.

Generale

Le impostazioni valgono per tutte le zone geografiche. FedEx viene offerto al checkout come un'unica opzione di spedizione: il servizio FedEx più economico, oppure il prezzo fisso quando FedEx non restituisce alcuna tariffa.

Enable/Disable: attiva o disattiva la spedizione FedEx al checkout. Predefinito: disattivato.

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

Tax class: la classe fiscale del costo di spedizione, oppure No tax (predefinito). Con una classe fiscale OpenCart aggiunge le tasse al costo di spedizione, quindi si usa l'importo FedEx al netto delle tasse. Con No tax si usa così com'è l'importo netto FedEx.

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

API FedEx (tariffe in tempo reale)

La sezione rimanda al FedEx Developer Portal. Senza chiavi si usano i prezzi fissi.

Sandbox: usa la sandbox FedEx (apis-sandbox.fedex.com) con chiavi di test. Disattivala per ottenere 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. Svuotarla rimuove anche la Secret Key salvata.

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. Clearing the API Key removes it too. Inserisci un nuovo valore solo per modificarla.

FedEx account number: il numero dell'account di spedizione FedEx a 9 cifre collegato al progetto. Per questo account vengono calcolate le tariffe negoziate.

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

Residential delivery: calcola gli indirizzi dei clienti come residenziali (FedEx Home Delivery, supplemento residenziale). Disattivalo se spedisci soprattutto ad aziende. Predefinito: attivo.

Box size (L x W x H): dimensioni facoltative del collo nell'unità di lunghezza del negozio indicata nel nome del campo, per esempio 30x20x15. FedEx applica quindi il peso volumetrico. Lascialo vuoto per calcolare 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 si chiede sempre 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 valuta predefinita del negozio, per esempio 0.92. Senza di esso tali tariffe non vengono usate, e un importo in un'altra valuta non viene mai mostrato come se fosse nella tua valuta.

Cache: il pulsante Clear cached FedEx token and rates svuota subito la cache. I token FedEx vengono memorizzati fino alla scadenza, le tariffe per 1 ora e le richieste fallite per 5-10 minuti.

Ship from

L'indirizzo da cui FedEx ritira o in cui consegni i pacchi. 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 gli Stati Uniti e il Canada, per esempio TN, CA o ON.

City: la città di partenza della spedizione.

ZIP / postal code: il CAP di partenza. FedEx ne ha bisogno per quotare le tariffe. OpenCart non ha un CAP del negozio, quindi inseriscilo qui.

Prezzi fissi

Si usano quando non sono inserite chiavi API e come riserva quando FedEx non restituisce alcuna tariffa (API non raggiungibile, chiavi errate, nessun servizio). Lascia vuoti entrambi i campi per nascondere il metodo in quel caso.

Country prices: un elenco di paesi di destinazione e prezzi nella valuta predefinita del negozio, al netto delle tasse. Clicca su Add row per aggiungere una riga e sul pulsante × per rimuoverla. Scegli * Any other country per un prezzo usato per ogni paese senza una riga propria. Le righe senza un paese o un prezzo validi vengono ignorate e segnalate al salvataggio.

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

Fixed price is: Per order (predefinito) 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 calcolate per il peso totale del carrello.

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 quel caso non viene fatta alcuna richiesta a FedEx. Lascialo vuoto per non offrire mai la spedizione gratuita.

Minimum subtotal: mostra il metodo solo se lo stesso subtotale è almeno questo importo. Lascialo vuoto per mostrarlo sempre.

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

Max weight (kg): il peso massimo del carrello. Il metodo viene nascosto se viene superato. 0 significa nessun limite (predefinito).

Default product weight (kg): il peso usato per i prodotti senza peso, per le tariffe FedEx e per i limiti di peso sopra indicati. Predefinito: 0.5; un campo vuoto significa anch'esso 0.5 kg. I pesi dei prodotti vengono convertiti dalla classe di peso di ogni prodotto.

Geo zone: offre FedEx solo per gli indirizzi di questa zona geografica. All zones (predefinito) significa nessun limite. Le zone geografiche si gestiscono in System > Localisation > Geo Zones. Non viene usata quando Ignore shipping zones è attivo.

Disponibilità senza zone di spedizione

Ignore shipping zones: non controlla la zona geografica; offre il metodo per i paesi indicati sotto. Predefinito: disattivato.

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

Avanzate

Debug log: scrive le richieste API e i calcoli delle tariffe in storage/logs/vfd_fdx_debug.log.php (in OpenCart 4 system/storage/logs/vfd_fdx_debug.log.php). Il file non può essere letto dal web. Gli errori API vengono sempre registrati, anche quando il registro è disattivato. Chiavi, token, numero di account e indirizzi dei clienti non vengono mai registrati. Quando il file raggiunge 5 MB, viene spostato in vfd_fdx_debug.old.log.php e ne viene avviato uno nuovo.

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

Remove data on uninstall: se attivo, disinstallando l'estensione vengono eliminate le impostazioni FedEx, i token e le tariffe in cache e il registro. Se disattivo (predefinito), tutto viene conservato per una reinstallazione. Le tariffe FedEx degli ordini effettuati vengono sempre conservate.

Importa / Esporta

Export: clicca su Download JSON per salvare le impostazioni in un file JSON. La Secret Key non viene esportata.

Import: incolla un 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. La Secret Key salvata viene mantenuta.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo FedEx. Se è impostata una Geo zone (e Ignore shipping zones è disattivato) e l'indirizzo è fuori da essa, FedEx non viene offerto. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non rientrano 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. L'estensione poi verifica 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 fatta alcuna richiesta a FedEx.

Altrimenti, se API Key, Secret Key e numero di account sono impostati, l'estensione ottiene un token OAuth e invia alla Rate API di FedEx l'indirizzo di partenza, l'indirizzo di destinazione, il peso del carrello (in kg, o in lb per i negozi con classe di peso lb o oz), la dimensione del collo se impostata e la tua valuta predefinita come valuta preferita. Per i paesi in cui in OpenCart è attivo Postcode Required, la richiesta viene fatta solo dopo che il cliente ha inserito un CAP. Per le spedizioni internazionali viene inviato il valore doganale del carrello. Le sigle degli stati vengono inviate solo per gli Stati Uniti e il Canada.

FedEx restituisce i servizi disponibili. Per ogni servizio l'estensione prende la tariffa di account o di listino che hai scelto, preferisce 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 riesce a convertire. Viene usato il servizio più economico. Il prezzo viene arrotondato alle cifre decimali della tua valuta predefinita e mostrato al cliente nella sua valuta, con le tasse della Tax class selezionata.

Il token viene memorizzato fino alla scadenza e richiesto di nuovo automaticamente quando FedEx lo rifiuta. Le quotazioni vengono memorizzate per 1 ora. Una richiesta di tariffa 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 della API è di 15 secondi. Se FedEx non risponde, il cliente non vede alcun errore: viene usato il prezzo fisso, oppure il metodo viene nascosto. Il motivo viene scritto nel registro di debug.

L'estensione calcola solo le tariffe. Non crea spedizioni FedEx, non stampa etichette, non prenota ritiri, non traccia i pacchi e non permette ai clienti di scegliere una sede FedEx. Mostra un'opzione (il servizio più economico), non più di una, e non c'è un confezionamento in scatole: il carrello viene quotato come un unico collo.

In OpenCart 4 il cliente clicca su Choose nel blocco dei metodi di spedizione della pagina di checkout e sceglie FedEx nella finestra Shipping method options. Il metodo funziona come in OpenCart 3.

Ordini

Quando viene effettuato un ordine con FedEx, la tariffa mostrata al cliente viene salvata con l'ordine. Nella pagina dell'ordine in Sales > Orders c'è un riquadro FedEx shipping. Mostra il FedEx service della tariffa (per le tariffe in tempo reale), il Price source (FedEx live rate, Fixed price (no live rate) o Free shipping threshold) e il Calculated price (excl. tax) nella tua valuta predefinita. I valori vengono congelati al momento dell'ordine: le modifiche successive alle impostazioni non li cambiano. In OpenCart 4 per il checkout viene mantenuto un solo ordine, che viene aggiornato ogni volta che il cliente conferma di nuovo: la tariffa FedEx salvata viene aggiornata insieme ad esso, e viene rimossa quando il cliente passa a un altro metodo di spedizione.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox FedEx è il primo blocco di Extensions > Extensions > Shipping > VibeFox FedEx > 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-fedex 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 o License expired on con una data. Dopo un cambio dell'indirizzo del negozio, o dopo aver liberato un posto 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 dalla configurazione di OpenCart. Rimuovere la chiave dal negozio non libera il suo posto dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, il metodo di spedizione FedEx 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 comunque il metodo nel negozio, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e provare l'estensione prima di acquistare una chiave. In 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 vengono modificati.

Quando una licenza scade, l'estensione continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene ricontrollato 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 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

FedEx non compare al checkout: controlla che la licenza sia attiva e che Enable/Disable sia attivo. Controlla Geo zone, oppure Ignore shipping zones e Countries. Controlla gli avvisi in cima alla pagina dell'estensione, i limiti di peso e Minimum subtotal. Senza tariffa in tempo reale il metodo richiede un prezzo per paese, una riga * Any other country o un Fallback cost. Controlla che i prodotti abbiano Requires Shipping impostato su Yes.

Le tariffe in tempo reale non compaiono: attiva Debug log, ricarica il checkout e guarda il campo Log nella pagina dell'estensione. Vi vengono registrati chiavi errate, ambiente sbagliato (chiavi di test con Sandbox disattivo, o chiavi di produzione con Sandbox attivo), un CAP di consegna mancante e i codici di errore di 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 come 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 dell'estensione svuota la cache. Puoi anche cliccare su Clear cached FedEx token and rates.

La pagina dice "Warning: You do not have permission to modify VibeFox FedEx!": il tuo gruppo utenti amministratori può solo visualizzare le impostazioni. Concedi al gruppo il permesso di modifica per extension/shipping/vfd_fedex (OpenCart 3) o extension/vfd_fedex/shipping/vfd_fedex (OpenCart 4) in System > Users > User Groups.

Per gli sviluppatori: altre estensioni possono modificare l'indirizzo della API, i servizi FedEx consentiti e la richiesta di tariffa tramite gli eventi OpenCart vfd_fedex/api_base_url, vfd_fedex/allowed_services e vfd_fedex/rate_request (registrati come catalog/vfd_fedex/...); l'impostazione vfd_fdx_api_url sostituisce l'indirizzo della API per i test e 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 FedEx. OpenCart reimposta sempre Enable/Disable, Sort order, Tax class e Geo zone. I token e le tariffe in cache vengono sempre eliminati. Se Remove data on uninstall è attivo, vengono eliminate anche le impostazioni FedEx e il registro di debug. Se è disattivo, le altre impostazioni vengono conservate e riutilizzate alla reinstallazione dell'estensione. Le tariffe FedEx degli ordini effettuati vengono conservate in entrambi i casi, e gli ordini mantengono il loro metodo e costo di spedizione.

In 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 FedEx nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso del cestino) per eliminare il pacchetto caricato.

FedEx è un marchio del suo proprietario. Questa estensione non è affiliata né approvata da FedEx.