VibeFox bpost Cubee for WooCommerce — Guida
Requisiti
WordPress: 5.8 o successivo.
WooCommerce: 7.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.
PHP: 8.0 o successivo.
Account bpost Shipping Platform (solo per il selettore del punto di ritiro): il plugin 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. 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 metodo continua a funzionare come metodo di spedizione a prezzo fisso, ma al cliente non viene chiesto di scegliere un punto di ritiro.
Chiave di licenza VibeFox: acquistabile su vibefox.net. Una chiave funziona su un solo dominio.
Installazione
1. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e fai clic su Install Now. Puoi anche caricare la cartella vfd_bpost_cubee in /wp-content/plugins/ via FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox bpost Cubee, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugin.
4. Inserisci la chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.
5. Inserisci i tuoi prezzi e, per il selettore del punto di ritiro, le chiavi API di bpost (vedi Configurazione).
6. Aggiungi VibeFox bpost Cubee alla tua zona di spedizione per il Belgio in WooCommerce > Settings > Shipping > Shipping zones, oppure attiva Ignore shipping zones e scegli i paesi.
Configurazione
Tutte le impostazioni sono in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox bpost Cubee. Si applicano a tutte le zone di spedizione. Quando aggiungi il metodo a una zona, la finestra della zona ha un solo campo:
Title (zone): il nome di questa opzione al checkout per questa zona. Lascialo vuoto per usare il Name globale.
La pagina delle impostazioni mostra avvisi quando qualcosa nasconde in silenzio il metodo o il selettore: il selettore del punto di ritiro è attivo ma le chiavi API sono incomplete, non c'è un prezzo per il Belgio, oppure l'ultima connessione all'API di bpost non è riuscita. Ogni volta che salvi le impostazioni, vengono cancellati il token API memorizzato e gli elenchi dei punti di ritiro in cache.
Generali
Enable/Disable: attiva o disattiva la spedizione in armadietti bpost in tutte le zone contemporaneamente.
Name: il nome del metodo di spedizione mostrato al cliente al checkout. Predefinito: bpost parcel locker.
Tax status: Taxable aggiunge l'IVA di WooCommerce ai tuoi prezzi, None significa che i prezzi sono definitivi.
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.
Passphrase (private key): la chiave privata che firma ogni richiesta (HMAC-SHA256). Non viene mai inviata a bpost né scritta nel log.
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 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 solo quando tutte e tre le chiavi API sono compilate.
Search field width: la larghezza CSS del campo CAP / 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 del tuo negozio; bpost non restituisce i prezzi di spedizione tramite questa API)
Price by: come viene scelto il prezzo.
Country prices: una riga per paese nel formato CC=PRICE, per esempio BE=4.95. La riga *=PRICE imposta il prezzo per tutti gli altri paesi, per esempio *=9.95. Sono accettati sia il punto sia la virgola come separatore decimale. Le righe non valide vengono ignorate e riportate in un messaggio di errore al salvataggio. Ai paesi senza prezzo (quando non c'è la riga *) il metodo non viene offerto.
Size prices: usato quando Price by è impostato sulla dimensione del pacco, nel formato S=3.50, M=4.50, L=6.00, XL=8.00. La dimensione dipende dal peso del carrello: S fino a 2 kg, M fino a 5 kg, L fino a 10 kg, XL oltre 10 kg.
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.
Condizioni
Min weight (kg): il peso minimo del carrello perché il metodo compaia. 0 significa nessun limite.
Max weight (kg): il metodo viene nascosto oltre 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 (IVA esclusa) raggiunge questo importo. Lascia vuoto per mostrarlo sempre.
Excluded shipping classes: nasconde il metodo quando un articolo del carrello appartiene a una di queste classi di spedizione di WooCommerce.
I pesi dei prodotti vengono convertiti dall'unità di peso del negozio in chilogrammi.
Spedizione gratuita
Free shipping: attiva la consegna gratuita dall'importo indicato sotto.
Free shipping from: il subtotale del carrello (IVA esclusa) da cui la spedizione è gratuita. Usato solo quando Free shipping è attivo.
Disponibilità senza zone di spedizione
Ignore shipping zones: offri il metodo nei paesi indicati sotto senza aggiungerlo a una zona.
Countries: i paesi di destinazione per questa modalità. Predefinito: Belgio. Lascia vuoto per usare tutti i paesi in cui spedisci. Questo campo viene usato solo quando Ignore shipping zones è attivo.
Avanzate
Debug log: registra le richieste API e i calcoli dei prezzi in WooCommerce > Status > Logs, origine vfd-bpost-cubee. Gli errori API vengono sempre registrati, anche con questa opzione disattivata. Chiavi, token e dati dei clienti non vengono mai registrati.
Remove data on uninstall: se attiva, eliminando il plugin vengono rimosse le sue impostazioni e i suoi metodi nelle zone. Disattivare il plugin non cancella mai i dati. I punti di ritiro salvati negli ordini vengono sempre conservati.
Come funziona al checkout
Quando il cliente inserisce un indirizzo di consegna, WooCommerce chiede al plugin una tariffa. Il plugin verifica le condizioni: paese di consegna, peso del carrello, importo minimo dell'ordine e classi di spedizione escluse. Poi prende il prezzo dall'elenco dei paesi o in base alla dimensione del pacco, lo moltiplica per il numero di articoli nella modalità per articolo e lo azzera quando si applica la spedizione gratuita.
Quando il cliente sceglie la tariffa bpost, sotto compaiono un campo di ricerca, un pulsante Search e un elenco di punti di ritiro. Se il campo di ricerca è vuoto, viene cercato automaticamente il CAP dell'indirizzo di checkout. Il cliente può inserire un altro CAP o il nome di una città. Ogni punto viene mostrato con il nome e l'indirizzo. Vengono elencati fino a 50 punti. L'elenco dei punti di ritiro viene richiesto in olandese sui siti in olandese e in francese negli altri casi.
Il cliente deve scegliere un punto di ritiro. Senza scelta, il checkout classico mostra Please select a bpost pickup point., e il checkout a blocchi non consente di effettuare l'ordine con lo stesso messaggio. La scelta viene mantenuta durante la sessione di checkout, quindi un aggiornamento della pagina non la fa perdere.
Per elencare i punti di ritiro, il plugin invia a bpost solo il CAP o la città cercati, il paese e l'ID del corriere, firmati con le tue chiavi. Nessun nome, indirizzo e-mail o riga di indirizzo del cliente viene inviato. 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 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 plugin riprova dopo 5 minuti. Il timeout dell'API è di 15 secondi.
Il metodo funziona nel checkout classico e nei blocchi Carrello e Checkout. È compatibile con WooCommerce High-Performance Order Storage (HPOS).
Il plugin 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 è nell'ordine.
Punti di ritiro
Il punto di ritiro scelto (nome e indirizzo) e il suo ID vengono salvati nell'ordine. Nella schermata di gestione dell'ordine viene mostrato sotto l'indirizzo di spedizione come bpost pickup point. Fai clic su Change, cerca un CAP o una città e scegli un altro punto dall'elenco. L'ordine viene aggiornato subito e viene aggiunta una nota d'ordine bpost pickup point changed to: …. Il link Change è disponibile solo quando le chiavi API sono compilate.
I clienti vedono il punto di ritiro nella pagina di ringraziamento e in My account > Orders. Viene inoltre aggiunto alle e-mail dell'ordine, sia in HTML sia in testo semplice.
Per offrire insieme consegna in armadietto e a domicilio, aggiungi un altro metodo di spedizione, per esempio Flat rate, alla stessa zona. Il selettore del punto di ritiro compare solo sotto la tariffa bpost.
Chiave di licenza
Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Shipping > VibeFox bpost Cubee. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, per esempio la data fino alla quale la licenza è attiva, e il tuo dominio. Usa Check now per controllare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuoverla da questo sito. Il link Manage licenses and domains in your account apre il tuo account vibefox.net.
Una chiave funziona su un solo dominio. Rimuovere la chiave da un sito non libera lo slot del dominio. Liberalo nel tuo account vibefox.net.
Senza una chiave attiva, il metodo bpost non viene mostrato ai clienti al checkout. I gestori del negozio con accesso vedono ancora il metodo, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugin e nelle pagine di WooCommerce. Gli ordini esistenti non vengono modificati.
Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene verificato di nuovo automaticamente in background.
Risoluzione dei problemi
bpost non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che il metodo sia aggiunto alla zona del paese del cliente (oppure che Ignore shipping zones sia attivo e il paese sia consentito). Controlla che il paese abbia un prezzo o una riga *=PRICE, e verifica i limiti di peso, Minimum order amount e Excluded shipping classes. 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 è in WooCommerce > Status > Logs (origine vfd-bpost-cubee) e nella pagina delle impostazioni. Il plugin riprova automaticamente dopo 5 minuti. Salvare le impostazioni riprova 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 il formato CC=PRICE vengono ignorate; il messaggio di errore dopo il salvataggio le elenca.
I prezzi includono l'IVA? Con Tax status impostato su Taxable, WooCommerce aggiunge l'IVA ai tuoi prezzi. Con None i prezzi sono definitivi.
Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera uno slot nel tuo account vibefox.net e fai clic su Check now. Se l'indirizzo del sito è cambiato, fai clic su Check now per attivare la chiave per il nuovo dominio. Se il server delle licenze non è raggiungibile, il plugin continua a funzionare con l'ultimo stato noto.
Disinstallazione
Disattivare il plugin mantiene tutte le impostazioni; cancella solo il token API e gli elenchi dei punti di ritiro in cache. Per rimuoverlo, disattivalo ed eliminalo dalla pagina Plugins. La chiave di licenza e lo stato di licenza di questo plugin, il token API e le cache vengono sempre rimossi. Impostazioni e metodi di zona vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano per una futura reinstallazione. I punti di ritiro salvati negli ordini fanno parte dello storico degli ordini e non vengono mai eliminati.
bpost è un marchio del rispettivo titolare. Questo plugin non è affiliato a bpost né approvato da bpost.