VibeFox DHL Africa for WooCommerce — Guida
Requisiti
WordPress: 5.8 o successivo.
WooCommerce: 5.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.
PHP: 8.0 o successivo.
Account DHL Express (solo per le tariffe in tempo reale): le tariffe in tempo reale usano la MyDHL API. Ti servono il numero del tuo account DHL Express e le credenziali MyDHL API: una chiave API e un segreto API. Richiedile sul DHL Developer Portal (MyDHL API, "Get access") oppure al tuo account manager DHL Express. Gli account che hanno ancora credenziali DHL XML Services (Site ID e password) possono usarle al loro posto. Se usi solo i prezzi alternativi, non ti servono credenziali DHL.
Chiave di licenza VibeFox: acquistata 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_dhl_africa in /wp-content/plugins/ via FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Shipping > DHL Express Africa, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugin.
4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.
5. Scegli la DHL API, inserisci la chiave API, il segreto API e il numero del tuo account DHL. Lascia attivo Test mode finché usi credenziali di test. Inserisci l'indirizzo Ship from. Se il tuo account DHL non è fatturato nella valuta del tuo negozio, imposta DHL quote currency e Exchange rate. Facoltativamente imposta i prezzi per paese e un costo alternativo (vedi Configurazione).
6. Aggiungi DHL Express Africa alle zone di spedizione in WooCommerce > Settings > Shipping > Shipping zones, oppure attiva Ignore shipping zones e scegli i paesi.
Configurazione
Tutte le impostazioni sono su un'unica pagina: WooCommerce > Settings > Shipping > DHL Express Africa. Valgono per ogni zona 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 per questa zona. Lascialo vuoto per usare il Name globale.
Gli avvisi sopra le impostazioni ti segnalano quando le tariffe in tempo reale sono disattivate perché mancano credenziali o origine, e quando una valuta di preventivo è impostata senza un tasso di cambio. Ogni volta che salvi le impostazioni, i preventivi DHL in cache vengono cancellati. Prezzi e pesi accettano la virgola o il punto decimale.
Generale
Enable/Disable: attiva o disattiva il metodo in tutte le zone contemporaneamente.
Name: il nome del metodo di spedizione mostrato al checkout. Predefinito: DHL Express.
Tax status: Taxable (con le imposte WooCommerce attive) prende la tariffa DHL senza l'imposta che DHL include nel preventivo, e WooCommerce aggiunge la propria imposta. None addebita la tariffa DHL così come quotata, imposta inclusa.
Account DHL Express (necessario solo per le tariffe in tempo reale)
DHL API: quale interfaccia DHL viene usata. Vengono mostrati solo i campi dell'API scelta.
API key: il tuo nome utente MyDHL API (chiave API).
API secret: la tua password MyDHL API (segreto API).
XML Site ID: il tuo Site ID di DHL XML Services (solo per l'API legacy).
XML password: la tua password di DHL XML Services (solo per l'API legacy).
DHL account number: il numero del tuo account DHL Express (9 cifre). MyDHL API lo richiede. Con XML Services restituisce le tariffe del tuo account invece delle tariffe pubblicate.
Test mode: usa l'ambiente di test DHL. Attivo per impostazione predefinita. Le credenziali di test funzionano solo nell'ambiente di test, e quelle di produzione solo in produzione. Disattivalo quando passi alla produzione.
Spedizione da
L'indirizzo da cui DHL ritira i pacchi. La tariffa dipende da esso.
Origin country: il paese da cui spedisci.
Origin city: la città da cui spedisci, per esempio Johannesburg. MyDHL API la richiede.
Origin postcode: lascialo vuoto per i paesi senza CAP (per esempio Kenya, Nigeria, Ghana).
Tariffe
Tutti i prezzi sono nella valuta del tuo negozio. La tariffa in tempo reale è il prodotto DHL Express più economico per il pacco. Se DHL non è configurato, fallisce o non ha un servizio per la tratta, si usa il prezzo del paese, poi il costo alternativo. Se mancano entrambi, il metodo viene nascosto.
DHL quote currency: DHL quota nella valuta del paese del tuo account DHL (per esempio ZAR, NGN o KES). Se DHL non restituisce un importo nella valuta del tuo negozio, la tariffa in tempo reale viene convertita da questa valuta con il tasso di cambio sotto. Altrimenti non viene usata.
Exchange rate: quanto vale 1 unità della valuta del preventivo DHL nella valuta del tuo negozio, per esempio 1 ZAR = 0.05. Lascialo vuoto per non effettuare alcuna conversione. Il tasso è un'impostazione manuale.
Fallback cost: un costo fisso quando non c'è una tariffa in tempo reale né un prezzo del paese. Lascialo vuoto per nascondere il metodo.
Country prices: un prezzo alternativo per paese di destinazione, uno per riga: CC:Prezzo, per esempio ZA:25.00. Usato quando non c'è una tariffa in tempo reale.
Fallback price basis: Per order addebita il prezzo una volta sola. Per item (multiplied by the cart quantity) lo moltiplica per il numero di articoli. Si applica solo al prezzo del paese e al costo alternativo. La tariffa DHL in tempo reale è sempre per l'intero pacco.
Free shipping from: il subtotale del carrello da cui questo metodo è gratuito. DHL non viene interpellato. Lascialo vuoto per non renderlo mai gratuito.
Condizioni
Minimum weight (kg): nasconde il metodo sotto questo peso del carrello. 0 significa nessun limite.
Maximum weight (kg): nasconde il metodo sopra questo peso del carrello. Predefinito: 70. 0 significa nessun limite.
Minimum subtotal: mostra il metodo solo se il subtotale del carrello è almeno questo importo. Lascialo vuoto per mostrarlo sempre.
Excluded shipping classes: nasconde il metodo se il carrello contiene un prodotto di una di queste classi di spedizione WooCommerce.
Disponibilità senza zone di spedizione
Ignore shipping zones: offre il metodo per i paesi qui sotto, anche se la zona di spedizione corrispondente non lo contiene.
Countries: i paesi di destinazione per questa modalità. Lascialo vuoto per usare tutti i paesi verso cui spedisci. Usato solo con Ignore shipping zones.
Avanzate
Debug log: registra i calcoli delle tariffe in WooCommerce > Status > Logs, origine vfd-dhl-africa. Gli errori DHL vengono sempre registrati, anche quando questa opzione è disattivata. Credenziali e indirizzi dei clienti non vengono mai registrati.
Remove data on uninstall: se attivo, eliminando il plugin vengono rimosse le sue impostazioni e i metodi delle zone. Disattivare il plugin non elimina mai i dati.
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 riceve la consegna gratuita e nessuna richiesta viene inviata a DHL.
Altrimenti il plugin invia a DHL origine e destinazione (paese, città, CAP), il peso del carrello convertito in kg (almeno 0,5 kg) e un box costruito dalle dimensioni dei prodotti in cm: la lunghezza maggiore, la larghezza maggiore e la somma delle altezze. I prodotti senza dimensioni non aggiungono nulla. Se nessun prodotto ha dimensioni, viene usato un box di 10 x 10 x 10 cm. Le spedizioni internazionali vengono dichiarate come merce, con il subtotale del carrello come valore dichiarato, così DHL quota i prodotti per pacchi. Le spedizioni nazionali non vengono dichiarate. Una tariffa in tempo reale viene richiesta solo dopo che il cliente ha inserito una città (con XML Services, una città o un CAP).
Il prodotto DHL Express più economico viene mostrato come un'unica tariffa con il tuo titolo. Il cliente non vede il prodotto DHL né un tempo di consegna. Il nome del prodotto (per esempio "EXPRESS WORLDWIDE (P)") viene salvato come DHL product nella riga di spedizione dell'ordine, così sai cosa prenotare.
Ogni preventivo viene messo in cache per 1 ora per pacco e tratta. Una richiesta fallita viene messa in cache per 10 minuti, così il checkout non attende DHL a ogni aggiornamento. Il timeout dell'API è di 12 secondi. Se DHL restituisce un errore o non ha un servizio, il cliente non vede alcun errore: si usa il prezzo alternativo oppure il metodo viene nascosto.
Il metodo funziona con il checkout classico e con i blocchi Carrello e Checkout. È compatibile con WooCommerce High-Performance Order Storage (HPOS).
Il plugin calcola solo le tariffe. Non crea spedizioni DHL, non stampa etichette o fatture commerciali, non prenota ritiri, non traccia pacchi, non offre punti di servizio DHL, non permette al cliente di scegliere tra prodotti DHL, non impacchetta più box, non aggiunge assicurazione e non quota dazi e imposte. Il preventivo riguarda solo la spedizione. Dazi e imposte di importazione sono a carico del destinatario.
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 > DHL Express Africa. 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 posto del dominio. Libera il posto nel tuo account vibefox.net.
Senza una chiave attiva, DHL Express non viene mostrato ai clienti al checkout. I gestori del negozio che hanno effettuato l'accesso vedono comunque il metodo, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria appare nella pagina Plugin e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati.
Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene ricontrollato automaticamente in background.
Risoluzione dei problemi
DHL Express non appare 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 sia consentito). Controlla i limiti di peso, Minimum subtotal e Excluded shipping classes. Senza una tariffa in tempo reale il metodo appare solo se è impostato un prezzo del paese o un costo alternativo.
Le tariffe in tempo reale non appaiono: controlla gli avvisi in cima alla pagina delle impostazioni (credenziali o origine mancanti). Attiva Debug log e apri WooCommerce > Status > Logs, origine vfd-dhl-africa. Gli errori DHL, come credenziali errate, nessun servizio per la tratta o un problema di valuta, vengono sempre registrati. Verifica che Test mode corrisponda alle tue credenziali.
DHL restituisce la tariffa in ZAR, NGN o KES ma il mio negozio usa un'altra valuta: imposta DHL quote currency su quella valuta e inserisci l'Exchange rate. Senza di esso la tariffa in tempo reale non viene usata e si applicano i prezzi alternativi.
Ho ancora vecchie credenziali DHL XML Services: scegli XML Services (legacy) in DHL API. Passa alla MyDHL API quando ricevi le credenziali MyDHL.
L'imposta sulla spedizione viene addebitata due volte: imposta Tax status su Taxable così la tariffa DHL viene presa senza l'IVA di DHL, oppure su None per addebitare l'importo DHL così come quotato.
Le tariffe sembrano obsolete dopo una modifica: salva la pagina delle impostazioni. Questo cancella i preventivi DHL in cache.
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. Cancella solo i preventivi DHL in cache. Per rimuovere il plugin, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi, così come i preventivi in cache. Impostazioni e metodi delle zone vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano per una successiva reinstallazione. Gli ordini non vengono mai modificati, e gli ordini esistenti mantengono le loro righe di spedizione.
DHL è un marchio del rispettivo proprietario. Questo plugin non è affiliato né approvato da DHL.