VibeFox bpost Cubee for PrestaShop — Guida
Requisiti
PrestaShop: da 8.0 a 9.x.
PHP: 8.0 o successivo. Il modulo non si installa su versioni precedenti di PHP.
Account bpost Shipping Platform (solo per il selettore del punto di ritiro): il modulo 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 è rilasciato da bpost per la tua integrazione; chiedilo 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 corriere funziona comunque con prezzi fissi, ma ai clienti non viene chiesto di scegliere un punto di ritiro.
Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un dominio.
Installazione
1. Nel back office vai su Modules > Module Manager e fai clic su Upload a module. Scegli il file ZIP del modulo.
2. Al termine del caricamento, fai clic su Configure, oppure trova VibeFox bpost Cubee più tardi nell'elenco dei moduli e fai clic su Configure.
3. Inserisci la tua chiave di licenza VibeFox in License key, nel blocco licenza in cima alla pagina Configure, e fai clic su Activate (vedi Chiave di licenza).
4. Inserisci i tuoi prezzi e, per il selettore del punto di ritiro, le chiavi API di bpost (vedi Configurazione). Fai clic su Save.
All'installazione il modulo crea il corriere bpost parcel locker con il testo dei tempi di consegna Pickup point or parcel locker. Il corriere è collegato alla zona del Belgio e a tutti i gruppi di clienti, senza regola fiscale. Puoi modificare zone, gruppi di clienti, testo dei tempi di consegna e logo 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 bpost Cubee > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella anche il token API memorizzato e gli elenchi dei punti di ritiro in cache.
La pagina mostra avvisi quando qualcosa nasconde in silenzio il corriere o il selettore: il selettore del punto di ritiro è attivo ma le chiavi API sono incomplete, non c'è un prezzo per il Belgio (BE) né un prezzo predefinito, l'ultima connessione all'API di bpost non è riuscita, l'unità di peso del negozio non è riconosciuta dal modulo (impostala in International > Localization, Local units), oppure il corriere bpost non è stato trovato. Al salvataggio, le righe di Country prices che non è stato possibile leggere sono elencate in un avviso, così come un valore di Size prices in cui non è stata riconosciuta alcuna dimensione. Un peso o un importo che non è un numero o è negativo non viene salvato: un avviso indica il campo e resta il valore precedente. Se Min weight (kg) è maggiore di Max weight (kg), anche i pesi non vengono salvati.
Generale
Enable/Disable: attiva o disattiva la spedizione con bpost parcel locker. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.
Name: il nome del metodo di spedizione mostrato al cliente al checkout (il nome del corriere). Predefinito: bpost parcel locker. Se lo lasci vuoto, viene usato il predefinito. Massimo 64 caratteri; un nome più lungo viene rifiutato e non si salva nulla.
Tax status: None significa che i prezzi sono definitivi. Taxable con una regola fiscale aggiunge l'imposta di quella regola ai tuoi prezzi. La scelta viene salvata nel corriere.
API bpost (ricerca dei punti di ritiro) (necessaria solo per il selettore del punto 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 log. Dopo il salvataggio il campo resta vuoto e mostra Saved - leave empty to keep it. Inserisci un nuovo valore 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 i cui punti di ritiro e armadietti vengono elencati. Predefinito: 68 (bpost). Gli altri corrieri attivi nel tuo contratto hanno i propri ID.
Selettore del punto di ritiro
Pickup points: mostra il selettore di punti di ritiro e armadietti al checkout. Attivo per impostazione predefinita. Il selettore compare, e un punto di ritiro è obbligatorio, solo quando tutte e tre le chiavi API sono compilate.
Search field width: la larghezza CSS del campo CAP / città, ad esempio 100% o 300px. Predefinito: 100%.
Pickup point list width: la larghezza CSS dell'elenco dei punti di ritiro, ad esempio 100% o 400px. Predefinito: 100%.
Prezzi (nella valuta predefinita del tuo negozio, IVA esclusa; bpost non restituisce tariffe di spedizione tramite questa API)
Price by: come viene scelto il prezzo.
Country prices: una riga per paese nella forma CC=PREZZO, ad esempio BE=4.95. La riga *=PREZZO imposta il prezzo per tutti gli altri paesi, ad esempio *=9.95. Sono accettati sia il punto sia la virgola come separatore decimale. Le righe non valide vengono ignorate. Nei paesi senza prezzo (se non c'è una riga *) il corriere non viene offerto.
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 addebita il prezzo una sola volta. Per item (price x number of items) lo moltiplica per il numero di articoli nel carrello.
I prezzi vengono arrotondati ai decimali della valuta predefinita e poi mostrati nella valuta del carrello del cliente.
Condizioni
Min weight (kg): il peso minimo del carrello perché il corriere compaia. I pesi dei prodotti vengono convertiti dall'unità di peso del tuo negozio. 0 significa nessun limite.
Max weight (kg): il corriere è 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 corriere solo quando il subtotale del carrello raggiunge questo importo. Il subtotale conta i prodotti che richiedono spedizione, dopo gli sconti, IVA esclusa. Lascia vuoto il campo per mostrare sempre il corriere.
Spedizione gratuita
Free shipping: attiva la consegna gratuita a partire dall'importo indicato qui sotto.
Free shipping from: il subtotale del carrello (prodotti che richiedono spedizione, dopo gli sconti, IVA esclusa) da cui la spedizione è gratuita. Usato solo quando Free shipping è attivo. Il paese deve comunque avere un prezzo, altrimenti il corriere non viene offerto.
Disponibilità senza zone di spedizione
Normalmente il corriere viene offerto nelle sue zone di spedizione in Shipping > Carriers. All'installazione è la zona del Belgio.
Ignore shipping zones: offre il corriere nei paesi indicati qui sotto senza aggiungerlo a una zona. Il corriere viene allora collegato a tutte le zone attive, anche a quelle che creerai in seguito. Quando disattivi di nuovo l'opzione, il corriere riprende le sue zone precedenti.
Countries: i paesi di destinazione per quella modalità. Predefinito: Belgio. Lascia vuoto per usare tutti i paesi verso cui spedisci. Questo campo viene usato solo quando Ignore shipping zones è attivo.
Avanzate
Debug log: registra richieste API e calcoli dei prezzi in logs/vfd_bpst_debug.log.php nella cartella del modulo. Il file non si può aprire dal web. Gli errori dell'API vengono sempre registrati, anche quando questa opzione è disattivata. Chiavi e token non vengono mai registrati.
Log: mostra la dimensione e le ultime voci del log di debug. Fai clic su Clear log per svuotarlo.
Remove data on uninstall: se attivo, disinstallando il modulo vengono eliminate le sue impostazioni e il corriere. I punti di ritiro salvati negli ordini vengono sempre conservati.
Come funziona al checkout
Nel passaggio di spedizione PrestaShop chiede al modulo il prezzo bpost. Contano solo i prodotti che richiedono spedizione: i prodotti virtuali non aggiungono peso e non sono inclusi nell'importo dell'ordine. Il modulo verifica le condizioni: i paesi di Ignore shipping zones (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 il corriere bpost il cliente vede un campo Postal code or city, un pulsante Search e un elenco di punti di ritiro. Quando il cliente sceglie il corriere e non ha ancora cercato, il CAP dell'indirizzo di consegna viene cercato automaticamente. Il cliente può inserire un altro CAP o il nome di una città. Ogni punto è mostrato con il suo 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, Continue nel passaggio di consegna mostra Please select a bpost pickup point. e il pulsante Place order viene bloccato nella pagina con lo stesso messaggio. Viene accettato solo un punto dall'elenco 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 con il carrello, quindi un aggiornamento della pagina non le fa perdere. Una nuova ricerca cancella la scelta precedente.
Per elencare i punti di ritiro, il modulo invia a bpost solo il CAP 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 sono memorizzati nella cache per 6 ore. 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 il modulo riprova dopo 5 minuti. Il timeout dell'API è di 15 secondi.
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 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 sono 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 nell'ordine.
Punti di ritiro
Quando l'ordine viene effettuato, il punto di ritiro scelto (nome e indirizzo) e il suo ID vengono salvati con l'ordine. Nella pagina dell'ordine nel back office, il blocco bpost pickup point mostra il punto e il suo ID, oppure No pickup point was selected for this order. Fai clic su Change, cerca un CAP o una città, scegli un altro punto dall'elenco e fai clic su Save. L'ordine viene aggiornato subito e la pagina mostra Pickup point updated. La modifica viene scritta nel log di debug quando Debug log è attivo. Il link Change è disponibile solo quando le chiavi API sono compilate. Salvare un nuovo punto richiede il permesso di modificare gli ordini; altrimenti la pagina mostra Permission denied. Non serve l'accesso alle pagine dei Moduli.
Se PrestaShop divide un carrello in più ordini, il punto di ritiro resta con il primo ordine. Gli altri ordini non hanno un punto di ritiro e il log di debug mostra un errore con il nome del primo ordine; imposta a mano il punto per quei pacchi in bpost.
I clienti vedono il punto di ritiro come bpost pickup point: nella pagina di conferma dell'ordine e nei dettagli dell'ordine del loro account. Viene aggiunto anche al nome del corriere nell'e-mail di conferma dell'ordine. L'e-mail di nuovo ordine al negozio (se usi il modulo di avvisi e-mail) contiene anche l'ID del punto.
Per offrire insieme armadietto e consegna a domicilio, usa un altro corriere per la consegna a domicilio nella stessa zona. Il selettore del punto di ritiro compare solo con il corriere bpost.
Chiave di licenza
Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox bpost Cubee è il primo blocco di Modules > Module Manager > VibeFox bpost Cubee > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic 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: presta-shipping-bpost-cubee 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 con una data. Dopo che l'indirizzo del negozio cambia, o dopo aver liberato uno slot di dominio nel tuo account, fai clic 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: quello 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 bpost non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Il frontend 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 testarlo al checkout. Un promemoria appare 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 controllato di nuovo automaticamente mentre lavori nel back office: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta a settimana. Non serve alcun cron job. Disinstallare o reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.
Risoluzione dei problemi
bpost non compare al 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 che Ignore shipping zones sia attivo e il paese sia in Countries. Controlla che il paese abbia un prezzo o che esista una riga *=PREZZO, e verifica i limiti di peso e il Minimum order amount. I prodotti possono anche essere limitati a determinati corrieri nella pagina del prodotto. La pagina delle impostazioni mostra un avviso quando il Belgio non ha un prezzo.
Nessun selettore del punto di ritiro al checkout: verifica 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 nella pagina delle impostazioni e nel log di debug (campo Log nella pagina del modulo). Il modulo riprova automaticamente dopo 5 minuti. Salvare le impostazioni fa riprovare subito.
Nessun punto di ritiro trovato per questo CAP o città: bpost non ha restituito punti per quella ricerca. Chiedi al cliente di provare un CAP 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 la forma CC=PREZZO vengono ignorate; l'avviso dopo il salvataggio le elenca.
I prezzi sono IVA inclusa? Con Tax status impostato su None i prezzi sono definitivi. Con una regola fiscale Taxable, PrestaShop aggiunge quell'imposta ai tuoi prezzi.
La pagina dice che il corriere bpost non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Reimposta il modulo in Modules > Module Manager per ricrearlo.
Per gli sviluppatori, gli hook actionVfdBpstApiUrl e actionVfdBpstApiLanguage modificano l'indirizzo dell'API di bpost e la lingua dell'elenco dei punti di ritiro.
Disinstallazione
Vai su Modules > Module Manager, apri il menu accanto a VibeFox bpost Cubee e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. Il token API memorizzato e gli elenchi dei punti di ritiro in cache vengono sempre rimossi. 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 di ritiro dei carrelli non completati. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni restano. Installare di nuovo il modulo ridà al corriere lo stato che aveva prima della disinstallazione. Reset in Modules > Module Manager funziona allo stesso modo, quindi un corriere disattivato resta disattivato. I punti di ritiro salvati negli ordini fanno parte della cronologia degli ordini e non vengono mai eliminati.
bpost è un marchio del rispettivo titolare. Questo modulo non è affiliato a bpost né approvato da bpost.