VibeFox Instabee 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.

Credenziali API Budbee (solo per la selezione del box): una chiave API e un secret API. Instabee le rilascia ai commercianti con un accordo di consegna. Chiedi al tuo referente Instabee oppure usa il portale commercianti di Instabee. La documentazione dell'API è su developer.budbee.com. Senza credenziali il corriere funziona comunque con prezzi fissi, ma i clienti non possono scegliere un box.

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un solo dominio.

Installazione

1. Nel back office vai su Modules > Module Manager e fai clic su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, fai clic su Configure, oppure trova VibeFox Instabee più tardi nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la tua chiave di licenza VibeFox in License key nel blocco licenza in cima alla pagina Configure, poi fai clic su Activate (vedi Chiave di licenza).

4. Compila la sezione Prices e, per il selettore dei box, la tua API key e il tuo API secret Budbee (vedi Configurazione). Fai clic su Save.

All'installazione il modulo crea il corriere Instabee parcel box con il testo dei tempi di consegna Delivery to an Instabee parcel box. Il corriere viene assegnato a tutti i gruppi di clienti e alle zone di Svezia, Finlandia, Danimarca, Paesi Bassi e Belgio. Puoi modificare zone, gruppi di clienti, tempi di consegna e logo in Shipping > Carriers. Non impostare prezzi lì: il prezzo arriva sempre dal modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Instabee > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina.

Gli avvisi sopra le impostazioni ti segnalano quando è compilata solo una delle due credenziali API, quando non ci sono credenziali API, quando non ci sono prezzi per paese né costo di riserva, quando l'ultima richiesta all'API Budbee è fallita (con data, ora e motivo), quando il corriere Instabee non viene trovato e quando l'unità di peso del negozio non viene riconosciuta (imposta kg, g, lb o oz in International > Localization, Local units). Ogni volta che salvi le impostazioni, vengono cancellati gli elenchi dei box in cache e l'ultimo errore API. Se il nome del metodo o lo stato fiscale non sono validi, oppure Min weight (kg) è maggiore di Max weight (kg), non viene salvato nulla e compare un errore.

General

Enable/Disable: attiva o disattiva il corriere. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.

Method name: il nome del corriere che il cliente vede al checkout. Predefinito: Instabee parcel box. Obbligatorio, massimo 64 caratteri.

Tax status: None significa che i prezzi sotto sono definitivi. Taxable con una regola fiscale significa che PrestaShop aggiunge sopra i prezzi sotto l'imposta sulla spedizione di quella regola.

Selettore dei box (API Budbee)

Con le credenziali API il cliente sceglie un box vicino al proprio CAP al checkout, e il box viene salvato nell'ordine. Servono entrambi i campi. Il selettore resta disattivato finché non sono compilati entrambi.

API key: la tua chiave API Budbee (il nome utente di HTTP Basic).

API secret: il tuo secret API Budbee (la password di HTTP Basic). Non viene mai scritto nel log.

Dopo il salvataggio, entrambi i campi restano vuoti e mostrano Saved - leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo. Per eliminare le credenziali salvate, spunta Remove the saved API key and secret e salva. Se non c'è nulla di salvato, la pagina mostra No credentials saved.

Test environment: usa l'API di staging di Budbee (api.staging.budbee.com). Attivalo solo con credenziali di staging fornite da Instabee. I negozi in produzione lo lasciano disattivato (api.budbee.com). Predefinito: disattivato.

Prezzi (il titolo della sezione mostra la valuta predefinita del negozio)

Tutti i prezzi sono nella valuta predefinita del negozio, IVA esclusa. Sono accettati sia la virgola sia il punto decimale (49,90 = 49.90). Il prezzo viene mostrato al cliente nella valuta del carrello.

Calculation type: come viene applicato il prezzo.

Country prices: una tabella con le colonne Country, Price, XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg e XL >5 kg. Fai clic su Add country per aggiungere una riga e sull'icona del cestino per rimuoverla. Scegli * Any other country per una riga che si applica a tutti i paesi senza una riga propria. Una fascia vuota o 0 usa la colonna Price. Un Price di 0 significa consegna gratuita. Se la riga del paese non ha un prezzo per il peso del carrello, si usa la riga *, poi il Fallback cost. Un prezzo che non è un numero viene cancellato e un avviso lo segnala. I pesi vengono convertiti dall'unità di peso del negozio in kg.

Fallback cost: usato quando né la riga del paese di destinazione né la riga * danno un prezzo. Lascialo vuoto per nascondere il corriere in quei paesi.

Condizioni

Min weight (kg): nasconde il corriere sotto questo peso del carrello. Predefinito: 0 (nessun limite).

Max weight (kg): nasconde il corriere sopra questo peso del carrello. I box accettano fino a circa 20 kg. Predefinito: 20. 0 significa nessun limite. Non può essere inferiore a Min weight (kg).

Minimum order amount: mostra il corriere solo quando il subtotale del carrello (prodotti che richiedono spedizione, dopo sconti, prima delle imposte) raggiunge questo importo. Lascialo vuoto per mostrarlo sempre.

Free shipping from: il subtotale del carrello (dopo sconti, prima delle imposte) a partire dal quale il corriere è gratuito. Lascialo vuoto per non renderlo mai gratuito.

Se un valore in questi campi o in Fallback cost non è un numero, non viene salvato, resta il valore precedente e un avviso indica il campo.

Disponibilità senza zone di spedizione

Di norma il corriere viene offerto nelle zone di spedizione a cui è collegato in Shipping > Carriers. In alternativa puoi attivarlo qui per un elenco di paesi.

Ignore shipping zones: offre il corriere nei paesi sotto indicati, anche dove le sue zone non li includono. Il corriere viene collegato a tutte le zone attive, comprese quelle create in seguito. Quando disattivi di nuovo l'opzione, il corriere riprende le zone che aveva prima.

Countries: i paesi di destinazione per questa modalità. Lascialo vuoto per consentire tutti i paesi. Questo campo viene usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: scrive i messaggi di debug in logs/vfd_ibee_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori API vengono sempre registrati, anche con questa opzione disattivata. Le chiavi API e i dati dei clienti non vengono mai registrati.

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

Remove data on uninstall: se attivo, la disinstallazione del modulo elimina le impostazioni e il corriere. Se disattivo, la disinstallazione si limita a disattivare il corriere. I box salvati sugli ordini vengono sempre conservati.

Come funziona al checkout

Al passo di spedizione PrestaShop chiede al modulo il prezzo di Instabee. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non rientrano nell'importo dell'ordine. Il modulo verifica le condizioni: peso del carrello e importo minimo dell'ordine e, con Ignore shipping zones, i paesi consentiti. Se il subtotale del carrello raggiunge Free shipping from, il prezzo è 0. Altrimenti il prezzo viene preso dalla riga Country prices del paese di destinazione, dalla riga * o dal Fallback cost. Se non c'è un prezzo, il corriere viene nascosto.

Quando il cliente seleziona il corriere Instabee e le credenziali API sono impostate, sotto il corriere compare un blocco Parcel box per Svezia, Finlandia, Danimarca, Paesi Bassi e Belgio. Elenca i box vicini al CAP dell'indirizzo di consegna, ordinati per distanza, con nome, indirizzo e distanza. Il cliente può digitare un altro CAP e fare clic su Search (oppure premere Invio). Finché non viene inserito un CAP, il blocco lo richiede. Se non viene trovato alcun box, al cliente viene chiesto di provare un altro CAP o di scegliere un altro metodo di spedizione. Per gli altri paesi il corriere viene offerto senza box.

Il box è obbligatorio. Il box scelto viene salvato nel carrello solo se è nell'elenco Budbee per quel CAP. Quando il cliente fa clic su Continue nel passo di consegna, il modulo verifica di nuovo il box sul server. Altrimenti il cliente vede Please choose an Instabee parcel box. Il nome del box viene preso dall'elenco Budbee, non dal browser. Se il cliente cambia il paese di consegna o il CAP dell'indirizzo, la scelta precedente viene annullata.

Il modulo invia a Budbee solo il paese di destinazione e il CAP, mai nomi, indirizzi, e-mail o dati dell'ordine. Gli elenchi dei box vengono messi in cache per 12 ore per CAP, un CAP senza box per 1 ora e una richiesta fallita per 5 minuti, così un'API lenta o guasta non rallenta ogni aggiornamento del checkout. La pagina di checkout non aspetta mai Budbee: l'elenco viene caricato in background appena il corriere è selezionato. Il timeout dell'API è di 10 secondi.

Se l'API Budbee non è raggiungibile, il cliente vede Parcel boxes cannot be loaded right now. You can place the order without choosing a box - the shop will assign one. L'ordine viene allora contrassegnato e scegli tu il box al momento di prenotare la spedizione. Un box scelto in precedenza che in quel momento non può essere verificato viene conservato e contrassegnato come non verificato.

Il selettore funziona con i temi Classic e Hummingbird. Se modifichi il corriere in Shipping > Carriers dopo che ha ricevuto ordini, PrestaShop lo salva come nuova versione del corriere. Il modulo segue automaticamente la nuova versione.

Il modulo non calcola tariffe in tempo reale, non prenota spedizioni, non stampa etichette, non fornisce numeri o e-mail di tracciamento, non offre fasce orarie di consegna Budbee Home e non mostra una mappa. Prenota il pacco per il box scelto nei tuoi strumenti di commerciante Instabee / Budbee.

Punti di ritiro

Alla creazione dell'ordine il box viene verificato ancora una volta e salvato nell'ordine. Da quel momento la vetrina non può più modificarlo. Il box viene mostrato in questi punti:

Pagina dell'ordine nel back office: un blocco Instabee parcel box con il nome del box, l'indirizzo e il Box ID. Se il box non è stato possibile verificarlo al checkout, viene contrassegnato come not verified (Budbee API was unavailable at checkout). Se nessun box è stato scelto perché l'API non era disponibile, il blocco dice Not chosen - the Budbee API was unavailable at checkout. Choose the box when you book the shipment.

Pagina di conferma dell'ordine e dettagli dell'ordine nell'account cliente: Instabee parcel box: con il nome e l'indirizzo del box.

E-mail dell'ordine: il box viene aggiunto al nome del corriere nell'e-mail di conferma dell'ordine inviata al cliente. L'e-mail di nuovo ordine al negozio (dal modulo Mail alerts di PrestaShop) mostra anche l'ID del box. Se nessun box è stato scelto perché l'API non era disponibile, solo l'e-mail al negozio lo segnala.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Instabee è il primo blocco della pagina Modules > Module Manager > VibeFox Instabee > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopo, 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: presta-shipping-instabee 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 modificare 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 oppure License expired on seguito da una data. Dopo aver cambiato l'indirizzo del negozio, o dopo aver liberato un posto per il dominio nel tuo account, fai clic 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 solo dominio: il dominio del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo posto per il dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, il corriere Instabee non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. La vetrina di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il corriere viene nascosto anche a te: puoi configurare il modulo prima di acquistare una chiave, ma non puoi provarlo al checkout. Un promemoria compare 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 ricontrollato automaticamente mentre lavori nel back office: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta a settimana. Non serve alcun cron job. Disinstallare o reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Instabee non compare al checkout: verifica che la licenza sia attiva e che Enable/Disable sia attivo. In Shipping > Carriers verifica che il corriere copra la zona del paese del cliente e il gruppo del cliente, oppure che Ignore shipping zones sia attivo e il paese sia consentito. Verifica che il paese abbia un prezzo, oppure che esista una riga * o un Fallback cost. Controlla i limiti di peso e il Minimum order amount. Un avviso sopra le impostazioni ti segnala quando non è configurato alcun prezzo. Sulla pagina del prodotto è anche possibile limitare i prodotti a determinati corrieri. Attiva il Debug log per vedere il motivo nel campo Log.

I clienti non vedono l'elenco dei box: l'elenco compare solo quando API key e API secret sono compilati, per Svezia, Finlandia, Danimarca, Paesi Bassi e Belgio, e dopo che è stato inserito un CAP. L'ultimo errore API viene mostrato sopra le impostazioni. I dettagli si trovano nel campo Log nella pagina del modulo. Attiva il Debug log per più dettagli.

HTTP 401 o 403 nel log: Budbee ha rifiutato la chiave o il secret API. Controllali e verifica che Test environment corrisponda alle tue credenziali (credenziali di staging solo con l'ambiente di test attivo).

Nessun box per un CAP: Budbee non serve quel CAP. Il cliente può cercare un altro CAP o scegliere un altro metodo di spedizione.

Il cliente non può proseguire dal passo di consegna: bisogna scegliere un box dall'elenco, a meno che l'API Budbee non sia raggiungibile. Un box che non è nell'elenco del CAP cercato non viene salvato e il cliente vede This parcel box is not in the Budbee list for the postal code. Please choose the parcel box again.

Vecchi elenchi di box dopo una modifica: fai clic su Save nella pagina del modulo. Questo cancella gli elenchi dei box in cache.

La pagina dice che il corriere Instabee non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Reimposta il modulo in Modules > Module Manager per ricrearlo. Lo stesso vale per il messaggio The settings were saved, but the carrier could not be updated. Il ripristino mantiene lo stato del corriere: un corriere disattivato resta disattivato.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Instabee e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. Gli elenchi dei box in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini mantengono la cronologia), e vengono rimosse le impostazioni, il log e i box scelti nei carrelli che non sono mai diventati ordini. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni restano. Installando di nuovo il modulo, il corriere salvato riprende lo stato che aveva. I box salvati sugli ordini vengono sempre conservati.

Instabee e Budbee sono marchi dei rispettivi proprietari. Questo modulo non è affiliato né approvato da Instabee o Budbee.