VibeFox DHL Africa 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. DHL XML Services richiede anche l'estensione PHP SimpleXML.

Account DHL Express (solo per le tariffe in tempo reale): le tariffe in tempo reale usano l'API MyDHL. Ti servono il tuo numero di account DHL Express e le credenziali dell'API MyDHL: una chiave API e un secret API. Richiedile sul portale per sviluppatori DHL (MyDHL API, "Get access") oppure al tuo account manager DHL Express. Gli account che hanno ancora le credenziali di DHL XML Services (Site ID e password) possono usarle al loro posto. Se usi solo i prezzi di riserva, non ti servono credenziali DHL.

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un 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_dhl_africa-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_dhl_africa.ocmod.zip. Installa solo il pacchetto della 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_dhl_africa-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 principale del tuo negozio.

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

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

4. Inserisci la tua chiave di licenza VibeFox nel campo License key del blocco licenza in alto nella pagina Edit e clicca su Activate (vedi License key).

5. Scegli l'API DHL, inserisci la chiave API, il secret API e il tuo numero di 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 predefinita del negozio, imposta DHL quote currency e Exchange rate. Facoltativamente imposta i prezzi per paese e un costo di riserva (vedi Configuration). Attiva Enable DHL Express Africa e clicca su Save.

OpenCart 4

1. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_dhl_africa.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 DHL Africa, clicca su Install (il pulsante verde +), poi su Edit (il pulsante con la 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 resta disattivato finché non attivi Enable DHL Express Africa e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono di nuovo usate le impostazioni DHL che avevi conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox DHL Africa > Edit. Le sezioni sono elencate a sinistra. Un unico pulsante Save salva l'intera pagina senza ricaricarla. Ogni salvataggio svuota anche la cache delle quotazioni DHL. Prezzi e pesi accettano la virgola o il punto decimale. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.

Gli avvisi in alto nella pagina ti segnalano quando le tariffe in tempo reale sono disattivate perché manca la chiave API, il secret API o il numero di account (oppure, con XML Services, il Site ID o la password), quando manca il paese o la città di origine, quando sono selezionati XML Services (DHL li sta dismettendo), quando è impostata una valuta di quotazione senza tasso di cambio, e quando l'unità di peso o di lunghezza del negozio non è riconosciuta dall'estensione (i pesi dei prodotti vengono allora letti in kg e le dimensioni in cm; aggiungi una classe di peso con unità kg in System > Localisation > Weight Classes oppure una classe di lunghezza con unità cm in System > Localisation > Length Classes).

Se un valore non è valido al salvataggio (un titolo del metodo vuoto o più lungo di 64 caratteri, un numero non valido o negativo, un tasso di cambio pari a 0, un peso minimo superiore al peso massimo, una valuta di quotazione, un paese di origine, una classe fiscale o una zona geografica sconosciuti, un ordine di visualizzazione che non è un numero intero), un avviso sopra le impostazioni indica il campo, per esempio Select a valid origin country. It was not saved. Il valore precedente di quel campo viene mantenuto e le altre impostazioni vengono salvate.

Generali

Enable DHL Express Africa: mostra o nasconde DHL Express al checkout. Predefinito: off.

Method title: il nome del metodo di spedizione mostrato al cliente al checkout. Predefinito: DHL Express. Obbligatorio, massimo 64 caratteri.

Tax class: la classe fiscale del costo di spedizione, oppure No tax (predefinito). Con una classe fiscale (e le tasse attive nel negozio) la tariffa DHL viene presa senza l'imposta indicata da DHL, e OpenCart aggiunge la propria imposta. Con No tax la tariffa DHL viene addebitata così com'è quotata, imposta inclusa.

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

Account DHL Express (necessario solo per le tariffe in tempo reale)

DHL API: quale interfaccia DHL viene usata.

API key: il tuo nome utente MyDHL API (chiave API).

API secret: la tua password MyDHL API (secret API). Dopo il salvataggio i campi API key e API secret restano vuoti e mostrano Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.

Remove the saved API key and API secret: visibile solo per la MyDHL API quando è salvata una chiave o un secret. Attivalo e clicca su Save per eliminarli entrambi.

XML Site ID: il tuo Site ID di DHL XML Services (solo per l'API legacy). Svuotarlo elimina anche la password XML salvata.

XML password: la tua password di DHL XML Services (solo per l'API legacy). Come il secret API, dopo il salvataggio non viene più mostrata.

DHL account number: il tuo numero di account DHL Express (9 cifre). L'API MyDHL 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, quelle di produzione solo in produzione. Disattivalo quando vai online.

Indirizzo di partenza

L'indirizzo da cui DHL ritira i pacchi. La tariffa dipende da esso. OpenCart conserva l'indirizzo del negozio come testo libero, quindi l'origine va sempre inserita qui. La nota di questa sezione mostra il paese del tuo negozio.

Origin country: il paese da cui spedisci.

Origin city: la città da cui spedisci, per esempio Johannesburg. L'API MyDHL la richiede.

Origin postcode: lascialo vuoto per i paesi senza codice postale (per esempio Kenya, Nigeria, Ghana).

Tariffe

Tutti i prezzi sono nella valuta predefinita del negozio, IVA esclusa. 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, viene usato il prezzo del paese, poi il costo di riserva. Se non c'è né l'uno né l'altro, 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 predefinita del negozio, la tariffa in tempo reale viene convertita da questa valuta con il tasso di cambio qui sotto. Altrimenti non viene usata. Predefinito: — None —.

Exchange rate: quanto vale 1 unità della valuta di quotazione DHL nella valuta predefinita del negozio, per esempio 1 ZAR = 0.05. Deve essere maggiore di 0. Lascialo vuoto se non vuoi conversioni. Il tasso è un'impostazione manuale.

Fallback cost: un costo fisso quando non ci sono né una tariffa in tempo reale né un prezzo per paese. Lascialo vuoto per nascondere il metodo in questo caso.

Country prices: un prezzo di riserva per paese di destinazione, uno per riga: CC:Price, per esempio ZA:25.00. Viene usato quando non c'è una tariffa in tempo reale. Le righe in un altro formato vengono ignorate e un avviso al salvataggio le elenca.

Fallback price basis: Per order (predefinito) addebita il prezzo una sola volta. Per item (multiplied by the cart quantity) lo moltiplica per il numero di articoli. Si applica solo al prezzo per paese e al costo di riserva. La tariffa DHL in tempo reale riguarda sempre tutto il pacco.

Free shipping from: il subtotale dei prodotti che richiedono spedizione (dopo il coupon, prima delle imposte) a partire dal quale questo metodo è gratuito. DHL non viene interrogato. Lascialo vuoto per non averla mai gratuita.

Condizioni

Minimum weight (kg): nasconde il metodo sotto questo peso del carrello. 0 significa nessun limite (predefinito). Non può essere maggiore di Maximum weight (kg).

Maximum weight (kg): nasconde il metodo sopra questo peso del carrello. Predefinito: 70 (usato anche quando il campo è vuoto). 0 significa nessun limite.

Minimum subtotal: mostra il metodo solo se il subtotale dei prodotti che richiedono spedizione (dopo il coupon, prima delle imposte) è almeno questo importo. Lascialo vuoto per mostrarlo sempre.

Disponibilità

Geo zone: offri DHL Express solo per indirizzi in questa zona geografica. All zones (predefinito) significa nessun limite. Le zone geografiche si gestiscono in System > Localisation > Geo Zones. Non viene verificato con Ignore shipping zones.

Ignore shipping zones: offri il metodo per i paesi qui sotto (o per tutti i paesi, se l'elenco è vuoto), qualunque sia la zona geografica selezionata.

Countries: i paesi di destinazione per questa modalità. Usato solo con Ignore shipping zones.

Avanzate

Debug log: scrive i calcoli delle tariffe in storage/logs/vfd_dhla_debug.log.php (su OpenCart 4 in system/storage/logs/vfd_dhla_debug.log.php). Il file non può essere letto dal web. Gli errori DHL vengono sempre registrati, anche quando l'opzione è disattiva. Le credenziali, il numero di account e gli indirizzi dei clienti non vengono mai registrati. Quando il file raggiunge 5 MB, viene spostato in vfd_dhla_debug.old.log.php e ne viene avviato uno nuovo.

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

Remove data on uninstall: se attivo, disinstallando l'estensione vengono eliminate le impostazioni, le quotazioni DHL in cache e il registro. Se disattivo (predefinito), tutto viene conservato per una reinstallazione. I prodotti DHL degli ordini effettuati vengono sempre conservati.

Importazione / Esportazione

Export: clicca su Download JSON per salvare le impostazioni in un file JSON. La chiave API, il secret API e la password XML non vengono esportati.

Import: incolla il JSON esportato in precedenza e clicca su Import per ripristinare le impostazioni, per esempio in un altro negozio. I valori vengono controllati come in un normale salvataggio. Le credenziali salvate vengono mantenute.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo DHL Express. Se è impostata una Geo zone (e Ignore shipping zones è disattivo) e l'indirizzo è al di fuori di essa, DHL Express non viene offerto. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri prodotti non aggiungono peso e non sono inclusi nel subtotale. L'estensione controlla poi le condizioni: i paesi di Ignore shipping zones, il peso del carrello e il subtotale minimo. Il subtotale è il prezzo dei prodotti che richiedono spedizione, dopo lo sconto del coupon e prima delle imposte. Buoni regalo, punti fedeltà e credito del negozio non vengono considerati. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata alcuna richiesta a DHL.

Altrimenti l'estensione invia a DHL l'origine e la destinazione (paese, città, codice postale), il peso del carrello convertito in kg dalle classi di peso dei prodotti (almeno 0,5 kg) e un collo costruito con le dimensioni dei prodotti in cm: la lunghezza maggiore, la larghezza maggiore e le altezze sovrapposte. I prodotti senza dimensioni non aggiungono nulla. Se nessun prodotto ha dimensioni, viene usato un collo di 10 x 10 x 10 cm. Le spedizioni verso un altro paese vengono dichiarate in dogana, con il subtotale del carrello come valore dichiarato. Le spedizioni nazionali non vengono dichiarate. La data di ritiro è oggi, nel fuso orario del negozio, oppure il lunedì nel fine settimana. Una tariffa in tempo reale viene richiesta solo dopo che il cliente ha inserito una città (con XML Services, una città o un codice postale). Prima di allora si applicano i prezzi di riserva.

Il prodotto DHL Express più economico viene mostrato come un unico prezzo con il titolo del tuo metodo. Il cliente non vede il prodotto DHL. Il prezzo viene calcolato nella valuta predefinita, arrotondato alle sue cifre decimali e mostrato al cliente nella sua valuta con l'imposta della Tax class selezionata.

Ogni quotazione viene memorizzata nella cache per 1 ora per pacco e tratta. Una richiesta non riuscita viene memorizzata per 10 minuti, così il checkout non attende DHL a ogni aggiornamento. Il timeout dell'API è di 12 secondi. Se DHL restituisce un errore, non ha un servizio o risponde in una valuta non utilizzabile, il cliente non vede alcun errore: viene usato il prezzo di riserva oppure il metodo viene nascosto. Il motivo viene scritto nel registro di debug.

L'estensione calcola solo le tariffe. Non crea spedizioni DHL, non stampa etichette o fatture commerciali, non prenota ritiri, non traccia i pacchi, non offre punti di servizio DHL, non permette al cliente di scegliere tra prodotti DHL, non confeziona più colli, non aggiunge un'assicurazione e non calcola dazi e imposte. La quotazione riguarda solo la spedizione. Dazi e imposte di importazione sono a carico del destinatario.

Su OpenCart 4 il cliente clicca su Choose nel blocco del metodo di spedizione della pagina di checkout e sceglie DHL Express nella finestra Shipping method options. Il metodo funziona come su OpenCart 3.

Ordini

Quando l'ordine viene effettuato, l'estensione conserva la tariffa calcolata per il suo carrello. Apri l'ordine in Sales > Orders: il pannello DHL Express Africa sopra la cronologia dell'ordine mostra cosa prenotare con DHL:

DHL product: il prodotto DHL Express della tariffa in tempo reale, per esempio "EXPRESS WORLDWIDE (P)". Mostrato solo per le tariffe in tempo reale.

Price source: Live DHL rate, Fallback price (no live rate) oppure Free shipping threshold.

Calculated price (excl. tax): il prezzo nella valuta predefinita del negozio.

Il prodotto DHL non viene mostrato al cliente nelle e-mail né nella sua pagina dell'ordine. L'ordine mostra il titolo del metodo e il costo di spedizione come qualsiasi altro metodo di spedizione di OpenCart.

Su OpenCart 4 il checkout mantiene un solo ordine e lo aggiorna ogni volta che il cliente conferma di nuovo. Il pannello mostra quindi l'ultima tariffa del checkout. Se il cliente passa a un altro metodo di spedizione, il pannello non viene più mostrato per quell'ordine.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza License — VibeFox DHL Africa è il primo blocco della pagina Extensions > Extensions > Shipping > VibeFox DHL Africa > Edit, sopra le impostazioni. Inserisci la chiave in License key e clicca 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 di essi ci sono la riga Product: opencart-shipping-dhl-africa 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 incluse le lingue inglese e russa).

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 un cambio dell'indirizzo del negozio, o dopo aver liberato uno slot di 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 dominio: l'indirizzo del negozio dalla configurazione di OpenCart. Rimuovere la chiave dal negozio non libera lo slot del dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, il metodo di spedizione DHL Express non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Un 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. Su 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, compare un promemoria nella Dashboard dell'amministrazione. Chiudilo con × per nasconderlo per 7 giorni. Gli ordini esistenti non sono interessati.

Quando una licenza scade, l'estensione continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene controllato di nuovo automaticamente quando apri la Dashboard o la pagina Edit dell'amministrazione: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve alcun cron job. Disinstallare l'estensione rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

DHL Express non compare al checkout: controlla che la licenza sia attiva e che Enable DHL Express Africa sia attivo. Controlla Geo zone (oppure attiva Ignore shipping zones e controlla Countries), i limiti di peso e il Minimum subtotal. Senza tariffa in tempo reale il metodo compare solo se è impostato un prezzo per paese o un costo di riserva. Controlla che i prodotti abbiano Requires Shipping impostato su Yes.

Le tariffe in tempo reale non compaiono: controlla gli avvisi in alto nella pagina dell'estensione (credenziali o origine mancanti). Attiva Debug log, ricarica il checkout e guarda il campo Log nella pagina dell'estensione. Gli errori DHL, come un errore HTTP dell'API MyDHL, nessun prodotto per la tratta o un problema di valuta, vengono sempre registrati. Controlla che Test mode corrisponda alle tue credenziali e che l'indirizzo del cliente contenga una città.

DHL restituisce la tariffa in ZAR, NGN o KES ma il negozio usa un'altra valuta: il registro dice DHL quote not usable. Imposta DHL quote currency su quella valuta e inserisci l'Exchange rate. Senza questo, la tariffa in tempo reale non viene usata e si applicano i prezzi di riserva.

Ho vecchie credenziali di DHL XML Services: scegli XML Services (legacy) in DHL API. Passa all'API MyDHL quando ricevi le credenziali MyDHL.

L'imposta sulla spedizione viene addebitata due volte: imposta una Tax class in modo che la tariffa DHL venga presa senza l'imposta di DHL, oppure scegli No tax per addebitare l'importo DHL così com'è quotato.

Le tariffe sembrano non aggiornate dopo una modifica: clicca su Save nella pagina dell'estensione. Questo svuota la cache delle quotazioni DHL.

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

Per gli sviluppatori: l'estensione attiva gli eventi OpenCart catalog/vfd_dhl_africa/api_url, is_dutiable, package_box, rest_request e xml_request (stesso prefisso), che possono modificare l'indirizzo dell'API, la dichiarazione doganale, il collo e le richieste a DHL.

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox DHL Africa. OpenCart ripristina sempre Enable DHL Express Africa, Sort order, Tax class e Geo zone. Le quotazioni DHL in cache e gli eventi dell'estensione vengono sempre eliminati. Se Remove data on uninstall è attivo, vengono eliminati anche le impostazioni DHL e il registro di debug. Se è disattivo, le altre impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. I prodotti DHL degli ordini effettuati non vengono mai eliminati. Gli ordini esistenti mantengono il loro metodo di spedizione e il loro costo.

Su 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 DHL Africa nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per rimuovere il pacchetto caricato.

DHL è un marchio del rispettivo proprietario. Questa estensione non è affiliata a DHL né approvata da DHL.