VibeFox Balikobot 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 Balikobot (per tariffe in tempo reale e punti di ritiro): ti serve un account Balikobot con accesso API. L'utente API e la chiave API si trovano nell'area clienti di Balikobot (client.balikobot.cz). Il supporto Balikobot (podpora@balikobot.cz) attiva l'API per il tuo account e per i tuoi corrieri. Le tariffe in tempo reale richiedono un corriere e un servizio per cui Balikobot supporta "transportcosts". I punti di ritiro richiedono un corriere con supporto "branchlocator" (per esempio Česká pošta, Zásilkovna, PPL, DPD, GLS). In caso di dubbi, chiedi al supporto Balikobot. I prezzi fissi funzionano senza account.

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_balikobot-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_balikobot.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_balikobot-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non serve aggiornare Extensions > Modifications. Invece dell'Installer, puoi copiare il contenuto della cartella upload di questo pacchetto nella cartella radice del tuo negozio.

2. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox Balikobot e clicca su Install (il pulsante verde +).

3. Clicca su Edit (il pulsante a forma di matita) per aprire la pagina delle impostazioni.

4. Inserisci la tua chiave di licenza VibeFox in License key nel blocco della licenza in cima alla pagina Edit e clicca su Activate (vedi Chiave di licenza).

5. Inserisci l'utente e la chiave API, scegli il corriere e il tipo di servizio, la fonte del prezzo e i prezzi per paese (vedi Configurazione). Per i servizi con ritiro, attiva Pickup point selection. Attiva Enable/Disable e clicca su Save.

OpenCart 4

1. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_balikobot.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 Balikobot, clicca su Install (il pulsante verde +), poi su Edit (il pulsante a forma di 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 gli stessi in entrambe le versioni.

All'installazione l'estensione crea una tabella per i punti di ritiro di checkout e ordini. Il metodo resta disattivato finché non attivi Enable/Disable e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni Balikobot che hai conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox Balikobot > Edit. Le sezioni sono elencate a sinistra. Un unico pulsante Save salva l'intera pagina senza ricaricarla. Dopo il salvataggio vedi Settings saved. Cached rates and pickup points were cleared. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.

Alcuni errori bloccano il salvataggio, e in tal caso non viene salvato nulla: un Name vuoto o troppo lungo, un Sort Order che non è un numero intero, oppure una classe fiscale o una zona geografica sconosciuta. Gli altri problemi vengono mostrati come avvisi, e il resto delle impostazioni viene salvato: un valore che non è un numero (o è negativo) non viene salvato e l'avviso indica il campo; le righe non valide di Country prices vengono rimosse ed elencate.

Gli avvisi sulle impostazioni che nasconderebbero il metodo, le tariffe in tempo reale o i punti di ritiro compaiono in cima alla pagina: tariffe in tempo reale o punti di ritiro senza utente o chiave API, una valuta del negozio diversa da CZK senza Exchange rate, Country prices vuoto con prezzi fissi o con la modalità di riserva, e un negozio senza classe di peso con unità kg (i pesi dei prodotti vengono quindi letti dal nome della loro unità: kg, g, lb o oz).

Generale

Enable/Disable: attiva o disattiva la spedizione Balikobot al checkout. Predefinito: disattivato.

Name: il nome del metodo di spedizione mostrato ai clienti. Predefinito: Balikobot. Obbligatorio, massimo 64 caratteri.

Sort Order: la posizione del metodo nell'elenco dei metodi di spedizione. Un numero intero.

Account API Balikobot (necessario per tariffe in tempo reale e punti di ritiro)

API user: il tuo utente API Balikobot dall'area clienti.

API key: la tua chiave API Balikobot dall'area clienti. Dopo il salvataggio il campo resta vuoto e mostra Saved - leave empty to keep it. Clear the API user to remove the saved key. Inserisci un nuovo valore solo per modificarla.

Carrier: il corriere Balikobot usato per tariffe e punti di ritiro: Česká pošta (predefinito), Zásilkovna (Packeta), PPL, DPD, GLS, DHL Express, UPS, TNT, FedEx, Geis, InTime, Uloženka, Toptrans, Pošta bez hranic, Slovenská pošta, SPS (Slovak Parcel Service) o Magyar Posta. Deve essere attivato nel tuo account Balikobot.

Service type: il codice di servizio Balikobot del corriere. Predefinito: NP. Per Česká pošta: NP = pacco presso un ufficio postale, NB = pacco a Balíkovna, DR = consegna a domicilio. I codici degli altri corrieri sono elencati nell'area clienti Balikobot e nella documentazione API.

Prezzo (tutti i prezzi sono nella valuta predefinita del negozio)

Price source: come viene calcolato il prezzo.

Country prices: un elenco di paesi e prezzi. Clicca su Add row per aggiungere una riga e sul pulsante di rimozione per eliminarne una. Scegli * All other countries per tutti i paesi senza una riga propria. Decimali con punto o virgola. Viene usato in modalità fissa e come alternativa in caso di errore dell'API. Un paese senza prezzo (e senza riga *) non riceve una tariffa fissa, quindi il metodo gli è nascosto.

Fixed price per: Order (predefinito) addebita il prezzo una sola volta. Item (price x quantity) lo moltiplica per il numero di articoli nel carrello. Questo vale solo per i prezzi fissi. Una tariffa Balikobot in tempo reale vale sempre per l'intero pacco.

Exchange rate: il valore di 1 unità della valuta del prezzo Balikobot (di solito CZK) nella valuta predefinita del tuo negozio, per esempio 0.04. Viene usato solo quando Balikobot restituisce un prezzo in un'altra valuta. Lascialo vuoto per rifiutare tali prezzi, così al cliente non viene mai addebitato un prezzo sbagliato.

Condizioni

Min weight (kg): nasconde il metodo quando il carrello pesa meno. 0 significa nessun limite (predefinito). I pesi dei prodotti vengono convertiti dalla loro classe di peso OpenCart.

Max weight (kg): nasconde il metodo quando il carrello pesa di più. Predefinito: 100. 0 significa nessun limite. Un campo vuoto equivale a 100 kg. Se Min weight (kg) è maggiore del massimo, vedi un avviso e vengono mantenuti i pesi precedenti.

Minimum order amount: mostra il metodo solo a partire da questo subtotale del carrello (dopo i coupon, senza imposte). Lascia il campo vuoto per mostrarlo sempre.

Free shipping: attiva la spedizione gratuita a partire dall'importo indicato sotto.

Free shipping from: il subtotale del carrello (dopo i coupon, senza imposte) da cui la spedizione è gratuita. In quel caso non viene inviata alcuna richiesta a Balikobot. Usato solo quando Free shipping è attivo.

Tax Class: l'imposta di questa classe viene aggiunta al prezzo della spedizione. I prezzi Balikobot sono di solito senza IVA. Predefinito: --- None ---.

Disponibilità

Normalmente il metodo viene offerto nella zona geografica selezionata qui (All Zones significa ovunque). Ignore geo zone lo offre invece nei paesi dell'elenco.

Geo Zone: offre il metodo solo per indirizzi in questa zona geografica. Le zone geografiche si gestiscono in System > Localisation > Geo Zones.

Ignore geo zone: offre il metodo nei paesi indicati sotto, qualunque sia la zona geografica.

Countries: i paesi di destinazione per quella modalità. Lascia vuoto per consentire tutti i paesi. Usato solo con Ignore geo zone.

Punti di ritiro

Pickup point selection: il cliente deve scegliere un punto di ritiro. Usalo per i servizi con ritiro, per esempio Česká pošta NP o NB, o Zásilkovna. Richiede l'utente e la chiave API.

Selector width: la larghezza CSS dell'elenco dei punti di ritiro, per esempio 100% o 400px. Predefinito: 100%.

Avanzate

Debug log: registra le richieste API e i calcoli delle tariffe in storage/logs/vfd_blkb_debug.log.php. Il file non può essere letto dal web. Gli errori dell'API vengono sempre registrati. Credenziali e indirizzi dei clienti non vengono mai registrati. Disattiva il log quando hai finito. Quando il file raggiunge 5 MB viene spostato in vfd_blkb_debug.old.log.php e ne viene avviato uno nuovo.

Log: mostra la dimensione e le ultime voci del log. Clicca su Clear log per svuotarlo.

Remove data on uninstall: se attivo, disinstallando l'estensione vengono eliminati impostazioni, log e punti di ritiro dei checkout senza ordine. Se disattivo (predefinito), le impostazioni vengono conservate. I punti di ritiro salvati negli ordini vengono sempre conservati.

Importa / Esporta

Export: clicca su Download JSON per salvare le impostazioni in un file JSON. La chiave API 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 chiave API salvata viene mantenuta.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo Balikobot. Se è impostata una Geo Zone (e Ignore geo zone è disattivato) e l'indirizzo ne è fuori, Balikobot non viene offerto. Con Ignore geo zone decide l'elenco Countries. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non rientrano nell'importo dell'ordine. L'estensione verifica poi 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 delle imposte. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata alcuna richiesta a Balikobot.

In modalità fissa il prezzo viene preso da Country prices. Nelle modalità in tempo reale l'estensione invia a Balikobot il corriere, il tipo di servizio, il paese e il CAP di destinazione e il peso del carrello in kg. Una tariffa in tempo reale viene richiesta solo quando l'indirizzo di consegna ha un CAP. Un prezzo in un'altra valuta viene convertito con Exchange rate, oppure rifiutato se non è impostato alcun tasso. Il prezzo viene calcolato nella valuta predefinita del negozio, arrotondato alle sue decimali e mostrato al cliente nella sua valuta con l'imposta della Tax Class selezionata.

I prezzi in tempo reale vengono memorizzati per 1 ora, così lo stesso carrello non genera una nuova richiesta. Una richiesta non riuscita viene memorizzata per 5 minuti e il timeout dell'API è di 12 secondi, così il checkout non attende Balikobot a ogni aggiornamento. Gli errori dell'API non vengono mai mostrati al cliente: il metodo viene nascosto, oppure in modalità di riserva si usa il prezzo fisso. I dettagli vanno nel log di debug.

L'estensione non crea spedizioni in Balikobot, non stampa etichette e non richiede ritiri: ordina la spedizione nell'area clienti Balikobot. Non traccia i pacchi e non cambia lo stato degli ordini. Per tutte le destinazioni si usano un solo corriere e un solo tipo di servizio. I punti di ritiro sono mostrati come menu a tendina, senza mappa.

Su OpenCart 4 il cliente clicca su Choose nel blocco del metodo di spedizione della pagina di checkout e sceglie Balikobot nella finestra Shipping method options. Il metodo funziona come su OpenCart 3; l'elenco dei punti di ritiro è descritto in Punti di ritiro.

Punti di ritiro

Con Pickup point selection attivo, sotto il metodo Balikobot nel passaggio Delivery Method del checkout di OpenCart compare un elenco di punti di ritiro. L'elenco viene caricato dal "branchlocator" di Balikobot per il paese, la città e il CAP dell'indirizzo di consegna. Finché l'indirizzo non ha una città, il cliente vede Enter your city to see the pickup points. Mentre l'elenco si carica, vede Loading pickup points.... L'elenco viene memorizzato fino a 12 ore.

La scelta viene salvata appena il cliente seleziona un punto. È obbligatoria: Continue nel passaggio di spedizione viene rifiutato con Please select a pickup point. Il server verifica inoltre che il punto scelto appartenga all'indirizzo di consegna. In caso contrario, il cliente vede The selected pickup point is not available for your shipping address. Please choose a pickup point again. Se in quel momento Balikobot non è raggiungibile, un punto già scelto viene accettato. Se non si trova alcun punto, al cliente viene chiesto di controllare città e CAP o di scegliere un altro metodo di spedizione. Se i punti non si possono caricare, al cliente viene chiesto di riprovare più tardi o di scegliere un altro metodo di spedizione.

Su OpenCart 4 il cliente clicca su Choose nel blocco del metodo di spedizione della pagina di checkout. La finestra Shipping method options mostra l'elenco dei punti di ritiro sotto il metodo Balikobot, con gli stessi testi e controlli. L'elenco viene caricato ogni volta che la finestra si apre, perché l'indirizzo può cambiare nella stessa pagina di checkout, e proviene dalla cache quando possibile. Se il cliente clicca su Continue nella finestra senza un punto valido, il messaggio compare in cima alla pagina di checkout e la finestra resta aperta. OpenCart 4 mantiene un unico ordine per il checkout e lo aggiorna a ogni conferma; il punto di ritiro dell'ordine viene aggiornato insieme ad esso.

Il punto scelto viene aggiunto al metodo di spedizione dell'ordine come - Pickup point: seguito dal suo nome e indirizzo. Il cliente lo vede nelle pagine ordine del proprio account e nelle e-mail d'ordine, ed è stampato in fattura.

Nella pagina ordine dell'amministratore (Sales > Orders, View) il pannello Balikobot pickup point mostra il punto, il suo ID Balikobot e il corriere, che ti servono quando crei la spedizione in Balikobot. Clicca su Change, scegli un altro punto vicino all'indirizzo dell'ordine e clicca su Save. Anche il testo del metodo di spedizione dell'ordine viene aggiornato e vedi Pickup point updated. Cambiare il punto richiede solo il permesso di modifica degli ordini, non l'accesso alle impostazioni dell'estensione. Se un ordine non ha un punto, il pannello mostra No pickup point was selected for this order. Il pannello funziona anche con Balikobot disattivato: gli ordini esistenti conservano i dati del punto di ritiro e puoi ancora cambiare il punto.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco della licenza License — VibeFox Balikobot è il primo blocco di Extensions > Extensions > Shipping > VibeFox Balikobot > 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 si trovano la riga Product: opencart-shipping-balikobot 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 con 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 dominio: l'indirizzo del negozio della 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, Balikobot 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 come (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 per i 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

Balikobot non compare al checkout: verifica che la licenza sia attiva e che Enable/Disable sia attivo. Leggi gli avvisi in cima alla pagina dell'estensione. Controlla Geo Zone (o Ignore geo zone e Countries), i limiti di peso e il Minimum order amount. In modalità fissa, verifica che il paese o * All other countries abbia un prezzo. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.

Le tariffe in tempo reale non compaiono: attiva Debug log, ricarica il checkout e guarda il campo Log nella pagina dell'estensione. Mostra il motivo: credenziali API mancanti, CAP non ancora inserito, l'errore Balikobot per il corriere e il servizio (per esempio "authorization failed: check the API user and API key"), oppure un prezzo in un'altra valuta senza Exchange rate. Con Live Balikobot rate, fixed price if the API fails i clienti ricevono comunque il prezzo fisso mentre risolvi il problema.

I prezzi sono nella valuta sbagliata: i prezzi fissi sono nella valuta predefinita del tuo negozio. Balikobot restituisce le tariffe in tempo reale nella valuta del tuo contratto Balikobot (di solito CZK). Se è diversa dalla valuta predefinita, imposta Exchange rate.

L'IVA è inclusa? I prezzi Balikobot sono di solito senza IVA. Con una Tax Class selezionata, OpenCart aggiunge l'imposta sulla spedizione.

Nessun punto di ritiro nell'elenco: verifica che utente e chiave API siano impostati, che il corriere supporti "branchlocator" e che l'indirizzo di consegna abbia città e CAP. Controlla il log per l'errore Balikobot.

Tariffe o punti di ritiro sembrano non aggiornati dopo una modifica: clicca su Save nella pagina dell'estensione. Questo svuota le tariffe e i punti di ritiro in cache.

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

Per sviluppatori: l'indirizzo dell'API Balikobot può essere sostituito con l'impostazione vfd_blkb_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 Balikobot. 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. Le tariffe e i punti di ritiro in cache vengono sempre rimossi, e il pannello dei punti di ritiro e l'elenco al checkout smettono di funzionare. Se Remove data on uninstall è attivo, vengono eliminati anche impostazioni, log e punti di ritiro dei checkout senza ordine. Se è disattivo, le altre impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. I dati dei punti di ritiro salvati negli ordini non vengono mai eliminati, e il testo del metodo di spedizione degli ordini esistenti mantiene il punto di ritiro.

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

Balikobot è un marchio del rispettivo titolare. Questa estensione non è affiliata a Balikobot né approvata da Balikobot.