VibeFox Balikobot 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 Balikobot (per tariffe in tempo reale e punti di ritiro): ti serve un account Balikobot con accesso all'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). Se non sei sicuro, chiedi al supporto Balikobot. I prezzi fissi funzionano senza account.

Chiave di licenza VibeFox: si acquista 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 clicca su Install Now. Puoi anche caricare la cartella vfd_balikobot in /wp-content/plugins/ via FTP.

2. Clicca su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox Balikobot, oppure clicca su Settings sotto il nome del plugin nella pagina Plugin.

4. Inserisci la chiave di licenza VibeFox nel blocco licenza in alto nella pagina e clicca su Activate.

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

6. Aggiungi VibeFox Balikobot a una zona di spedizione (per esempio Repubblica Ceca) 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 Balikobot. Si applicano a tutte le zone di spedizione. Gli avvisi su impostazioni che nasconderebbero il metodo, le tariffe in tempo reale o i punti di ritiro compaiono in alto nella pagina. Ogni volta che salvi le impostazioni, le tariffe e i punti di ritiro in cache vengono cancellati. Quando aggiungi il metodo a una zona, la finestra della zona ha un solo campo:

Title (zone): il nome del metodo di spedizione mostrato ai clienti in questa zona. Lascialo vuoto per usare il Name globale.

Generale

Enable/Disable: attiva o disattiva la spedizione Balikobot in tutte le zone contemporaneamente.

Name: il nome del metodo di spedizione mostrato ai clienti. Una zona può sostituirlo con il proprio Title. Predefinito: Balikobot.

Tax status: Taxable significa che WooCommerce aggiunge l'IVA sulla spedizione sopra il prezzo; None significa che non la aggiunge. I prezzi Balikobot di solito sono senza IVA.

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.

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 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 Balikobot e nella documentazione API.

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

Price source: come viene calcolato il prezzo.

Country prices: un prezzo fisso per ogni paese di destinazione (codice a 2 lettere, per esempio CZ, SK). Usa * per tutti gli altri paesi. Decimali con punto o virgola. Usato nella modalità fissa e come alternativa in caso di errore dell'API. Un paese senza prezzo (e senza riga *) non riceve una tariffa fissa.

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

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

Condizioni

Min weight (kg): nasconde il metodo 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 metodo quando il carrello è più pesante. Predefinito: 100. 0 significa nessun limite.

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

Excluded shipping classes: nasconde il metodo se nel carrello c'è un prodotto appartenente a una di queste classi di spedizione di WooCommerce.

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

Free shipping from: il subtotale del carrello (dopo sconti, senza tasse) da cui la spedizione è gratuita. In questo caso non viene inviata nessuna richiesta all'API.

Disponibilità senza zone di spedizione

Ignore shipping zones: offre il metodo nei paesi indicati sotto, anche se non è aggiunto alla zona corrispondente.

Countries: i paesi di destinazione per quella modalità. Lascia vuoto per usare tutti i paesi in cui spedisci. 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, o Zásilkovna. Richiede 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 WooCommerce > Status > Logs, origine "vfd-balikobot". Gli errori dell'API vengono sempre registrati. Credenziali e indirizzi dei clienti non vengono mai registrati.

Remove data on uninstall: se attivo, eliminando il plugin vengono rimosse le sue impostazioni e i metodi delle zone. Disattivare il plugin non cancella mai dati. I punti di ritiro salvati negli ordini vengono conservati.

Come funziona al checkout

Quando il cliente inserisce un indirizzo di consegna, il plugin controlla il peso del carrello, il Minimum order amount e le Excluded shipping classes. Se si applica la spedizione gratuita, la tariffa è 0 e nessuna richiesta viene inviata a Balikobot.

In modalità fissa il prezzo viene preso da Country prices. Nelle modalità in tempo reale il plugin 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 dopo che il cliente ha inserito un CAP. Un prezzo in un'altra valuta viene convertito con Exchange rate, oppure rifiutato se non è impostato alcun tasso.

I prezzi in tempo reale vengono memorizzati nella cache per 1 ora, così lo stesso carrello non genera una nuova richiesta. Una richiesta fallita 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 metodo viene nascosto oppure, nella modalità di ripiego, viene usato il prezzo fisso. I dettagli vanno nel log.

Il metodo funziona sul checkout classico e sui blocchi Carrello e Checkout. È compatibile con WooCommerce High-Performance Order Storage (HPOS).

Il plugin non crea spedizioni in Balikobot, non stampa etichette e non prenota ritiri: crea la spedizione nell'area clienti di Balikobot. Non traccia i pacchi e non aggiorna lo stato degli ordini. Per tutte le zone si usano un solo corriere e un solo tipo di servizio. I punti di ritiro sono mostrati come elenco a discesa, senza mappa.

Punti di ritiro

Con Pickup point selection attivo, sotto l'opzione Balikobot compare al checkout un elenco di punti di ritiro, sia nel checkout classico sia in quello a blocchi. L'elenco viene caricato dal "branchlocator" di Balikobot per il paese, la città e il CAP del cliente. Finché il cliente non inserisce città e CAP, vede Enter your city and postcode to see the pickup points. L'elenco viene memorizzato nella cache per 12 ore.

La scelta è obbligatoria: il cliente vede Please select a pickup point. Il server verifica inoltre che il punto scelto appartenga all'indirizzo di spedizione. Dopo un cambio di indirizzo, al cliente viene chiesto di scegliere di nuovo un punto di ritiro. Se i punti non possono essere caricati, al cliente viene chiesto di riprovare più tardi o di scegliere un altro metodo di spedizione.

Il punto di ritiro scelto viene salvato nell'ordine. Nella schermata dell'ordine nell'area admin compare sotto l'indirizzo di spedizione come 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. Il cliente vede il punto come Pickup point nella pagina dell'ordine e nelle email dell'ordine (HTML e testo semplice). Gli ordini esistenti conservano i dati del loro punto di ritiro.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in alto in WooCommerce > Settings > Shipping > VibeFox Balikobot. Incolla la chiave in License key e clicca 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 verificare 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, Balikobot non viene mostrato ai clienti al checkout. I gestori del negozio che hanno effettuato l'accesso lo vedono ancora, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugin e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene controllato di nuovo automaticamente in background.

Risoluzione dei problemi

Balikobot 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 consentito). Leggi gli avvisi in alto nella pagina delle impostazioni. Controlla i limiti di peso, Minimum order amount e Excluded shipping classes. In modalità fissa, verifica che il paese o * abbia un prezzo.

Le tariffe in tempo reale non compaiono: attiva Debug log, ricarica il checkout e apri WooCommerce > Status > Logs (origine "vfd-balikobot"). Lì trovi il motivo: credenziali API mancanti, CAP non ancora inserito, errore Balikobot per il corriere e il servizio, 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 del tuo negozio. Balikobot restituisce i prezzi in tempo reale nella valuta del tuo contratto Balikobot (di solito CZK). Se è diversa dalla valuta del negozio, imposta Exchange rate.

L'IVA è inclusa? I prezzi Balikobot di solito sono senza IVA. Con Tax status impostato su Taxable, WooCommerce aggiunge l'IVA sulla spedizione.

Nessun punto di ritiro nell'elenco: verifica che utente e chiave API siano inseriti, che il corriere supporti "branchlocator" e che il cliente abbia inserito città e CAP. Controlla nel log l'errore di Balikobot.

Tariffe o punti di ritiro sembrano non aggiornati dopo una modifica: salva la pagina delle impostazioni. Così vengono cancellati le tariffe e i punti di ritiro in cache.

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 clicca su Check now. Se l'indirizzo del sito è cambiato, clicca 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 e cancella solo le cache. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato di licenza di questo plugin, così come le tariffe e i punti di ritiro in cache, vengono sempre rimossi. Impostazioni e metodi delle zone vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano per una futura reinstallazione. I dati dei punti di ritiro salvati negli ordini non vengono mai eliminati.

Balikobot è un marchio del suo rispettivo proprietario. Questo plugin non è affiliato a Balikobot né approvato da Balikobot.