VibeFox DHL Africa for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo con l'estensione cURL. Il modulo non si installa su versioni di PHP precedenti o senza cURL. I DHL XML Services richiedono anche l'estensione PHP SimpleXML.

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: si acquista su vibefox.net. Una chiave funziona su un solo dominio.

Installazione

1. Nel back office vai su Modules > Module Manager e clicca su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, clicca su Configure, oppure cerca più tardi VibeFox DHL Africa nell'elenco dei moduli e clicca su Configure.

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

4. Scegli la DHL API, inserisci la API key, la API secret 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 prezzi per paese e un costo alternativo (vedi Configurazione). Clicca su Save.

All'installazione il modulo crea il corriere DHL Express con il testo dei tempi di consegna DHL Express courier. Il corriere è assegnato a tutte le zone e a tutti i gruppi di clienti. Puoi cambiare zone, gruppi di clienti, tempi di consegna, logo e limiti di dimensione in Shipping > Carriers. Non impostare lì i prezzi: il prezzo arriva sempre dal modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox DHL Africa > Configure. Valgono per tutte le zone del corriere. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella anche i preventivi DHL in cache. Prezzi e pesi accettano la virgola o il punto decimale.

Gli avvisi in cima alla pagina ti segnalano quando le tariffe in tempo reale sono disattivate perché mancano la API key, la API secret o il numero di account (o, con XML Services, il Site ID o la password), quando manca il paese o la città di origine, quando sono selezionati gli XML Services (DHL li sta dismettendo), quando è impostata una valuta di preventivo senza tasso di cambio, e quando l'unità di peso o di dimensione del negozio in International > Localization (Local units) non è riconosciuta dal modulo (viene quindi letta come kg o cm). Se un valore non è valido al salvataggio (un nome 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, la valuta di preventivo, il paese di origine o la regola fiscale), un errore indica il campo, viene mantenuto il valore precedente di quel campo e le altre impostazioni vengono salvate.

Generali

Enable DHL Express Africa: attiva o disattiva il corriere. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.

Name: il nome del corriere mostrato al cliente al checkout. Predefinito: DHL Express. Obbligatorio, fino a 64 caratteri.

Tax: la regola fiscale del corriere, oppure No tax. Con una regola fiscale (e le tasse attive nel negozio) la tariffa DHL viene presa senza l'imposta quotata da DHL, e PrestaShop aggiunge la propria imposta. Con No tax la tariffa DHL viene addebitata 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). 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 modificarlo.

Remove the saved API key and API secret: visibile solo quando una chiave o un segreto sono salvati. Attivalo e clicca su Save per eliminarli entrambi.

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

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

DHL account number: il tuo numero di account DHL Express (9 cifre). La MyDHL API lo richiede. Con gli XML Services restituisce le tariffe del tuo account invece di quelle 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 in produzione.

Ship from

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. La MyDHL API lo 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 tuo 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, si usa il prezzo del paese, poi il costo alternativo. Con nessuno dei due, il corriere 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 preventivo 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 di cambio è 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 corriere in quel caso.

Country prices: un prezzo alternativo 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 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 alternativo. La tariffa DHL in tempo reale riguarda sempre l'intero pacco.

Free shipping from: il subtotale del carrello (prodotti che richiedono spedizione, dopo gli sconti, prima delle tasse) a partire dal quale questo corriere è gratuito. DHL non viene interrogato. Lascialo vuoto per non averlo mai gratuito.

Condizioni

Minimum weight: nasconde il corriere sotto questo peso del carrello, in kg. 0 significa nessun limite. Non può essere maggiore di Maximum weight.

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

Minimum subtotal: mostra il corriere solo se il subtotale del carrello (dopo gli sconti, prima delle tasse) è almeno questo importo. Lascialo vuoto per mostrarlo sempre.

Disponibilità senza zone di spedizione

Ignore shipping zones: offre il corriere senza che tu gli assegni delle zone. Il corriere riceve tutte le zone, comprese quelle che creerai in seguito, e decidono i paesi sotto. Disattivandolo, il corriere torna ad avere le proprie zone.

Countries: i paesi di destinazione per questa modalità. Lascialo vuoto per consentire tutti i paesi in cui spedisci. Viene usato solo con Ignore shipping zones.

Avanzate

Debug log: scrive i calcoli delle tariffe in logs/vfd_dhla_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori DHL vengono sempre registrati, anche quando questa opzione è disattivata. Credenziali e indirizzi dei clienti non vengono mai registrati.

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

Remove data on uninstall: se attivo, disinstallando il modulo vengono eliminati le impostazioni, il corriere, i prodotti DHL salvati degli ordini e il registro. Se disattivo, tutto viene conservato per una reinstallazione.

Come funziona al checkout

Al passaggio della spedizione PrestaShop chiede al modulo il prezzo DHL Express. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nel subtotale. Il modulo controlla prima le condizioni: i paesi di 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 DHL.

Altrimenti il modulo invia a DHL origine e destinazione (paese, città, codice postale), 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 le altezze sovrapposte. 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 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, 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 alternativi.

Il prodotto DHL Express più economico viene mostrato come un unico prezzo con il nome del tuo corriere. Il cliente non vede il prodotto DHL. Il prezzo viene calcolato nella valuta predefinita, arrotondato e poi mostrato nella valuta del carrello del cliente.

Ogni preventivo viene memorizzato in cache per 1 ora per pacco e tratta. Una richiesta non riuscita viene memorizzata in cache per 10 minuti, così il checkout non aspetta 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 alternativo oppure il corriere viene nascosto. Il motivo viene scritto nel registro di debug.

Se modifichi il corriere in Shipping > Carriers dopo che ha degli 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 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 i prodotti DHL, non confeziona più box, non aggiunge assicurazione e non calcola dazi e tasse. Il preventivo riguarda solo la spedizione. Dazi e imposte d'importazione sono a carico del destinatario.

Ordini

Quando l'ordine viene effettuato, il modulo conserva la tariffa calcolata per il suo carrello. La pagina dell'ordine nel back office mostra quindi un blocco DHL Express Africa, così sai 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.

I successivi ricalcoli del carrello, per esempio quando l'ordine viene modificato nel back office, non cambiano questi valori. Le tariffe dei carrelli che non sono mai diventati ordini vengono rimosse dopo 30 giorni.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox DHL Africa è il primo blocco della pagina Modules > Module Manager > VibeFox DHL Africa > Configure, 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 si trovano la riga Product: presta-shipping-dhl-africa 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 cambiare 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 o License expired on seguito da una data. Dopo aver cambiato l'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, il modulo continua a funzionare con l'ultimo stato noto.

Una chiave funziona su un solo dominio: il dominio 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 DHL Express non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Il front office di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il corriere è nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non provarlo 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 ricontrollato automaticamente mentre lavori nel back office: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve alcun cron job. La disinstallazione o il ripristino del modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

DHL Express non compare al checkout: verifica che la licenza sia attiva e che Enable DHL Express Africa 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 i limiti di peso e Minimum subtotal. Senza una tariffa in tempo reale il corriere compare solo se è impostato un prezzo per paese o un costo alternativo. I prodotti possono anche essere limitati a determinati corrieri nella pagina del prodotto.

Le tariffe in tempo reale non compaiono: controlla gli avvisi in cima alla pagina del modulo (credenziali o origine mancanti). Attiva il Debug log, ricarica il checkout e guarda il campo Log nella pagina del modulo. Gli errori DHL, come un errore HTTP della MyDHL API, nessun prodotto per la tratta o un problema di valuta, vengono sempre registrati. Verifica 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 mio negozio usa un'altra valuta: il registro riporta 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 alternativi.

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

La spedizione viene tassata due volte: imposta una regola fiscale in Tax così la tariffa DHL viene presa senza l'IVA di DHL, oppure scegli No tax per addebitare l'importo DHL così come quotato.

Le tariffe sembrano obsolete dopo una modifica: clicca su Save nella pagina del modulo. Questo cancella i preventivi DHL in cache.

La pagina dice che il corriere DHL Express non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Ripristina il modulo in Modules > Module Manager per ricrearlo.

Per gli sviluppatori, il modulo fornisce gli hook actionVfdDhlaApiUrl, actionVfdDhlaIsDutiable, actionVfdDhlaPackageBox, actionVfdDhlaRestRequest e actionVfdDhlaXmlRequest per modificare l'indirizzo dell'API, la dichiarazione doganale, il box e le richieste a DHL.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox DHL Africa e scegli Uninstall. La chiave di licenza, lo stato della licenza e i preventivi DHL in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini mantengono lo storico) e vengono rimosse le impostazioni, i prodotti DHL salvati degli ordini e il registro. Se è disattivo, il corriere viene solo disabilitato e le impostazioni e i prodotti DHL degli ordini effettuati vengono conservati. Reinstallando il modulo viene ripristinato lo stato che il corriere aveva prima.

DHL è un marchio registrato del rispettivo titolare. Questo modulo non è affiliato a DHL né approvato da DHL.