VibeFox bpost Cubee for OpenCart — Guida
Requisiti
OpenCart: 3.0.x (testato con 3.0.5.0) o 4.0.2 e successive (testato con 4.1.0.3).
PHP: 8.0 o successivo.
Account bpost Shipping Platform (solo per il selettore dei punti di ritiro): l'estensione cerca i punti di ritiro tramite l'API di bpost Shipping Platform. Accedi al tuo account bpost Shipping Platform su plugins.bpost.be e crea le chiavi in Settings > Key management. Ti servono tre valori: Account ID (chiave pubblica), Passphrase (chiave privata) e un App ID (X-APPID). L'App ID viene rilasciato da bpost per la tua integrazione; chiedi al supporto e-commerce di bpost (eol@bpost.be). Ti serve anche l'ID del corriere del tuo contratto (68 = bpost). Senza chiavi complete il metodo funziona comunque con prezzi fissi, ma al cliente non viene chiesto di scegliere un punto di ritiro.
Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un solo dominio.
Installazione
Il download è un unico file zip con i pacchetti per entrambe le versioni di OpenCart. Estrailo sul tuo computer. Contiene README.txt, il pacchetto per OpenCart 3 vfd_bpost_cubee-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_bpost_cubee.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. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_bpost_cubee-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non serve aggiornare Extensions > Modifications. In alternativa all'Installer, puoi copiare il contenuto della cartella upload del pacchetto nella cartella radice del tuo negozio.
2. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox bpost Cubee 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 in License key nel blocco di licenza in alto nella pagina Edit, poi clicca su Activate (vedi Chiave di licenza).
5. Inserisci i tuoi prezzi, per esempio BE=4.95 e *=9.95, e, per il selettore dei punti di ritiro, le chiavi API di bpost (vedi Configurazione). Attiva Enable/Disable e clicca su Save.
OpenCart 4
1. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_bpost_cubee.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 Shipping. Trova VibeFox bpost Cubee, 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 lo attivi e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni che hai conservato.
Configurazione
Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox bpost Cubee > Edit. Le sezioni sono elencate a sinistra. Un solo pulsante Save salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella anche il token API memorizzato e gli elenchi dei punti di ritiro in cache. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.
Alcuni errori bloccano il salvataggio e non viene salvato nulla: un Name di oltre 64 caratteri, un Sort Order che non è un numero intero, o una classe fiscale o una zona geografica sconosciuta. Gli altri problemi vengono segnalati come avvisi e il resto viene salvato: un peso o un importo che non è un numero o è negativo non viene salvato e resta il valore precedente; se Min weight (kg) è maggiore di Max weight (kg), i pesi non vengono salvati; le righe di Country prices che non è stato possibile leggere vengono elencate e ignorate; un valore di Size prices in cui non è stata riconosciuta alcuna dimensione viene segnalato.
In alto nella pagina compare un avviso quando qualcosa nasconde in silenzio il metodo o il selettore: il selettore dei punti di ritiro è attivo ma le chiavi API sono incomplete, non c'è un prezzo per il Belgio (BE) né un prezzo predefinito (*=PREZZO), l'ultima connessione all'API di bpost è fallita, oppure il negozio non ha una classe di peso con l'unità "kg" (System > Localisation > Weight Classes). In quest'ultimo caso i pesi dei prodotti vengono letti in base al nome della loro unità (kg, g, lb o oz).
Generale
Enable/Disable: attiva o disattiva la spedizione in armadietti bpost al checkout. Predefinito: disattivato.
Name: il nome del metodo di spedizione mostrato al cliente al checkout. Predefinito: bpost parcel locker. Se lo lasci vuoto, viene usato il valore predefinito. Massimo 64 caratteri.
Tax Class: l'imposta di questa classe viene aggiunta ai tuoi prezzi. --- None --- (predefinito) significa che i prezzi sono definitivi.
Sort Order: la posizione del metodo nell'elenco dei metodi di spedizione.
API di bpost (ricerca dei punti di ritiro) (necessaria solo per il selettore dei punti di ritiro)
Account ID (public key): la chiave pubblica del tuo account bpost Shipping Platform, da Key management su plugins.bpost.be. Svuotare questo campo rimuove anche la passphrase salvata.
Passphrase (private key): la chiave privata usata per firmare ogni richiesta (HMAC-SHA256). Non viene mai inviata a bpost né scritta nel registro. Dopo il salvataggio il campo resta vuoto e mostra Saved - leave empty to keep it. Inserisci un valore nuovo solo per cambiarlo.
App ID (X-APPID): l'identificativo dell'applicazione rilasciato da bpost per la tua integrazione. Viene inviato nell'intestazione X-APPID.
Carrier ID: il corriere del tuo contratto bpost Shipping Platform di cui vengono elencati i punti di ritiro e gli armadietti. Predefinito: 68 (bpost). Gli altri corrieri abilitati nel tuo contratto hanno ID propri.
Selettore del punto di ritiro
Pickup points: mostra al checkout il selettore di punti di ritiro e armadietti. Attivo di default. Il selettore compare, e la scelta di un punto è obbligatoria, solo quando Account ID, Passphrase e App ID sono tutti compilati.
Search field width: la larghezza CSS del campo codice postale / città, per esempio 100% o 300px. Predefinito: 100%.
Pickup point list width: la larghezza CSS dell'elenco dei punti di ritiro, per esempio 100% o 400px. Predefinito: 100%.
Prezzi (nella valuta predefinita del tuo negozio, IVA esclusa; bpost non restituisce prezzi di spedizione tramite questa API)
Price by: come viene scelto il prezzo.
Country prices: una riga per paese nella forma CC=PREZZO, per esempio BE=4.95. La riga *=PREZZO imposta il prezzo per tutti gli altri paesi, per esempio *=9.95. Vengono accettati sia il punto sia la virgola come separatore decimale. Le righe non valide vengono ignorate. I paesi senza prezzo (quando non c'è una riga *) non ricevono il metodo.
Size prices: usato quando Price by è la dimensione del pacco, nella forma S=3.50, M=4.50, L=6.00, XL=8.00. La dimensione deriva dal peso del carrello: S fino a 2 kg, M fino a 5 kg, L fino a 10 kg, XL oltre.
Calculation: Per order (predefinito) addebita il prezzo una volta. Per item (price x number of items) lo moltiplica per il numero di articoli nel carrello.
I prezzi vengono arrotondati alle cifre decimali della valuta predefinita del negozio e poi mostrati nella valuta del cliente.
Condizioni
Min weight (kg): il peso minimo del carrello perché il metodo compaia. I pesi dei prodotti vengono convertiti in kg. 0 significa nessun limite (predefinito).
Max weight (kg): il metodo viene nascosto sopra questo peso del carrello. Predefinito: 30, perché gli armadietti bpost accettano pacchi fino a 30 kg. 0 significa nessun limite.
Minimum order amount: mostra il metodo solo quando il subtotale del carrello raggiunge questo importo. Il subtotale conta i prodotti da spedire, dopo i coupon, IVA esclusa. Lascialo vuoto per mostrare sempre il metodo.
Spedizione gratuita
Free shipping: attiva la consegna gratuita a partire dall'importo indicato sotto.
Free shipping from: il subtotale del carrello (prodotti da spedire, dopo i coupon, IVA esclusa) da cui la spedizione è gratuita. Viene usato solo quando Free shipping è attivo. Il paese deve comunque avere un prezzo, altrimenti il metodo non viene offerto.
Disponibilità
Normalmente il metodo viene offerto nella zona geografica selezionata sotto. Con Ignore geo zone viene offerto invece nei paesi dell'elenco.
Geo Zone: offre il metodo solo per gli indirizzi in questa zona geografica. All Zones (predefinito) significa ovunque. Le zone geografiche si gestiscono in System > Localisation > Geo Zones.
Ignore geo zone: offre il metodo nei paesi dell'elenco, indipendentemente dalla zona geografica.
Countries: i paesi di destinazione per quella modalità. Predefinito: Belgium. Lascialo vuoto per consentire tutti i paesi. Viene usato solo quando Ignore geo zone è attivo.
Avanzate
Debug log: scrive le richieste API e i calcoli dei prezzi in storage/logs/vfd_bpst_debug.log.php. Il file non può essere letto dal web. Gli errori dell'API vengono sempre registrati, anche con questa opzione disattivata. Chiavi e token non vengono mai registrati.
Log: mostra la dimensione e le ultime voci del registro di debug. Clicca su Clear log per svuotarlo.
Remove data on uninstall: quando è attivo, disinstallando l'estensione vengono cancellati impostazioni, registro e scelte dei punti di ritiro dei checkout non completati. I punti di ritiro salvati negli ordini vengono sempre conservati. Predefinito: disattivato.
Importazione / Esportazione
Export: clicca su Download JSON per salvare le impostazioni in un file JSON. La passphrase non viene esportata.
Import: incolla un JSON esportato in precedenza e clicca su Import per ripristinare le impostazioni, per esempio su un altro negozio. I valori vengono controllati come in un normale salvataggio. La passphrase salvata viene conservata.
Come funziona al checkout
Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di bpost. Se è impostata una Geo Zone (e Ignore geo zone è disattivato) e l'indirizzo si trova al di fuori, il metodo non viene offerto. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri prodotti non aggiungono peso e non rientrano nell'importo dell'ordine. L'estensione verifica le condizioni: i paesi di Ignore geo zone (se attivo), il peso del carrello e l'importo minimo dell'ordine. Poi prende il prezzo dall'elenco dei paesi o per dimensione del pacco, lo moltiplica per il numero di articoli nella modalità per articolo e lo azzera quando si applica la spedizione gratuita. Per il prezzo non viene inviata alcuna richiesta a bpost.
Sotto l'opzione bpost il cliente vede un campo Postal code or city, un pulsante Search e un elenco di punti di ritiro. Quando il cliente sceglie bpost e l'elenco non è ancora caricato, il codice postale dell'indirizzo di consegna (o l'ultima ricerca del cliente) viene cercato automaticamente. Il cliente può inserire un altro codice postale o il nome di una città. Ogni punto viene mostrato con nome e indirizzo. Vengono elencati fino a 50 punti. L'elenco viene richiesto in olandese quando la lingua del negozio è l'olandese, altrimenti in francese.
Il cliente deve scegliere un punto di ritiro. Senza un punto, Continue nel passaggio della modalità di consegna mostra Please select a bpost pickup point. Viene accettato solo un punto presente nell'elenco di bpost per la ricerca. Altrimenti il cliente vede The selected bpost pickup point is not in the list of your search. Please choose another one. La ricerca e la scelta vengono salvate per il checkout, quindi un aggiornamento della pagina non le perde. Una nuova ricerca cancella la scelta precedente.
Su OpenCart 4 il cliente clicca su Choose nel blocco del metodo di spedizione della pagina di checkout e sceglie bpost nella finestra Shipping method options. La ricerca e l'elenco dei punti di ritiro compaiono in quella finestra sotto l'opzione bpost. Continue nella finestra senza un punto di ritiro mostra Please select a bpost pickup point. Il resto funziona come su OpenCart 3.
Per elencare i punti di ritiro, l'estensione invia a bpost solo il codice postale o la città cercati, il paese e l'ID del corriere, firmati con le tue chiavi. Il token API viene richiesto e rinnovato automaticamente. Se bpost rifiuta un token, ne viene richiesto uno nuovo una volta e la ricerca viene ripetuta. I risultati di ricerca vengono memorizzati nella cache per un massimo di 6 ore, ma non oltre la durata della cache di OpenCart (1 ora di default). Se bpost non risponde, il cliente vede Pickup points cannot be loaded right now. Please try again in a few minutes or choose another shipping method. e l'estensione riprova dopo 5 minuti. Il timeout dell'API è di 15 secondi.
L'estensione usa solo prezzi fissi. Non ottiene tariffe in tempo reale da bpost, non crea spedizioni, non stampa etichette e non traccia i pacchi. I punti di ritiro vengono mostrati come elenco, non su una mappa. Crea le spedizioni nel tuo account bpost Shipping Platform o Shipping Manager; l'ID del punto di ritiro si trova nella pagina dell'ordine nel pannello di amministrazione.
Punti di ritiro
Quando l'ordine viene effettuato, il punto di ritiro scelto viene aggiunto al metodo di spedizione dell'ordine come bpost pickup point: con il nome e l'indirizzo del punto, per esempio "bpost parcel locker - bpost pickup point: …". Il cliente lo vede quindi nella conferma dell'ordine, nello storico ordini del suo account, nelle email degli ordini e nella fattura. Il punto completo, con il suo ID, viene inoltre salvato in una tabella separata dell'estensione. Su OpenCart 4 il checkout mantiene un unico ordine: se il cliente conferma di nuovo l'ordine, per esempio dopo aver scelto un altro punto di ritiro, il punto dell'ordine viene aggiornato.
Nel pannello di amministrazione, la pagina dell'ordine in Sales > Orders mostra il riquadro bpost pickup point con il punto e il suo ID, oppure No pickup point was selected for this order. Clicca su Change, cerca un codice postale o una città, scegli un altro punto dall'elenco e clicca su Save. L'ordine e il testo del suo metodo di spedizione vengono aggiornati subito e la pagina mostra Pickup point updated. Se il punto non è nell'elenco di bpost per la ricerca, la pagina mostra Pickup point not found in the bpost list of this search. La modifica viene scritta nel registro di debug quando Debug log è attivo. Change è disponibile solo quando le chiavi API sono compilate e l'utente amministratore può modificare gli ordini; non serve l'accesso alle impostazioni dell'estensione.
Per offrire insieme consegna in armadietto e consegna a domicilio, usa un altro metodo di spedizione per la consegna a domicilio. Il selettore dei punti di ritiro compare solo sotto l'opzione bpost.
Chiave di licenza
L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox bpost Cubee è il primo blocco di Extensions > Extensions > Shipping > VibeFox bpost Cubee > Edit, sopra le impostazioni. Incolla la chiave in License key e clicca su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (per esempio la data fino a cui 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 ci sono la riga Product: opencart-shipping-bpost-cubee 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 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 un posto dominio nel tuo account, clicca su Check now. Se il server delle licenze non risponde, l'estensione continua a funzionare con l'ultimo stato noto.
Una chiave funziona su un solo dominio: l'indirizzo del negozio dalla configurazione di OpenCart. Rimuovere la chiave dal negozio non libera il suo posto dominio. Liberalo nel tuo account vibefox.net.
Senza una chiave attiva, bpost non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Un utente amministratore che ha effettuato l'accesso all'amministrazione nello stesso browser vede comunque il metodo nel negozio, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e testare 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, 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 il rinnovo. Lo stato viene controllato di nuovo automaticamente quando apri la Dashboard dell'amministrazione o la pagina Edit: una volta al giorno nei 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
bpost non compare al checkout: controlla che la licenza sia attiva e che Enable/Disable sia attivo. Controlla la Geo Zone, oppure che Ignore geo zone sia attivo e che il paese sia in Countries. Controlla che il paese abbia un prezzo o una riga *=PREZZO, e controlla i limiti di peso e il Minimum order amount. Verifica che i prodotti abbiano Requires Shipping impostato su Yes. La pagina delle impostazioni mostra un avviso quando il Belgio non ha un prezzo.
Nessun selettore di punti di ritiro al checkout: controlla che Pickup points sia attivo e che Account ID (public key), Passphrase (private key) e App ID (X-APPID) siano tutti compilati. La pagina delle impostazioni mostra un avviso quando le chiavi sono incomplete.
I clienti vedono "Pickup points cannot be loaded right now": bpost non ha risposto o ha rifiutato le chiavi. Il motivo è mostrato in alto nella pagina delle impostazioni e nel registro di debug (campo Log nella pagina dell'estensione). L'estensione riprova automaticamente dopo 5 minuti. Salvare le impostazioni fa riprovare subito.
Nessun punto di ritiro trovato per questo codice postale o città: bpost non ha restituito punti per quella ricerca. Chiedi al cliente di provare un codice postale vicino o il nome di una città, e controlla il Carrier ID.
I prezzi con la virgola non vengono usati: sono accettati sia 5,50 sia 5.50. Le righe di Country prices che non seguono il formato CC=PREZZO vengono ignorate; l'avviso dopo il salvataggio le elenca.
I prezzi includono l'IVA? Con Tax Class impostato su --- None --- i prezzi sono definitivi. Con una classe fiscale, OpenCart aggiunge quell'imposta ai tuoi prezzi.
La pagina dice "Warning: You do not have permission to modify VibeFox bpost Cubee!": il tuo gruppo utenti amministratori può solo visualizzare le impostazioni. Dai al gruppo il permesso di modifica per extension/shipping/vfd_bpost_cubee (OpenCart 3) o extension/vfd_bpost_cubee/shipping/vfd_bpost_cubee (OpenCart 4) in System > Users > User Groups.
Per gli sviluppatori: l'indirizzo dell'API di bpost può essere sostituito con l'impostazione vfd_bpst_api_url (per i test); non ha un campo nella pagina delle impostazioni.
Disinstallazione
Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox bpost Cubee. 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. Il token API salvato e gli elenchi dei punti di ritiro in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, vengono eliminati anche impostazioni, registro e punti di ritiro dei checkout non completati. Se è disattivato, le altre impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. I punti di ritiro salvati negli ordini fanno parte dello storico ordini e non vengono mai eliminati. Gli ordini esistenti mantengono il proprio metodo di spedizione e il proprio 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 bpost Cubee nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso del cestino) per rimuovere il pacchetto caricato.
bpost è un marchio registrato del rispettivo proprietario. Questa estensione non è affiliata né approvata da bpost.