VibeFox Balikobot 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 Balikobot (per tariffe in tempo reale e punti di ritiro): ti serve un account Balikobot con accesso all'API. Il nome 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 dubbio, 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
1. Nel back office vai su Modules > Module Manager e clicca su Upload a module. Scegli il file ZIP del modulo.
2. Al termine del caricamento, clicca su Configure, oppure cerca più tardi VibeFox Balikobot nell'elenco dei moduli e clicca su Configure.
3. Incolla la tua chiave di licenza VibeFox in License key nel blocco licenza in cima alla pagina Configure e clicca su Activate (vedi Chiave di licenza).
4. Inserisci il nome 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. Clicca su Save.
All'installazione il modulo crea il corriere Balikobot con il testo dei tempi di consegna Delivery by Balikobot. Il corriere viene assegnato alle zone di Repubblica Ceca, Slovacchia e Ungheria e a tutti i gruppi di clienti. Puoi modificare zone, gruppi di clienti, tempi di consegna, logo e limiti di dimensione in Shipping > Carriers. Non impostare i prezzi lì: il prezzo arriva sempre dal modulo.
Configurazione
Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Balikobot > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Dopo il salvataggio vedi Settings saved. Cached rates and pickup points were cleared. In cima alla pagina compaiono avvisi su impostazioni che nasconderebbero il corriere, le tariffe in tempo reale o i punti di ritiro: tariffe in tempo reale o punti di ritiro senza nome utente o chiave API, valuta del negozio diversa da CZK senza Exchange rate, Country prices vuoto con prezzi fissi o con il fallback, un'unità di peso del negozio che il modulo non riconosce (i pesi vengono letti come kg; usa kg, g, lb o oz) e un corriere eliminato. Un valore che non è un numero non viene salvato e vedi un avviso con il nome del campo.
General
Enable/Disable: attiva o disattiva la spedizione Balikobot. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.
Name: il nome del metodo di spedizione mostrato al cliente (il nome del corriere). Predefinito: Balikobot. Obbligatorio, massimo 64 caratteri.
Tax status: None, oppure Taxable con una delle tue regole fiscali. Con una regola fiscale, la sua imposta viene aggiunta al prezzo di spedizione. La scelta viene salvata sul corriere. I prezzi Balikobot sono di solito senza IVA. Predefinito: None.
Account API Balikobot (necessario per tariffe in tempo reale e punti di ritiro)
API user: il tuo nome 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 a un ufficio postale, NB = pacco a Balíkovna, DR = consegna a domicilio. I codici degli altri corrieri sono elencati nell'area clienti di Balikobot e nella documentazione dell'API.
Prezzo (tutti i prezzi sono nella valuta predefinita del negozio)
Price source: come viene calcolato il prezzo.
Country prices: una tabella di codici paese a 2 lettere (per esempio CZ, SK) e prezzi. Clicca su Add row per aggiungere un paese e sull'icona del cestino per rimuoverlo. Usa * come codice paese per tutti gli altri paesi. Decimali con punto o virgola. Viene usato nella modalità fissa e come fallback dell'API. Un paese senza prezzo (e senza una riga *) non ha una tariffa fissa. Le righe non valide vengono rimosse al salvataggio e un avviso le elenca.
Fixed price per: Order applica 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 è sempre riferita all'intero pacco.
Exchange rate: il valore di 1 unità della valuta del prezzo Balikobot (di solito CZK) nella valuta predefinita del negozio, per esempio 0.04. Usato solo quando Balikobot restituisce un prezzo in una valuta diversa. Lascia il campo vuoto per rifiutare tali prezzi, così un cliente non paga mai un prezzo sbagliato.
Condizioni
Min weight (kg): nasconde il corriere quando il carrello è più leggero. 0 significa nessun limite. I pesi dei prodotti vengono convertiti dall'unità di peso del negozio.
Max weight (kg): nasconde il corriere quando il carrello è più pesante. Predefinito: 100. 0 significa nessun limite. Un campo vuoto significa 100 kg. Se Min weight (kg) è maggiore del massimo, vedi un avviso e i pesi precedenti vengono mantenuti.
Minimum order amount: mostra il corriere solo a partire da questo subtotale del carrello (dopo gli sconti, senza tasse). 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 gli sconti, senza tasse) da cui la spedizione è gratuita. In questo caso non viene inviata alcuna richiesta all'API.
Disponibilità senza zone di spedizione
Normalmente il corriere viene offerto nelle sue zone in Shipping > Carriers.
Ignore shipping zones: offre il corriere nei paesi indicati sotto anche se non è collegato alla loro zona. Il modulo collega il corriere a tutte le zone, anche a quelle che creerai in seguito. Quando disattivi l'opzione, le zone aggiunte in questo modo vengono rimosse. Le tue zone restano invariate.
Countries: i paesi di destinazione per questa modalità. Lascia il campo vuoto per usare tutti i paesi verso cui spedisci. Viene usato solo con Ignore shipping zones.
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, oppure Zásilkovna. Richiede nome utente e 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 logs/vfd_blkb_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori dell'API vengono sempre registrati. Credenziali e indirizzi dei clienti non vengono mai registrati. Disattiva il log quando hai finito.
Log: mostra la dimensione e le ultime voci del log. Clicca su Clear log per svuotarlo.
Remove data on uninstall: se attivo, la disinstallazione del modulo elimina le sue impostazioni e il corriere. Disinstallare senza questa opzione non elimina mai dati. I punti di ritiro salvati negli ordini vengono conservati.
Come funziona al checkout
Nel passaggio della spedizione PrestaShop chiede al modulo il prezzo Balikobot. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nell'importo dell'ordine. Il modulo controlla prima i paesi (con Ignore shipping zones), il peso del carrello e il Minimum order amount. 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 il modulo 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 se 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 e poi mostrato nella valuta del carrello del cliente.
I prezzi in tempo reale vengono memorizzati nella cache per 1 ora, così lo stesso carrello non genera una nuova richiesta. Una richiesta non riuscita viene memorizzata nella cache 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 corriere viene nascosto oppure, in modalità fallback, si usa il prezzo fisso. I dettagli finiscono nel log di debug.
Se modifichi il corriere in Shipping > Carriers dopo che ha degli ordini, PrestaShop lo salva come una nuova versione del corriere. Il modulo segue automaticamente la nuova versione.
Il modulo non crea spedizioni in Balikobot, non stampa etichette e non prenota ritiri: ordina la spedizione nell'area clienti di Balikobot. Non traccia i pacchi e non aggiorna gli stati degli ordini. Per tutte le zone viene usato un solo corriere e un solo tipo di servizio. I punti di ritiro vengono mostrati come elenco a discesa, senza mappa.
Punti di ritiro
Con Pickup point selection attivo, nel passaggio della spedizione compare un elenco di punti di ritiro sotto il corriere Balikobot. 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. L'elenco viene memorizzato nella cache per 12 ore.
La scelta viene salvata nel carrello non appena il cliente seleziona un punto. È obbligatoria: Continue nel passaggio della spedizione e Place order sono bloccati con Please select a pickup point. Il server verifica anche 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 non viene trovato alcun punto, il cliente è invitato a controllare la città e il CAP oppure a scegliere un altro metodo di spedizione. Se i punti non possono essere caricati, il cliente è invitato a riprovare più tardi o a scegliere un altro metodo di spedizione.
Il punto di ritiro scelto viene salvato nell'ordine. Nella pagina dell'ordine nel back office viene mostrato nel blocco Balikobot pickup point, con l'ID della filiale Balikobot e il corriere, che ti servono quando crei la spedizione in Balikobot. Clicca su Change per scegliere un altro punto vicino all'indirizzo dell'ordine e clicca su Save. Per cambiare il punto basta il permesso di modificare gli ordini, non l'accesso alle pagine dei moduli. Se un ordine non ha un punto, il blocco mostra No pickup point was selected for this order.
Il cliente vede il punto come Pickup point: nella pagina di conferma dell'ordine e nei dettagli dell'ordine. Nell'email di conferma dell'ordine e nell'email di nuovo ordine per il negozio (modulo Mail alerts) viene aggiunto dopo il nome del corriere. Gli ordini esistenti mantengono i dati del punto di ritiro.
Chiave di licenza
Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Balikobot è il primo blocco di Modules > Module Manager > VibeFox Balikobot > Configure, sopra le impostazioni. Incolla la chiave in License key e clicca su Activate. Dopo, 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 di essi ci sono la riga Product: presta-shipping-balikobot 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 seguito da una data. Dopo un cambio dell'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, il modulo continua a funzionare con l'ultimo stato noto.
Una chiave funziona su un dominio: il dominio 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 Balikobot non viene mostrato ai clienti al checkout e non viene calcolata nessuna tariffa. La vetrina di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il corriere viene 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 alla settimana. Non serve alcun cron job. Disinstallare o ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.
Risoluzione dei problemi
Balikobot non compare al checkout: controlla che la licenza sia attiva e che Enable/Disable sia attivo. Leggi gli avvisi in cima alla pagina del modulo. In Shipping > Carriers controlla che il corriere copra la zona del paese del cliente e il gruppo del cliente, oppure attiva Ignore shipping zones e controlla Countries. Controlla i limiti di peso e il Minimum order amount. In modalità fissa, verifica che il paese o * abbia un prezzo. I prodotti possono anche essere limitati a determinati corrieri nella pagina del prodotto.
Le tariffe in tempo reale non compaiono: attiva Debug log, ricarica il checkout e controlla il campo Log nella pagina del modulo. Mostra il motivo: credenziali API mancanti, CAP non ancora inserito, l'errore di Balikobot per il corriere e il servizio (per esempio authorization failed, controlla nome utente e chiave API) 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 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 Tax status impostato su una regola fiscale, PrestaShop aggiunge l'imposta sulla spedizione.
Nessun punto di ritiro nell'elenco: controlla che nome 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 di Balikobot.
Tariffe o punti di ritiro sembrano obsoleti dopo una modifica: clicca su Save nella pagina del modulo. Questo svuota le tariffe e i punti di ritiro in cache.
La pagina dice che il corriere Balikobot non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Ripristina il modulo in Modules > Module Manager per ricrearlo.
Per gli sviluppatori: il modulo ha hook propri per modificare l'indirizzo dell'API (actionVfdBlkbApiUrl), il pacchetto "transportcosts" (actionVfdBlkbTransportcostsPackage) e il numero di punti di ritiro (actionVfdBlkbPickupMaxResults, predefinito 30).
Disinstallazione
Vai su Modules > Module Manager, apri il menu accanto a VibeFox Balikobot e scegli Uninstall. La chiave di licenza, lo stato della licenza, le tariffe e i 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 senza ordine. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni vengono mantenute. Reinstallando il modulo (o ripristinandolo), il corriere salvato riprende lo stato che aveva prima della disinstallazione: attivo resta attivo, disattivo resta disattivo. I dati del punto di ritiro salvati negli ordini non vengono mai eliminati.
Balikobot è un marchio del rispettivo proprietario. Questo modulo non è affiliato a Balikobot né approvato da Balikobot.