VibeFox Bob Go 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 Bob Go (solo per le tariffe in tempo reale): Bob Go non usa chiavi API. Ti servono un account Bob Go (bobgo.co.za), il tuo negozio installato come canale di vendita WooCommerce nel tuo account Bob Go (Sales channels) e "Rates at checkout" attivo per quel canale. Servizi, prezzi e regole si configurano su Bob Go. Se usi solo prezzi fissi, non ti serve un account Bob Go.
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. Decomprimilo sul tuo computer. Contiene README.txt, il pacchetto per OpenCart 3 vfd_bob_go-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_bob_go.ocmod.zip. Installa solo il pacchetto della 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_bob_go-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 Bob Go 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, e clicca su Activate (vedi Chiave di licenza).
5. Nel tuo account Bob Go, installa il tuo negozio come canale di vendita. Attiva "Rates at checkout" per quel canale e configura i tuoi servizi e i tuoi prezzi.
6. Nella pagina Edit controlla il dominio del negozio, l'indirizzo di partenza (da dove spedisci) e, se la valuta del tuo negozio non è ZAR, il tasso di conversione in ZAR (vedi Configurazione). Attiva Enable Bob Go e clicca su Save.
OpenCart 4
1. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_bob_go.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 Bob Go, clicca su Install (il pulsante verde +), poi su Edit (il pulsante con la matita).
4. Configura Bob Go, inserisci la chiave di licenza e le impostazioni come ai passaggi da 4 a 6 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 Bob Go e salvi. Di default usa le tariffe Bob Go in tempo reale. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni Bob Go che hai conservato.
Configurazione
Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox Bob Go > Edit. Le sezioni sono elencate a sinistra. Un solo pulsante Save salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella anche le tariffe Bob Go in cache. I numeri accettano un punto o una virgola come separatore decimale. Se un valore è errato, non viene salvato nulla e la pagina mostra il motivo: un Method title vuoto o più lungo di 64 caratteri, un valore che non è un numero ("…" must be a number.), un importo o un peso negativo ("…" must be a number of 0 or more.), un ZAR conversion rate pari a 0 o inferiore, un Minimum weight (kg) superiore al Maximum weight (kg), oppure una classe fiscale o una zona geografica sconosciuta. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.
Sopra le impostazioni la pagina avvisa quando le tariffe in tempo reale non possono funzionare: Live rates are not requested: your store currency is … — set the "ZAR conversion rate"., quando il Sudafrica non ha zone (province) nel tuo negozio, oppure quando il negozio non ha una classe di peso con l'unità "kg" o una classe di lunghezza con l'unità "cm". In quest'ultimo caso pesi e dimensioni vengono convertiti in base al nome dell'unità della loro classe (kg, g, lb, oz; cm, mm, m, in), mentre le altre unità vengono lette come kg o cm.
Generale
Le impostazioni si applicano a ogni zona geografica. Al checkout ogni servizio Bob Go è un'opzione di consegna separata sotto il titolo del metodo.
Enable Bob Go: mostra o nasconde Bob Go al checkout. Predefinito: disattivato.
Method title: il nome del metodo di spedizione mostrato al cliente. I servizi Bob Go, per esempio "The Courier Guy - Economy", sono elencati sotto con i nomi di Bob Go. Predefinito: Bob Go. Obbligatorio, massimo 64 caratteri.
Shipping cost: come viene calcolato il prezzo.
Il motivo dell'assenza di tariffe in tempo reale viene scritto nel registro. Non viene mai mostrato al cliente.
Sort order: la posizione di Bob Go tra i metodi di spedizione al checkout. Un numero intero.
Account Bob Go
Questa sezione spiega cosa ti serve su Bob Go, con collegamenti al tuo account Bob Go, a Sales channels e a Rates at checkout. Mostra anche l'ultima risposta di Bob Go per il dominio del tuo negozio: connected, the WooCommerce channel is not installed on Bob Go (HTTP 404), "Rates at checkout" is not enabled for this channel (HTTP 401 o 403), oppure request failed con il codice di errore o no connection.
Store domain: Bob Go identifica il tuo negozio tramite il dominio. Lascialo vuoto per usare il dominio del tuo negozio, che viene mostrato nella descrizione del campo. Inserisci un altro dominio solo se il tuo canale su Bob Go è installato con un indirizzo diverso, per esempio example.co.za/shop per un negozio in una sottocartella. Lo schema e la barra finale vengono rimossi.
ZAR conversion rate: Bob Go quota in rand sudafricani (ZAR). Se la valuta predefinita del tuo negozio non è ZAR, inserisci quanto vale 1 ZAR nella tua valuta, per esempio 0.05. Le tariffe vengono convertite con questo valore e i prezzi dei prodotti vengono inviati a Bob Go in ZAR. Lascialo vuoto per non usare le tariffe Bob Go in tempo reale nella tua valuta (i prezzi fissi continuano a funzionare). Il tasso deve essere maggiore di 0. Se la valuta del tuo negozio è ZAR, lascialo vuoto.
Delivery dates: mostra l'intervallo di date di consegna stimate da Bob Go accanto a ogni servizio al checkout. La stima viene sempre salvata con l'ordine e resta visibile nella pagina dell'ordine.
Spedizione da (indirizzo di partenza)
L'indirizzo di partenza viene inviato a Bob Go con ogni richiesta di tariffe. L'indirizzo del negozio in OpenCart è testo libero, quindi vengono usati solo il paese e la regione del tuo negozio (System > Settings > Store > Local): se il paese del negozio è il paese di partenza, una provincia vuota viene ripresa dalla regione del negozio. Inserisci qui la città, il codice postale e la via.
Origin country: il paese da cui spedisci. Predefinito: South Africa. Bob Go spedisce solo all'interno del Sudafrica.
Origin province: una provincia sudafricana, oppure Store region (if in South Africa).
Origin city / suburb: la città o il quartiere da cui spedisci, per esempio Johannesburg.
Origin postal code: il codice postale da cui spedisci, per esempio 2001.
Origin street address: l'indirizzo della via da cui spedisci, per esempio 123 Main Street.
Prezzi fissi (usati quando Shipping cost è Fixed prices (below), e come alternativa quando Bob Go non restituisce tariffe)
Price per country: una riga per paese: un codice paese di 2 lettere, un segno di uguale e il prezzo nella valuta predefinita del tuo negozio, IVA esclusa, per esempio ZA=99.99. Usa * per tutti gli altri paesi, per esempio *=199.99 nella riga successiva. Le righe in un altro formato vengono rimosse al salvataggio, e la pagina le elenca in un avviso.
Flat price: il prezzo per i paesi senza una riga sopra. Lascialo vuoto per nascondere il metodo per quei paesi.
Fixed price applies: Per order (predefinito) addebita il prezzo una sola volta. Per item (price × quantity) lo moltiplica per il numero di articoli nel carrello. Le tariffe Bob Go in tempo reale riguardano sempre la spedizione completa.
Condizioni
Minimum weight (kg): nasconde il metodo sotto questo peso del carrello. 0 significa nessun limite (predefinito).
Maximum weight (kg): nasconde il metodo sopra questo peso del carrello. 0 significa nessun limite (predefinito).
Minimum order amount: mostra il metodo solo quando il subtotale dei prodotti da spedire (dopo il coupon, IVA esclusa) raggiunge questo importo. Lascialo vuoto per mostrarlo sempre.
Free shipping: attiva la spedizione gratuita quando viene raggiunto l'importo dell'ordine indicato sotto.
Free shipping from: il subtotale dei prodotti da spedire (dopo il coupon, IVA esclusa) a partire dal quale la spedizione è gratuita. Viene usato solo quando Free shipping è attivo. In quel caso Bob Go non viene interrogato per le tariffe.
Tax class: la classe fiscale del costo di spedizione, oppure No tax (predefinito). Le tariffe Bob Go di solito includono già l'IVA. In questo caso lascia No tax, così l'imposta sulla spedizione non viene applicata due volte.
Geo zone: offri Bob Go solo per gli indirizzi in questa zona geografica. All zones (predefinito) significa nessun limite. Non viene usato quando Ignore shipping zones è attivo. Le zone geografiche si gestiscono in System > Localisation > Geo Zones.
Disponibilità senza zone di spedizione
Ignore shipping zones: quando è attivo, la zona geografica non viene controllata e il metodo viene offerto per i paesi sotto.
Countries: i paesi di destinazione per quella modalità. Lascialo vuoto per consentire tutti i paesi. Viene usato solo quando Ignore shipping zones è attivo.
Avanzate
Debug log: scrive i calcoli delle tariffe e le richieste a Bob Go in storage/logs/vfd_bobg_debug.log.php. Il file non può essere letto dal web. Gli indirizzi dei clienti non vengono registrati. Gli errori di Bob Go vengono registrati anche quando questa opzione è disattivata. Disattiva il registro quando hai finito. Quando il file raggiunge 5 MB, viene spostato in vfd_bobg_debug.old.log.php e ne viene avviato uno nuovo.
Log: mostra la dimensione e le ultime voci del registro. Clicca su Clear log per svuotarlo.
Remove data on uninstall: quando è attivo, disinstallando l'estensione vengono cancellate le impostazioni Bob Go, le tariffe in cache e i registri. Il servizio Bob Go salvato con gli ordini viene conservato. Quando è disattivato (predefinito), tutto viene conservato per una nuova installazione.
Importazione / Esportazione
Export: clicca su Download JSON per salvare le impostazioni in un file JSON.
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.
Come funziona al checkout
Quando OpenCart mostra i metodi di spedizione, chiede all'estensione le tariffe Bob Go. Se è impostata una Geo zone (e Ignore shipping zones è disattivato) e l'indirizzo si trova al di fuori, Bob Go 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 controlla poi il paese di destinazione (con Ignore shipping zones), il peso del carrello e il Minimum order amount. L'importo dell'ordine è il prezzo dei prodotti da spedire, dopo lo sconto del coupon e prima dell'IVA. Buoni regalo, punti fedeltà e credito del negozio non vengono considerati. Se si applica la spedizione gratuita, il cliente vede Bob Go (free) (il tuo Method title) e non viene inviata alcuna richiesta a Bob Go.
Nelle modalità in tempo reale l'estensione invia a Bob Go il dominio del tuo negozio, gli indirizzi di partenza e di consegna (con la provincia) e gli articoli del carrello: prezzi dei prodotti in ZAR, pesi e dimensioni, e il modello del prodotto come SKU. Per gli indirizzi sudafricani la zona di OpenCart viene inviata come codice di provincia (EC, FS, GP, KZN, LP, MP, NC, NW, WC). Le tariffe in tempo reale vengono richieste solo dopo che il cliente ha inserito una città o un codice postale. Le tariffe in ZAR vengono convertite con il ZAR conversion rate quando la valuta del tuo negozio non è ZAR. Il prezzo viene calcolato nella valuta predefinita, arrotondato alle sue cifre decimali e mostrato al cliente nella sua valuta, con l'IVA della Tax class selezionata.
Sotto il titolo del metodo il cliente vede un'opzione per ogni servizio Bob Go, con il suo nome, il prezzo e, se Delivery dates è attivo, le date di consegna stimate tra parentesi. Il cliente sceglie un servizio come qualsiasi altra opzione di spedizione di OpenCart. Con un prezzo fisso c'è un'unica opzione con il titolo del metodo.
In OpenCart 4 il cliente clicca su Choose nel blocco del metodo di spedizione della pagina di checkout e sceglie un servizio Bob Go nella finestra Shipping method options, per esempio SkyNet - Overnight (by 17/10/2026) con il suo prezzo. Il metodo funziona come in OpenCart 3.
Le tariffe vengono memorizzate nella cache per 1 ora per ogni richiesta completa, così lo stesso carrello non genera una nuova richiesta. Una richiesta non riuscita viene memorizzata per 5 minuti, e il timeout è di 12 secondi, così un'interruzione di Bob Go non rallenta ogni aggiornamento del checkout. Una richiesta non riuscita non interrompe mai il checkout: il metodo viene nascosto oppure, in modalità di riserva, si usa il prezzo fisso. Il motivo viene scritto nel registro.
L'estensione mostra solo tariffe. Non crea spedizioni, lettere di vettura o etichette, non traccia i pacchi, non sincronizza gli ordini con Bob Go e non invia notifiche. Per l'evasione usa il pannello di Bob Go. Non c'è una scelta di punti di ritiro o armadietti. Bob Go spedisce solo all'interno del Sudafrica.
Ordini
Il nome del servizio scelto diventa il metodo di spedizione dell'ordine, quindi compare nelle email degli ordini, in Sales > Orders e nell'account del cliente. Quando l'ordine viene effettuato, anche il servizio Bob Go, il suo codice e la stima di consegna vengono salvati con l'ordine. Le modifiche successive al carrello o ai prezzi Bob Go non li cambiano. In OpenCart 4 il checkout mantiene un solo ordine: se il cliente torna indietro e conferma di nuovo l'ordine con un altro servizio Bob Go, il servizio salvato viene aggiornato, mentre con un altro metodo di spedizione o un prezzo fisso viene rimosso.
Nel pannello di amministrazione, la pagina dell'ordine in Sales > Orders mostra un blocco Bob Go con Bob Go service (nome e codice) e Estimated delivery. Il cliente vede Bob Go service e Estimated delivery nella pagina dei dettagli dell'ordine nel suo account. Gli ordini con prezzo fisso o spedizione gratuita non hanno un servizio Bob Go.
Chiave di licenza
L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox Bob Go è il primo blocco di Extensions > Extensions > Shipping > VibeFox Bob Go > Edit, 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 ci sono la riga Product: opencart-shipping-bob-go e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo gli utenti amministratori con il permesso di modifica 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 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 solo dominio: l'indirizzo del negozio nella configurazione di OpenCart. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Liberalo nel tuo account vibefox.net.
Senza una chiave attiva, Bob Go 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. In 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 ricontrollato automaticamente quando apri la Dashboard o la pagina Edit dell'amministrazione: una volta al giorno nei primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve alcun cron job. La disinstallazione dell'estensione rimuove sempre la chiave di licenza e lo stato della licenza.
Risoluzione dei problemi
Bob Go non compare al checkout: controlla che la licenza sia attiva e che Enable Bob Go sia attivo. Controlla la Geo zone, oppure attiva Ignore shipping zones e controlla Countries. Controlla i limiti di peso e il Minimum order amount. In modalità a prezzo fisso, verifica che il paese, * o il Flat price abbiano un prezzo. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.
Non vengono mostrate tariffe Bob Go: apri la pagina dell'estensione. La sezione Account Bob Go mostra l'ultima risposta di Bob Go. "The WooCommerce channel is not installed on Bob Go" (HTTP 404) significa che il dominio del negozio non è un canale di vendita su Bob Go: controlla lo Store domain. "Rates at checkout is not enabled" (HTTP 401) significa che la funzione è disattivata per il canale. Assicurati anche che il cliente abbia inserito una città o un codice postale e, per i negozi non in ZAR, che il ZAR conversion rate sia impostato. Attiva il Debug log, ricarica il checkout e controlla il campo Log. Con Bob Go live rates, fixed prices if Bob Go returns no rates i clienti ricevono comunque il prezzo fisso mentre risolvi il problema.
Il mio negozio non usa rand: Bob Go quota in ZAR. Inserisci quanto vale 1 ZAR nella valuta del tuo negozio. Senza questo valore l'estensione non chiede tariffe a Bob Go. I prezzi fissi continuano a funzionare.
La pagina avvisa che il Sudafrica non ha zone: aggiungi le province del Sudafrica in System > Localisation > Zones, altrimenti Bob Go non riceve alcuna provincia per gli indirizzi sudafricani.
L'imposta viene applicata due volte sulla spedizione: le tariffe Bob Go di solito includono l'IVA. Imposta Tax class su No tax.
Le tariffe sembrano obsolete dopo una modifica: clicca su Save nella pagina dell'estensione. Questo cancella le tariffe Bob Go in cache. Le modifiche nel tuo account Bob Go vengono recepite dopo la cache di 1 ora o quando salvi le impostazioni.
La pagina dice "Warning: You do not have permission to modify VibeFox Bob Go!": il tuo gruppo utenti amministratori può solo visualizzare le impostazioni. Dai al gruppo il permesso di modifica per extension/shipping/vfd_bob_go (OpenCart 3) o extension/vfd_bob_go/shipping/vfd_bob_go (OpenCart 4) in System > Users > User Groups.
Per gli sviluppatori: l'indirizzo dell'API di Bob Go può essere sostituito con l'impostazione vfd_bobg_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 Bob Go. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable Bob Go, Sort order, Tax class e Geo zone. Le tariffe in cache vengono sempre rimosse. Se Remove data on uninstall è attivo, vengono eliminate anche le impostazioni Bob Go e il registro. Se è disattivato, le altre impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. Il servizio Bob Go salvato con gli ordini viene sempre conservato, e gli ordini esistenti mantengono il proprio metodo di spedizione e il proprio costo.
In 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 Bob Go nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per rimuovere il pacchetto caricato.
Bob Go è un marchio registrato del rispettivo proprietario. Questa estensione non è affiliata a Bob Go né approvata da Bob Go.