VibeFox Instabee for OpenCart — Guida

Requisiti

OpenCart: 3.0.x (testato su 3.0.5.0) o 4.0.2 o versioni successive (testato su 4.1.0.3).

PHP: 8.0 o successivo.

Credenziali API di Budbee (solo per la selezione del box per pacchi): una chiave API e un segreto 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 API si trova su developer.budbee.com. Senza credenziali il metodo funziona comunque con prezzi fissi, ma i clienti non possono scegliere un box per pacchi.

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_instabee-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_instabee.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_instabee-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non serve aggiornare Extensions > Modifications. Al posto dell'Installer puoi anche 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 Instabee 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 della licenza in cima alla pagina Edit, e clicca su Activate (vedi Chiave di licenza).

5. Compila la sezione Prices e, per il selettore del box per pacchi, la tua API key e il tuo API secret di Budbee (vedi Configurazione). Attiva Enable/Disable e clicca su Save.

OpenCart 4

1. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_instabee.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 Instabee, clicca su Install (il pulsante verde +), poi su Edit (il pulsante con la 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 uguali in entrambe le versioni.

Dopo l'installazione il metodo resta disattivato finché non attivi Enable/Disable e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni di Instabee che avevi conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox Instabee > Edit. Le sezioni sono elencate a sinistra. Un unico pulsante Save salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella anche gli elenchi dei box in cache e l'ultimo errore API. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.

Gli avvisi sopra le impostazioni ti segnalano quando è inserita solo una delle credenziali API, quando non ci sono credenziali API, quando non ci sono prezzi per paese e nessun costo di riserva, quando l'ultima richiesta all'API Budbee è fallita (con data, ora e motivo), e quando il negozio non ha una classe di peso con unità kg e l'unità della classe di peso predefinita non viene riconosciuta (in quel caso i pesi vengono trattati come kg; aggiungi una classe di peso kg in System > Localisation > Weight Classes).

Se Method name è vuoto o troppo lungo, Min weight (kg) è maggiore di Max weight (kg), Sort order non è un numero intero, oppure la classe fiscale o la zona geografica non esistono, non viene salvato nulla e compare un errore.

Generale

Enable/Disable: mostra o nasconde Instabee al checkout. Predefinito: off.

Method name: il nome del metodo di spedizione mostrato al cliente al checkout. Predefinito: Instabee parcel box. Obbligatorio, massimo 64 caratteri.

Tax class: None (the prices are final) (predefinito) significa che i prezzi qui sotto sono definitivi. Una classe fiscale aggiunge l'imposta di spedizione di quella classe ai prezzi qui sotto.

Sort order: la posizione di Instabee tra i metodi di spedizione al checkout. Un numero intero.

Selettore del box per pacchi (API Budbee)

Con le credenziali API il cliente sceglie al checkout un box per pacchi vicino al suo codice postale, e il box viene salvato sull'ordine. Servono entrambi i campi. Il selettore resta disattivato finché non sono impostati entrambi.

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

API secret: il tuo segreto API di 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 per modificarlo. Per eliminare le credenziali salvate, spunta Remove the saved API key and secret e salva. Quando non c'è nulla di salvato, la pagina mostra No credentials saved.

Test environment: usa l'API di staging di Budbee (api.staging.budbee.com). Attivala solo con le credenziali di staging fornite da Instabee. I negozi in produzione la lasciano disattivata (api.budbee.com). Predefinito: off.

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 sua valuta.

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. Clicca su Add country per aggiungere una riga e sul pulsante × per rimuoverne una. Scegli * Any other country per una riga che si applica a tutti i paesi senza una riga propria. Una fascia vuota o pari a 0 usa la colonna Price. Un Price pari a 0 significa consegna gratuita. Se la riga del paese non ha un prezzo per il peso del carrello, viene usata la riga *, poi il Fallback cost. Al salvataggio, un prezzo che non è un numero pari o superiore a 0 viene cancellato e una riga con un paese sconosciuto viene rimossa; un avviso le elenca. I pesi dei prodotti vengono convertiti dalla loro classe di peso di OpenCart in kg.

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

Condizioni

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

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

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

Free shipping from: il subtotale dei prodotti che richiedono spedizione (dopo il coupon, prima delle imposte) a partire dal quale il metodo è gratuito. Lascialo vuoto per non renderlo mai gratuito.

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

Disponibilità

Geo zone: offri Instabee solo per gli indirizzi in questa zona geografica. All zones (predefinito) significa ovunque. La zona geografica non viene verificata quando Ignore shipping zones è attivo. Le zone geografiche si gestiscono in System > Localisation > Geo Zones.

Ignore shipping zones: quando è attivo, la Geo zone non viene verificata e il metodo viene offerto per i paesi elencati qui sotto. Quando è disattivo (predefinito), si applica solo la Geo zone.

Countries: i paesi di destinazione per quella 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 storage/logs/vfd_ibee_debug.log.php (su OpenCart 4 system/storage/logs/vfd_ibee_debug.log.php). Il file non può essere letto dal web. Gli errori API e gli ordini effettuati senza box mentre l'API funzionava vengono sempre registrati, anche quando questa opzione è disattiva. Le chiavi API e i dati dei clienti non vengono mai registrati. Quando il file raggiunge 5 MB, viene spostato in vfd_ibee_debug.old.log.php e viene avviato un nuovo log.

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

Remove data on uninstall: quando è attivo, disinstallando l'estensione vengono eliminati le impostazioni, gli elenchi dei box in cache, il log e i box dei checkout non completati. Quando è disattivo (predefinito), le impostazioni vengono conservate per una reinstallazione. I box per pacchi salvati sugli ordini vengono sempre conservati.

Importa / Esporta

Export: clicca su Download JSON per salvare le impostazioni come file JSON. La chiave e il segreto API non vengono esportati.

Import: incolla un JSON esportato in precedenza e clicca su Import per ripristinare le impostazioni, ad esempio su un altro negozio. I valori vengono controllati come in un salvataggio normale. La chiave e il segreto API salvati vengono mantenuti.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di Instabee. Con Ignore shipping zones attivo, Instabee viene offerto solo quando il paese è consentito (la zona geografica non viene verificata). Altrimenti, se è impostata una Geo zone e l'indirizzo è al di fuori di essa, Instabee non viene offerto. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri prodotti non aggiungono peso e non sono inclusi nell'importo dell'ordine. L'importo dell'ordine è il prezzo dei prodotti che richiedono spedizione, dopo lo sconto del coupon e prima delle imposte. L'estensione verifica il peso del carrello e l'importo minimo dell'ordine. Se il subtotale 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 metodo viene nascosto. Il prezzo viene calcolato nella valuta predefinita del negozio, arrotondato alle sue cifre decimali e mostrato nella valuta del cliente con l'imposta della Tax class selezionata.

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

Il box per pacchi è obbligatorio. Il box scelto viene salvato per il checkout solo se è nell'elenco Budbee per quel codice postale. Un codice postale digitato senza cliccare su Search non viene usato. Quando il cliente clicca su Continue nel passaggio del metodo di consegna, l'estensione 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 codice postale dell'indirizzo, la scelta precedente viene eliminata.

Su OpenCart 4 il cliente clicca su Choose nel blocco del metodo di spedizione della pagina di checkout e sceglie Instabee nella finestra Shipping method options. Il blocco Parcel box compare in quella finestra, sotto l'opzione Instabee, e funziona allo stesso modo. Il pulsante Continue della finestra non procede senza un box dall'elenco, con gli stessi messaggi.

L'estensione invia a Budbee solo il paese di destinazione e il codice postale, mai nomi, indirizzi, e-mail o dati dell'ordine. Gli elenchi dei box sono memorizzati nella cache per 12 ore per codice postale, un codice postale 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 del checkout non attende mai Budbee: l'elenco viene caricato in background non appena il metodo è 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 quindi contrassegnato e tu scegli il box quando prenoti la spedizione. Un box scelto in precedenza che non può essere verificato in quel momento viene conservato e contrassegnato come non verificato.

L'estensione non calcola tariffe in tempo reale, non prenota spedizioni, non stampa etichette, non fornisce numeri di tracciamento o e-mail di tracciamento, non offre fasce orarie per la consegna Budbee Home e non mostra una mappa. Prenota il pacco per il box scelto negli strumenti per commercianti di Instabee / Budbee.

Punti di ritiro

Alla creazione dell'ordine il box viene verificato ancora una volta e salvato sull'ordine. Da quel momento il negozio non può modificarlo. Su OpenCart 4 un unico ordine viene usato per il checkout e aggiornato ogni volta che il cliente conferma di nuovo, e il box dell'ordine viene aggiornato insieme ad esso. Se il cliente passa quell'ordine a un altro metodo di spedizione, il suo box viene rimosso. Il box viene mostrato in questi punti:

Metodo di spedizione dell'ordine: il box viene aggiunto al nome del metodo, ad esempio Instabee parcel box: (il nome del metodo) seguito dal nome e dall'indirizzo del box. Questo testo compare nelle pagine degli ordini in amministrazione e nell'account del cliente, nelle e-mail dell'ordine e nella fattura.

Pagina ordine in amministrazione (Sales > Orders): un pannello Instabee parcel box con nome del box, indirizzo e Box ID. Se il box non è stato verificato 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 pannello riporta Not chosen - the Budbee API was unavailable at checkout. Choose the box when you book the shipment. Il pannello è di sola lettura e viene mostrato anche quando il metodo è disattivato. Su OpenCart 4 viene mostrato sopra History.

E-mail di nuovo ordine al negozio: il nome del box con il suo ID, oppure Instabee parcel box: not chosen (Budbee API unavailable at checkout).

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco della licenza License — VibeFox Instabee è il primo blocco della pagina Extensions > Extensions > Shipping > VibeFox Instabee > Edit, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (ad 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-instabee 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, ad esempio Key not found, This key belongs to another product, Domain limit reached o License expired on seguito da una data. Dopo che l'indirizzo del negozio cambia, o dopo che liberi 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. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, il metodo di spedizione Instabee non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Un amministratore che ha effettuato l'accesso all'amministrazione nello stesso browser continua a vedere il metodo nel negozio, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e provare 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 un rinnovo. Lo stato viene ricontrollato 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

Instabee non compare al checkout: verifica che la licenza sia attiva e che Enable/Disable sia attivo. Controlla Geo zone oppure, se Ignore shipping zones è attivo, che il paese sia consentito in Countries. Controlla che il paese abbia un prezzo, oppure che esista una riga * o un Fallback cost. Controlla i limiti di peso e Minimum order amount, e che i prodotti abbiano Requires Shipping impostato su Yes. Un avviso sopra le impostazioni ti segnala quando non è configurato alcun prezzo. Attiva Debug log per vedere il motivo nel campo Log.

I clienti non vedono l'elenco dei box per pacchi: l'elenco compare solo quando sono impostati sia API key sia API secret, per Svezia, Finlandia, Danimarca, Paesi Bassi o Belgio, e dopo aver inserito un codice postale. L'ultimo errore API viene mostrato sopra le impostazioni. I dettagli si trovano nel campo Log nella pagina dell'estensione. Attiva Debug log per maggiori dettagli.

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

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

Il cliente non può proseguire dal passaggio del metodo di consegna: bisogna scegliere un box dall'elenco, a meno che l'API Budbee non sia raggiungibile. Un box che non si trova nell'elenco del codice postale 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.

Elenchi di box obsoleti dopo una modifica: clicca su Save nella pagina dell'estensione. Questo svuota gli elenchi dei box in cache.

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

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox Instabee. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart reimposta sempre Enable/Disable, Sort order, Tax class e Geo zone. Gli elenchi dei box in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, vengono rimosse anche le impostazioni, il log e i box scelti nei checkout che non sono mai diventati ordini. Se è disattivo, le altre impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. I box per pacchi salvati sugli ordini vengono sempre conservati, e gli ordini esistenti mantengono il loro metodo di spedizione e il loro costo.

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

Instabee e Budbee sono marchi dei rispettivi proprietari. Questa estensione non è affiliata né approvata da Instabee o Budbee.