VibeFox DHL Packstation 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). Il selettore dei punti di ritiro funziona con il checkout standard di OpenCart.

PHP: 8.0 o successivo.

Chiave API DHL: l'elenco dei punti proviene dall'API gratuita DHL Location Finder. Registrati sul portale per 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 metodo viene nascosto al checkout. Tieni presente il limite di richieste della tua app DHL: ogni nuova ricerca per codice postale o città è una richiesta API.

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_packstation-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_dhl_packstation.ocmod.zip. Installa solo il pacchetto per la 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_packstation-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 Packstation 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 chiave di licenza VibeFox nel campo License key nel blocco della licenza in alto nella pagina Edit e clicca su Activate (vedi Chiave di licenza).

5. Incolla la chiave API DHL, clicca su Save, poi su Test API key. Scegli i tipi di punto di ritiro e inserisci i prezzi per paese (vedi Configuration). Attiva Enable/Disable e clicca su Save.

OpenCart 4

1. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_dhl_packstation.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 Packstation, 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/Disable e salvi. Il listino predefinito contiene prezzi per la Germania e l'Austria e un prezzo per gli altri paesi. Se reinstalli l'estensione dopo una disinstallazione, vengono di nuovo usate le impostazioni che avevi conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox DHL Packstation > Edit. Le sezioni sono elencate a sinistra. Un unico pulsante Save salva l'intera pagina senza ricaricarla. Ogni salvataggio svuota la cache dei punti. Se un campo contiene un errore (un nome non valido o più lungo di 64 caratteri, un raggio o un numero di risultati che non è un intero, un numero non valido o negativo, Min weight (kg) maggiore di Max weight (kg), un ordine di visualizzazione che non è un intero, una classe fiscale o una zona geografica sconosciute), non viene salvato nulla e l'errore viene mostrato. 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 la chiave API DHL è vuota, quando non è attivo alcun tipo di punto di ritiro (in entrambi i casi il metodo non viene mostrato al checkout), quando le voci di prezzo per paese non sono nel formato CC:PRICE (queste voci vengono ignorate), e quando non esiste una classe di peso con unità kg in System > Localisation > Weight Classes (i pesi dei prodotti vengono allora letti in base al nome dell'unità della loro classe: kg, g, lb o oz; le unità sconosciute come kg).

Generali

Le impostazioni si applicano a tutte le zone geografiche.

Enable/Disable: attiva DHL Packstation al checkout. Predefinito: off.

Name: il nome del metodo di spedizione mostrato al cliente. Predefinito: DHL Packstation. Obbligatorio, massimo 64 caratteri, senza i caratteri < > ; = # { }.

Tax Class: la classe fiscale del costo di spedizione, oppure --- None --- (predefinito). OpenCart aggiunge questa imposta ai prezzi sotto. Con --- None --- i prezzi sono definitivi.

Sort Order: la posizione di DHL Packstation tra i metodi di spedizione. Un numero intero.

API DHL Location Finder

DHL API key: la «API Key» della tua app su developer.dhl.com. Senza di essa il metodo viene nascosto al 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: visibile quando una chiave è salvata. Spunta questa casella e salva per eliminare la chiave memorizzata.

Connection test: il pulsante Test API key cerca i punti vicini a 53113 Bonn con la chiave salvata e svuota la cache dei punti. Salva prima le impostazioni. Mostra quanti punti sono stati trovati (Connected: … DHL locations found near 53113 Bonn.), che DHL ha rifiutato la chiave (401/403), oppure che l'API non ha risposto correttamente (dettagli nel registro di debug).

Punti di ritiro

Al checkout il cliente vede i punti vicini al codice postale di spedizione e può cercarne un altro per codice postale o città.

Location types: quali punti DHL il cliente può scegliere: Packstation (parcel locker), Post Office (Postfiliale) e DHL Parcel Shop (Paketshop). Di default sono attivi tutti e tre. Se non ne viene selezionato nessuno, il metodo viene nascosto. Per una Packstation il cliente deve inserire il proprio DHL Postnummer.

Search radius (meters): il raggio intorno al codice postale o alla città cercati. Predefinito: 5000. Un numero intero; i valori inferiori a 100 o superiori a 25000 m (il massimo di DHL) vengono portati a quel limite.

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

Shipping address: usa il punto scelto come indirizzo di spedizione dell'ordine. Attivo per impostazione predefinita. La riga 1 dell'indirizzo diventa per esempio «Packstation 105» (o «Postfiliale 502» per un ufficio postale o un DHL Parcel Shop), la riga 2 «Postnummer» con il numero, più il codice postale, la città e il paese del punto, in modo che le etichette stampate dall'ordine arrivino nel posto giusto. Nome, azienda e telefono provengono dall'indirizzo del cliente. La regione viene svuotata. La rubrica indirizzi del cliente non viene modificata.

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

Country prices: il prezzo per paese di destinazione nella valuta predefinita del negozio, IVA esclusa, nel formato CC:PRICE, separati 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 che non è in Country prices. Predefinito: 5.99. Lascialo vuoto per nascondere il metodo per questi paesi.

Calculation: Per order (predefinito) 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 dei prodotti che richiedono spedizione (dopo il coupon, prima delle imposte) a partire dal quale questa spedizione è gratuita. Lascialo vuoto per non averla mai gratuita.

Disponibilità

Min weight (kg): il peso minimo del carrello. I pesi dei prodotti vengono convertiti dalla loro classe di peso. 0 significa nessun limite (predefinito).

Max weight (kg): il metodo viene 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 metodo solo se il subtotale dei prodotti che richiedono spedizione (dopo il coupon, prima delle imposte) è almeno questo valore. Lascialo vuoto per mostrarlo sempre.

Geo Zone: offri il metodo solo in questa zona geografica. All Zones (predefinito) significa nessun limite. Le zone geografiche si gestiscono in System > Localisation > Geo Zones. Non viene usato con Ignore shipping zones.

Ignore shipping zones: se attivo, il metodo viene offerto per i paesi qui sotto (tutti i paesi se l'elenco è vuoto), qualunque sia la zona geografica dell'indirizzo.

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

Avanzate

Debug log: scrive richieste API e passaggi del checkout in storage/logs/vfd_dhlp_debug.log.php (in OpenCart 4 system/storage/logs/vfd_dhlp_debug.log.php). Il file non può essere letto dal web. Gli errori API vengono sempre registrati, anche quando l'opzione è disattiva. La chiave API, il Postnummer e gli indirizzi dei clienti non vengono mai scritti. Quando il file raggiunge 5 MB, viene spostato in vfd_dhlp_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 eliminati impostazioni, ricerche in cache, registro e punti dei checkout non completati. I punti scelti restano negli ordini. Se disattivo (predefinito), tutto viene conservato per una reinstallazione.

Importazione / Esportazione

Export: clicca su Download JSON per salvare le impostazioni in un file JSON. La chiave API non viene esportata.

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. La chiave API salvata viene mantenuta.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di DHL Packstation. Se è impostata una Geo Zone (e Ignore shipping zones è disattivo) e l'indirizzo è al di fuori di essa, il metodo 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 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 del paese di destinazione (o il prezzo per gli altri paesi) e applica la spedizione gratuita se il subtotale è sufficiente. Il subtotale è il prezzo dei prodotti che richiedono spedizione, dopo lo sconto del coupon e prima delle imposte. Il prezzo non dipende dal punto di ritiro e per calcolarlo non viene inviata alcuna richiesta a DHL. Viene calcolato nella valuta predefinita e mostrato al cliente nella sua valuta con l'imposta della Tax Class selezionata.

L'estensione 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. L'estensione non calcola tariffe DHL in tempo reale e non mostra mappe. Non esiste l'inserimento manuale di un numero di Packstation.

Punti di ritiro

Quando il cliente seleziona DHL Packstation nel passaggio del metodo di spedizione, sotto il metodo compare un selettore. Vengono caricati i punti DHL vicini al codice postale e alla città di consegna. Il cliente può digitare un altro codice postale o un'altra città e cliccare su Search. I punti sono raggruppati per tipo (Packstation, Post Office, Parcel Shop) e ordinati per distanza. Se non viene trovato 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 di 6–12 cifre, dall'app DHL o dal proprio account DHL. Per gli altri punti è facoltativo. La scelta viene salvata appena effettuata. Cliccando su Continue il server la controlla 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. Se il Postnummer di una Packstation manca, compare Please enter your DHL Postnummer - it is required for delivery to a Packstation., se non è valido The DHL Postnummer must consist of 6 to 12 digits.

I risultati di ricerca vengono memorizzati nella cache per 12 ore. Una ricerca vuota o fallita viene memorizzata per 10 minuti, così il checkout non attende DHL a ogni aggiornamento. Con la cache su file predefinita di OpenCart, le voci durano al massimo quanto la durata della cache del negozio (1 ora di default), quindi l'elenco viene aggiornato una volta all'ora. 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.

In OpenCart 4 il cliente clicca su Choose nel blocco del metodo di spedizione della pagina di checkout e sceglie DHL Packstation nella finestra Shipping method options. Il selettore compare in quella finestra sotto il metodo e funziona come descritto sopra. Il pulsante Continue della finestra non procede senza un punto valido o, per una Packstation, senza il Postnummer, con gli stessi messaggi.

Quando l'ordine viene effettuato, il punto (ID, tipo, numero, nome, indirizzo) e il Postnummer vengono salvati con l'ordine. Il punto viene aggiunto al metodo di spedizione dell'ordine come DHL pickup location: e DHL Postnummer:, quindi compare ovunque OpenCart mostri il metodo di spedizione: nella pagina ordine del cliente, nelle e-mail dell'ordine e sulla fattura. Se Shipping address è attivo, l'indirizzo di spedizione dell'ordine viene sostituito con quello del punto.

In OpenCart 4 il checkout usa un unico ordine, che viene aggiornato ogni volta che il cliente conferma di nuovo. Con esso vengono aggiornati il punto, il testo del metodo di spedizione e l'indirizzo dell'ordine.

Ordini

Apri l'ordine in Sales > Orders. Il pannello DHL pickup location sopra la cronologia dell'ordine mostra il punto, il suo tipo e ID, e il Postnummer, anche dopo aver disattivato l'estensione. Un ordine senza punto mostra No DHL location was selected for this order.

Clicca su Change, cerca per codice postale o città, scegli un altro punto dalla lista DHL, modifica il Postnummer se necessario e clicca su Save location. Puoi anche modificare solo il Postnummer. Il testo del metodo di spedizione dell'ordine viene aggiornato. Se Shipping address è attivo, anche l'indirizzo di spedizione dell'ordine viene aggiornato, ripartendo dall'indirizzo originale del cliente. Ogni modifica aggiunge alla cronologia dell'ordine una voce DHL pickup location changed to: …, con lo stato attuale dell'ordine e senza notificare il cliente. Modificare il punto richiede il permesso di modifica degli ordini; l'accesso alle impostazioni dell'estensione non serve.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza License — VibeFox DHL Packstation è il primo blocco nella pagina Extensions > Extensions > Shipping > VibeFox DHL Packstation > Edit, sopra le impostazioni. Incolla la chiave in License key e clicca su Activate. Dopo questo 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 si trovano la riga Product: opencart-shipping-dhl-packstation 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 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 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 nella configurazione di OpenCart. 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 metodo di spedizione DHL Packstation non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Un utente amministratore connesso all'amministrazione nello stesso browser vede comunque il metodo nel negozio, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e provare l'estensione prima di acquistare una chiave. In OpenCart 4 questa anteprima non è disponibile: il negozio non vede l'accesso all'amministrazione, quindi senza una chiave attiva il metodo è nascosto a tutti. Dopo aver aperto una volta la pagina Edit, nella Dashboard dell'amministrazione compare un promemoria. 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 dell'amministrazione o la pagina Edit: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve un cron job. Disinstallando l'estensione vengono sempre rimossi la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

DHL Packstation non compare al checkout: controlla che la licenza sia attiva e che Enable/Disable sia attivo. Controlla Geo Zone (oppure attiva Ignore shipping zones e controlla Countries (ignore zones)). Controlla che la DHL API key sia compilata, che sia selezionato almeno un tipo di punto, che il paese di destinazione abbia un prezzo (o che Other countries sia impostato), e che le regole di peso e subtotale non lo nascondano. Controlla che i prodotti abbiano Requires Shipping impostato su Yes.

Non viene mostrato nessun punto: 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 guarda il campo Log nella pagina dell'estensione. Controlla che il limite di richieste della tua app DHL non sia stato raggiunto.

Nessun punto vicino a un indirizzo: aumenta Search radius (meters) o Max results, oppure lascia che il cliente cerchi un altro codice postale o 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 codice postale né città. Il cliente può inserirne uno nel campo di ricerca.

Change nella pagina ordine dell'amministrazione dice "Please choose a DHL location of the search - nothing was changed.": cerca per codice postale 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.

Il pannello DHL pickup location manca nella pagina ordine: il pannello viene mostrato solo per gli ordini spediti con DHL Packstation (resta visibile anche con l'estensione disattivata).

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

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox DHL Packstation. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable/Disable, Sort Order, Tax Class e Geo Zone. La cache dei punti e gli eventi dell'estensione vengono sempre eliminati. Se Remove data on uninstall è attivo, vengono eliminati anche impostazioni, registro e punti dei checkout non completati. Se è disattivo, le altre impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. I punti scelti restano sempre negli ordini, e gli ordini esistenti mantengono il loro metodo di spedizione, costo e indirizzo.

In OpenCart 4, per rimuovere anche i file dell'estensione, dopo la disinstallazione vai su Extensions > Installer, clicca su Uninstall (il pulsante arancione −) accanto a VibeFox DHL Packstation nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per eliminare il pacchetto caricato.

DHL e Packstation sono marchi dei rispettivi proprietari. Questa estensione non è affiliata a DHL né approvata da DHL.