VibeFox DHL Packstation for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x. Sono supportati i temi Classic e Hummingbird.

PHP: 8.0 o successivo. Il modulo non si installa su versioni precedenti di PHP.

DHL API key: l'elenco delle sedi proviene dalla DHL Location Finder API gratuita. Registrati sul portale sviluppatori DHL (developer.dhl.com), crea un'app, aggiungi l'API «Location Finder - Unified» e copia la chiave API dell'app. Per questa API non serve un contratto commerciale con DHL. Senza la chiave il corriere è nascosto nel checkout. Tieni presente il limite di richieste della tua app DHL: ogni nuova ricerca per CAP o città è una richiesta API.

VibeFox license key: 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 trova più tardi VibeFox DHL Packstation 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. Incolla la chiave API DHL, clicca su Save, poi su Test API key. Scegli i tipi di punto e inserisci i prezzi per paese (vedi Configurazione).

All'installazione il modulo crea il corriere DHL Packstation con il testo del tempo di consegna Delivery to a DHL Packstation or post office. Il corriere è attivo, assegnato a tutti i gruppi di clienti e alle zone di Germania e Austria (i paesi del listino predefinito). Puoi modificare zone, gruppi di clienti, tempo di consegna, logo e limiti di dimensione in Shipping > Carriers. Non impostare i prezzi lì: il prezzo arriva sempre dal modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox DHL Packstation > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Se un campo contiene un errore (un numero non valido o negativo, Min weight (kg) maggiore di Max weight (kg), un nome più lungo di 64 caratteri), non viene salvato nulla e l'errore compare in alto. Ogni salvataggio svuota la cache dei punti.

Gli avvisi sopra le impostazioni segnalano quando il corriere non è stato trovato, quando l'unità di peso del negozio (International > Localization, Local units) non è riconosciuta dal modulo (i pesi vengono letti come kg; usa kg, g, lb o oz), quando la chiave API DHL è vuota, quando non è attivo nessun tipo di punto e quando le voci di prezzo per paese non sono nel formato CC:PRICE (tali voci vengono ignorate).

Generali

Gruppi di clienti, zone e limiti di dimensione del corriere si impostano in Shipping > Carriers. Le impostazioni seguenti valgono per tutte le zone.

Enable/Disable: attiva o disattiva il corriere. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.

Name: il nome del corriere mostrato al cliente. Predefinito: DHL Packstation. Obbligatorio, massimo 64 caratteri.

Tax: la regola fiscale del corriere, oppure No tax. PrestaShop aggiunge questa imposta ai prezzi sotto. Con No tax i prezzi sono definitivi.

DHL Location Finder API

DHL API key: la «API Key» della tua app su developer.dhl.com. Senza di essa il corriere è nascosto nel checkout. Dopo il salvataggio il campo resta vuoto e mostra Saved - leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.

Remove the saved API key: spunta questa casella e salva per eliminare la chiave memorizzata.

Connection test: il pulsante Test API key cerca le sedi vicine a 53113 Bonn con la chiave salvata e svuota la cache dei punti. Salva prima le impostazioni. Mostra quante sedi sono state trovate, se DHL ha rifiutato la chiave (401/403) o se l'API non ha risposto correttamente (dettagli nel log di debug).

Punti di ritiro

Nel checkout il cliente vede i punti vicino al CAP di consegna e può cercare un altro CAP o un'altra città.

Location types: quali sedi DHL il cliente può scegliere: Packstation (parcel locker), Post Office (Postfiliale) e DHL Parcel Shop (Paketshop). Tutte e tre sono attive per impostazione predefinita. Se non ne è selezionata nessuna, il corriere è nascosto. Per una Packstation il cliente deve inserire il proprio DHL Postnummer.

Search radius (meters): il raggio attorno al CAP o alla città cercati. Predefinito: 5000. Numero intero; i valori sotto 100 o sopra 25000 m (il massimo DHL) vengono portati a quel limite.

Max results: il numero massimo di punti mostrati per ricerca. Predefinito: 20. Numero intero; DHL consente fino a 50, i valori più alti vengono ridotti a 50.

Shipping address: usa il punto scelto come indirizzo di consegna dell'ordine. Attivo per impostazione predefinita. La riga 1 dell'indirizzo diventa, ad esempio, «Packstation 105» (o «Postfiliale 502» per un Post Office o un Parcel Shop), la riga 2 «Postnummer» con il numero, più CAP, città e paese del punto, così le etichette stampate dall'ordine arrivano nel posto giusto. Nome, azienda e telefono provengono dall'indirizzo del cliente. Il nuovo indirizzo è usato solo dall'ordine e non compare nella rubrica del cliente.

Prezzi (il titolo della sezione mostra la valuta predefinita del negozio)

Country prices: il prezzo per paese di destinazione nella valuta predefinita del negozio, IVA esclusa, formato CC:PRICE, separato da virgole o a capo. Predefinito: DE:4.99, AT:5.99. Funziona anche la virgola decimale (DE:4,99).

Other countries: il prezzo per un paese di destinazione non presente in Country prices. Predefinito: 5.99. Lascialo vuoto per nascondere il corriere per tali paesi.

Calculation: Per order addebita il prezzo una sola volta. Per item (price x quantity) lo moltiplica per il numero di articoli nel carrello.

Free shipping from: il subtotale del carrello (prodotti che richiedono spedizione, dopo sconti, prima delle imposte) da cui questa spedizione è gratuita. Lascia vuoto se non deve mai essere gratuita.

Disponibilità

Min weight (kg): il peso minimo del carrello. I pesi dei prodotti vengono convertiti dall'unità di peso del negozio. 0 significa nessun limite.

Max weight (kg): il corriere è nascosto sopra questo peso del carrello. Predefinito: 31.5, perché una Packstation accetta pacchi fino a 31,5 kg. 0 significa nessun limite.

Minimum subtotal: mostra il corriere solo se il subtotale del carrello (prodotti che richiedono spedizione, dopo sconti, prima delle imposte) è almeno questo valore. Lascia vuoto per mostrarlo sempre.

Ignore shipping zones: se attivo, il corriere è collegato a tutte le zone attive (anche a quelle create in seguito) ed è offerto per i paesi sotto, o per tutti i paesi se l'elenco è vuoto. Quando lo disattivi di nuovo, il corriere riottiene le zone che aveva prima.

Countries (ignore zones): i paesi di destinazione per questa modalità. Ctrl/Cmd + clic per selezionarne più di uno. Usato solo con Ignore shipping zones.

Avanzate

Debug log: scrive richieste API e passaggi del checkout in logs/vfd_dhlp_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori API vengono sempre registrati, anche quando l'opzione è disattivata. La chiave API, il Postnummer e gli indirizzi dei clienti non vengono mai scritti.

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

Remove data on uninstall: se attivo, la disinstallazione del modulo elimina impostazioni, corriere, ricerche in cache e log. I punti scelti restano negli ordini. Se disattivo, tutto viene conservato per una reinstallazione.

Come funziona nel checkout

Nel passaggio di consegna PrestaShop chiede al modulo il prezzo di DHL Packstation. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nel subtotale. Il modulo verifica che siano impostati una chiave API e almeno un tipo di punto, i paesi consentiti (con Ignore shipping zones), il peso del carrello e il subtotale minimo. Poi prende il prezzo per il paese di destinazione (o il prezzo per gli altri paesi) e applica la spedizione gratuita se il subtotale è abbastanza alto. Il prezzo viene calcolato nella valuta predefinita del negozio e mostrato nella valuta del carrello del cliente.

Se modifichi il corriere in Shipping > Carriers dopo che ha ricevuto ordini, PrestaShop lo salva come nuova versione del corriere. Il modulo segue automaticamente la nuova versione.

Il modulo non crea spedizioni DHL, non stampa etichette e non traccia i pacchi. Usa il portale clienti business di DHL o uno strumento per le etichette: con Shipping address attivo, l'ordine contiene già l'indirizzo della Packstation e il Postnummer. Il modulo non calcola tariffe DHL in tempo reale e non mostra una mappa. Non esiste l'inserimento manuale di un numero di Packstation.

Punti di ritiro

Quando il cliente seleziona DHL Packstation, sotto il corriere compare un selettore. Vengono caricate le sedi DHL vicine al CAP e alla città di consegna. DHL viene interrogata solo per il corriere selezionato. Il cliente può inserire un altro CAP o un'altra città e cliccare su Search. Le sedi sono raggruppate per tipo (Packstation, Post Office, Parcel Shop) e ordinate per distanza. Se non si trova nulla, il cliente vede No DHL locations found near "…". Try another postcode or city.

Per una Packstation il cliente deve inserire il DHL Postnummer, il suo numero cliente DHL da 6-12 cifre, presente nell'app o nell'account DHL. Per gli altri punti è facoltativo. La scelta viene salvata nel carrello non appena viene fatta. Cliccando su Continue, il server la verifica di nuovo: il punto deve essere uno dei risultati di ricerca DHL nel paese di consegna. Senza un punto il cliente vede Please choose a DHL Packstation or post office for delivery. e non può proseguire. Un Postnummer mancante o non valido viene segnalato allo stesso modo.

I risultati di ricerca vengono memorizzati in cache per 12 ore. Una ricerca vuota o fallita viene memorizzata in cache per 10 minuti, così il checkout non attende DHL a ogni aggiornamento. Il timeout dell'API è di 12 secondi. Se l'API DHL non è raggiungibile, il cliente vede DHL locations cannot be loaded right now. Please try again later or choose another shipping method. Un punto già scelto dal cliente continua a essere accettato.

Quando l'ordine viene effettuato, il punto (ID, tipo, numero, nome, indirizzo) e il Postnummer vengono salvati con l'ordine. Se Shipping address è attivo, l'indirizzo di consegna dell'ordine viene sostituito con quello del punto. Il punto è mostrato nella pagina di conferma dell'ordine, in Order history and details dell'account del cliente, e nell'e-mail di conferma dell'ordine e nell'e-mail di nuovo ordine del modulo Mail alerts, con le voci DHL pickup location e DHL Postnummer aggiunte al nome del corriere.

Nella pagina dell'ordine nel back office, il blocco DHL pickup location mostra il punto, il suo tipo e ID, e il Postnummer. Clicca su Change, cerca per CAP o città, scegli un altro punto, modifica il Postnummer e clicca su Save location. Puoi anche modificare solo il Postnummer. Ogni modifica aggiunge all'ordine un messaggio privato DHL pickup location changed to: …. Se Shipping address è attivo, anche l'indirizzo di consegna dell'ordine viene aggiornato. Modificare il punto richiede il permesso di modificare gli ordini; l'accesso alle pagine dei moduli non è necessario. Se da un carrello sono stati creati più ordini, il punto appartiene solo al primo ordine; Change su un altro ordine dello stesso carrello mostra The DHL location of this cart belongs to another order of the same cart - nothing was changed.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox DHL Packstation è il primo blocco della pagina Modules > Module Manager > VibeFox DHL Packstation > 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-packstation 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 Packstation non viene mostrato ai clienti nel 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 nel 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 del modulo rimuove sempre la chiave di licenza e lo stato della licenza. Il Reset di questo modulo non cancella i dati, quindi la chiave e lo stato vengono mantenuti.

Risoluzione dei problemi

DHL Packstation non compare nel checkout: verifica che la licenza sia attiva e che Enable/Disable 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 (ignore zones)). Verifica che DHL API key sia compilata, che sia selezionato almeno un tipo di punto, che il paese di destinazione abbia un prezzo (o che sia impostato Other countries) e che le regole su peso e subtotale non lo nascondano. Anche i prodotti possono essere limitati a certi corrieri nella pagina del prodotto.

Non viene mostrata nessuna sede: clicca su Test API key. Se DHL rifiuta la chiave (401/403), controlla la chiave e che la tua app abbia l'API «Location Finder - Unified». Attiva Debug log, ricarica il checkout e controlla il campo Log nella pagina del modulo. Verifica che il limite di richieste della tua app DHL non sia stato raggiunto.

Nessuna sede vicino a un indirizzo: aumenta Search radius (meters) o Max results, oppure lascia che il cliente cerchi un altro CAP o un'altra città. Una Packstation senza numero nei dati DHL non viene elencata.

Il cliente vede «Enter your postcode or city to see DHL locations near you.»: l'indirizzo di consegna non ha CAP né città. Il cliente può inserirne uno nel campo di ricerca.

Nella pagina dell'ordine, Change mostra «Please choose a DHL location of the search - nothing was changed.»: cerca per CAP o città e scegli un punto tra i risultati. Se l'ordine non ha ancora un punto, bisogna sceglierlo prima di poter salvare il Postnummer.

La pagina segnala che il corriere DHL Packstation non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Ripristina il modulo con Reset in Modules > Module Manager per ricrearlo. Reset mantiene lo stato attivo/disattivo di un corriere esistente.

Disinstallazione

Vai in Modules > Module Manager, apri il menu accanto a VibeFox DHL Packstation e scegli Uninstall. La chiave di licenza, lo stato della licenza e la cache dei punti vengono sempre eliminati. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini conservano la cronologia), e vengono rimosse le impostazioni, il log e i punti dei carrelli senza ordine. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni vengono mantenute. Reinstallando il modulo si ripristina lo stato del corriere precedente. I punti scelti restano sempre negli ordini.

DHL e Packstation sono marchi dei rispettivi proprietari. Questo modulo non è affiliato a DHL né approvato da DHL.