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

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 l'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, le chiavi di produzione solo con il campo disattivato. Il plugin 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 servono le chiavi FedEx.

Chiave di licenza VibeFox: acquistabile 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. Puoi anche caricare la cartella vfd_fedex in /wp-content/plugins/ tramite FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox FedEx, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugins.

4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.

5. Inserisci l'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 di 2 lettere della provincia/stato). Disattiva Sandbox quando usi chiavi di produzione.

6. Aggiungi VibeFox FedEx a una zona di spedizione in WooCommerce > Settings > Shipping > Shipping zones, oppure attiva Ignore shipping zones e scegli i paesi.

7. Facoltativamente, inserisci prezzi fissi come alternativa.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox FedEx. 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 al checkout. Lascialo vuoto per usare il Name globale.

In cima alla pagina il plugin mostra degli avvisi: sono compilate solo alcune delle tre credenziali API, mancano le chiavi API o i prezzi fissi (in tal caso il metodo non viene mai mostrato), manca il CAP di partenza, manca la provincia di partenza per gli Stati Uniti o il Canada, oppure la valuta del negozio è diversa da quella dell'account FedEx senza un tasso di cambio. Ogni volta che salvi le impostazioni, il token FedEx e le tariffe in cache vengono cancellati. I campi numerici accettano il punto o la virgola decimale. Un numero non valido non viene salvato e viene segnalato.

General

Enable/Disable: attiva o disattiva la spedizione FedEx in tutte le zone contemporaneamente. Predefinito: attivo.

Name: il nome del metodo di spedizione mostrato al cliente al checkout. Predefinito: FedEx.

Tax status: Taxable consente a WooCommerce di aggiungere l'imposta al costo di spedizione, quindi si usa la tariffa FedEx senza imposte. None usa la tariffa netta di FedEx così com'è. Predefinito: Taxable.

API FedEx (tariffe in tempo reale)

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

Sandbox: usa la sandbox FedEx con chiavi di test. Disattivalo per ottenere tariffe reali con chiavi di produzione. Predefinito: attivo.

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

Secret Key: la Secret Key (client_secret) dello stesso progetto.

FedEx account number: l'account di spedizione FedEx a 9 cifre collegato al progetto.

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 tal caso FedEx applica il peso volumetrico. Lascialo vuoto 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 del negozio.

Exchange rate: serve solo quando FedEx restituisce tariffe solo nella valuta dell'account e la valuta del tuo negozio è diversa: il prezzo di 1 unità della valuta dell'account nella valuta del tuo negozio, 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: il codice di 2 lettere, obbligatorio 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.

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 metodo in questo caso.

Country prices: il prezzo nella valuta del tuo negozio per paese di destinazione, una riga per paese nel formato CC=PREZZO, per esempio US=12.99 o CA=19,99. Usa * per qualsiasi altro paese, per esempio *=29.99. Le righe in un formato diverso vengono ignorate e segnalate al salvataggio.

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

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. 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 a partire dal quale questo metodo è gratuito. Lascialo vuoto per non offrire mai la spedizione gratuita.

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

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

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

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.

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 se non è stato aggiunto a una zona di spedizione. Un metodo di zona disattivato nella sua zona resta disattivato.

Countries: i paesi di destinazione per questa modalità. Lascialo vuoto per tutti i paesi di spedizione del negozio. 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-fedex. Gli errori API vengono sempre registrati. Chiavi, 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. Disattivare il plugin non cancella mai le impostazioni.

Come funziona al checkout

Quando il cliente inserisce un indirizzo di consegna, WooCommerce chiede al plugin una tariffa. Il plugin controlla prima il peso del carrello, il subtotale minimo e le classi di spedizione escluse. Se si applica la spedizione gratuita, il cliente vede il metodo come FedEx (Free) e non viene inviata alcuna richiesta a FedEx.

Altrimenti il plugin 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 valuta del negozio come valuta preferita. Per i paesi che usano i codici postali, la richiesta viene inviata solo dopo che il cliente ha inserito il CAP. Per le spedizioni internazionali viene inviato il valore doganale del carrello. I codici di provincia vengono inviati solo per gli Stati Uniti e il Canada.

FedEx restituisce i servizi disponibili. Per ogni servizio il plugin prende la tariffa dell'account o di listino che hai scelto, preferisce una tariffa nella valuta del negozio, 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 viene mostrato sotto il nome del tuo metodo, e il suo nome viene salvato nella riga di spedizione dell'ordine.

Il token viene 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 del servizio non rallenti ogni aggiornamento del checkout. Il timeout dell'API è di 15 secondi. Se FedEx non risponde, il cliente non vede alcun errore: si usa il prezzo fisso oppure il metodo viene nascosto.

Il metodo funziona sul checkout classico e su quello a blocchi. È compatibile con WooCommerce High-Performance Order Storage (HPOS).

Il plugin 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'opzione (il servizio più economico), non più di una, e non c'è il confezionamento dei colli: il carrello viene quotato come un unico collo.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Shipping > VibeFox FedEx. 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 controllare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuoverla da questo sito. Il collegamento 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 per il dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, FedEx non viene mostrato ai clienti al checkout. Gli amministratori del negozio connessi lo vedono ancora, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugins e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati.

Quando una licenza scade, il plugin continua a funzionare, ma per gli aggiornamenti e l'assistenza serve il rinnovo. Lo stato viene controllato di nuovo automaticamente in background.

Risoluzione dei problemi

FedEx non compare al 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 consentito). Controlla gli avvisi in cima alla pagina delle impostazioni, i limiti di peso, Minimum subtotal ed Excluded shipping classes. Senza una tariffa in tempo reale, il metodo richiede un prezzo per paese, una riga * o un Fallback cost.

Le tariffe in tempo reale non compaiono: attiva Debug log, ricarica il checkout e apri WooCommerce > Status > Logs, origine vfd-fedex. Lì vengono registrate le chiavi errate, l'ambiente sbagliato (chiavi di test con Sandbox disattivato, o chiavi di produzione con Sandbox attivo) e i codici di errore FedEx.

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

La modalità «per item» moltiplica la tariffa FedEx? No. Per item si applica solo ai prezzi fissi.

Le tariffe sembrano non aggiornate dopo una modifica: dopo aver cambiato le chiavi la cache viene cancellata automaticamente. Puoi anche fare clic su Clear cached FedEx token and rates.

Si vogliono offrire solo alcuni servizi: gli sviluppatori possono limitare i servizi con il filtro vfd_fdx_allowed_services.

Il blocco 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 tutte le impostazioni e cancella solo i 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, i token e le tariffe in cache e i vecchi file di log vengono sempre rimossi. Le impostazioni e i metodi di zona vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano per una successiva reinstallazione. Gli ordini esistenti conservano le proprie righe di spedizione.

FedEx è un marchio del suo rispettivo titolare. Questo plugin non è affiliato a FedEx né approvato da FedEx.