VibeFox Blue Express 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 Blue Express (solo per tariffe in tempo reale): le tariffe in tempo reale richiedono un account e-commerce Blue Express e la sua chiave API (x-api-key). Richiedila a Blue Express: developers.bluex.cl o gpo.integraciones@bx.cl. Il servizio che usi (EX, PY o MD) deve essere attivo nel tuo contratto con Blue Express. Se usi solo prezzi fissi, non ti serve una chiave API.

Regioni cilene: per una tariffa in tempo reale, l'indirizzo di consegna deve avere una regione cilena. Se al tuo negozio mancano le regioni cilene, l'estensione può aggiungerle per te (vedi Configurazione).

Punti di ritiro: la mappa di Blue Express viene caricata da widget-pudo.blue.cl nel browser del cliente.

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 OpenCart 3 vfd_blue_express-oc3-(version).ocmod.zip e il pacchetto OpenCart 4 vfd_blue_express.ocmod.zip. Installa solo il pacchetto della 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_blue_express-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 Blue Express 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 la chiave API, il servizio, il codice distretto di partenza (per esempio SCL), il tasso di cambio CLP se la valuta del negozio non è CLP, e i prezzi fissi (per esempio CL=4500). Attiva Enable/Disable per la consegna a domicilio e Pickup point option se vuoi offrire il ritiro nei punti Blue Express. Clicca su Save. Vedi Configurazione.

OpenCart 4

1. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_blue_express.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 Blue Express, 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 ai passaggi 4 e 5 per OpenCart 3. La pagina delle impostazioni e i suoi campi sono uguali in entrambe le versioni.

All'installazione l'estensione crea una tabella per i punti di ritiro degli ordini. Il metodo resta disattivato finché non attivi la consegna a domicilio o l'opzione del punto di ritiro e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni Blue Express che hai conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox Blue Express > Edit. Le sezioni sono elencate a sinistra. Un unico pulsante Save salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella anche le tariffe Blue Express e i dati dei comuni memorizzati. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni. Le condizioni, i prezzi e la classe fiscale qui sotto si applicano a entrambe le opzioni.

I valori non validi vengono rifiutati con un errore e non viene salvato nulla: un nome vuoto o con i caratteri < > ; = # { }, un nome di oltre 64 caratteri, un numero negativo o non valido, un Min weight (kg) maggiore di Max weight (kg), un Sort order che non è un numero intero, o una classe fiscale o una zona geografica sconosciuta.

In cima alla pagina compaiono avvisi su impostazioni che nasconderebbero le opzioni o la tariffa in tempo reale: manca la chiave API, una valuta del negozio diversa da CLP senza tasso di cambio, una tabella di prezzi fissi vuota, nessuna zona per il Cile, e un negozio senza classe di peso in chilogrammi o classe di lunghezza in centimetri, la cui unità predefinita l'estensione non riconosce (i pesi vengono letti come kg e le dimensioni come cm).

Generale

Enable/Disable: attiva o disattiva la consegna a domicilio di Blue Express.

Name: il nome del metodo di spedizione mostrato al checkout per la consegna a domicilio. Predefinito: Blue Express. Obbligatorio, massimo 64 caratteri.

Tax class: la classe fiscale del costo di spedizione, oppure None (no tax on shipping) (predefinito). I prezzi Blue Express includono l'IVA. Scegli None se OpenCart non deve aggiungere tasse sopra. Vale per entrambe le opzioni.

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

Ritiro presso i punti Blue Express (PUDO)

Pickup point option: offre la consegna in un punto Blue Express scelto dal cliente, come seconda opzione accanto alla consegna a domicilio. Disattivata per impostazione predefinita.

Pickup point name: il nome del metodo di spedizione mostrato al checkout per il ritiro presso un punto Blue Express. Predefinito: Blue Express pickup point. Obbligatorio, massimo 64 caratteri.

API Blue Express (necessaria per le tariffe in tempo reale)

API key: la tua chiave API Blue Express (header x-api-key). Senza di essa vengono usati solo i prezzi fissi. Dopo il salvataggio il campo resta vuoto e mostra A key is saved - leave empty to keep it. Inserisci un nuovo valore solo se vuoi modificarla.

Remove the saved API key: attiva e salva per eliminare la chiave salvata.

Service: il servizio Blue Express usato per la tariffa: Express (EX) (predefinito), Prioritario (PY) oppure SameDay (MD). Deve essere attivo nel tuo contratto con Blue Express.

Origin district code: il codice distretto Blue Express del luogo da cui spedisci, per esempio SCL per Santiago (predefinito). Chiedi a Blue Express se non sei sicuro.

CLP per 1 (your currency): l'etichetta mostra la valuta predefinita del tuo negozio, per esempio CLP per 1 EUR. I prezzi Blue Express sono in pesos cileni (CLP). Inserisci quanti CLP vale un'unità della valuta predefinita del tuo negozio, per esempio 1050. Senza questo valore non vengono usate le tariffe in tempo reale. Viene ignorato se la valuta del negozio è CLP.

Prezzo

Rate source: come viene calcolato il prezzo. La tariffa in tempo reale richiede un indirizzo cileno con regione e comune (città). Gli errori vengono scritti nel log e non vengono mai mostrati al cliente.

Fixed prices: una riga per paese nel formato CODICE_PAESE=PREZZO, nella valuta predefinita del negozio, IVA esclusa, per esempio CL=4500 in un negozio in CLP o CL=4.50 in un negozio in EUR. Sono accettati la virgola o il punto come separatore decimale. Le righe non valide vengono ignorate ed elencate in un avviso al salvataggio. Un paese senza riga non ha un prezzo fisso, quindi le opzioni gli vengono nascoste quando serve il prezzo fisso. I prezzi fissi possono essere usati per qualsiasi paese.

Fixed price per: Order (predefinito) addebita il prezzo una volta. Item (price x quantity) lo moltiplica per il numero di articoli nel carrello. Questo vale solo per il prezzo fisso. La tariffa API è sempre per la spedizione completa.

Condizioni

Min weight (kg): nasconde il metodo quando il carrello pesa meno. 0 significa nessun limite (predefinito).

Max weight (kg): nasconde il metodo quando il carrello pesa di più. Predefinito: 100. 0 significa nessun limite; un campo vuoto significa 100 kg.

Minimum order subtotal: mostra il metodo solo a partire da questo subtotale del carrello (valuta del negozio, prodotti da spedire, dopo il coupon, IVA esclusa). Lascialo vuoto per mostrarlo sempre.

Spedizione gratuita

Free shipping: attiva la spedizione gratuita da un subtotale del carrello.

Free from subtotal: il subtotale del carrello (valuta del negozio, prodotti da spedire, dopo il coupon, IVA esclusa) da cui la spedizione è gratuita. In quel caso non viene inviata alcuna richiesta a Blue Express. Usato solo quando Free shipping è attivo.

Disponibilità

Geo zone: offre Blue Express solo per gli indirizzi di questa zona geografica. All zones (predefinito) significa nessun limite. Le zone geografiche si gestiscono in System > Localisation > Geo Zones. Non viene controllata con Ignore shipping zones.

Ignore shipping zones: offre entrambe le opzioni in ogni zona geografica. I paesi vengono poi limitati dall'elenco qui sotto.

Countries: i paesi di destinazione per questa modalità. Lascialo vuoto per consentire tutti i paesi. Usato solo con Ignore shipping zones.

Regioni cilene (mostrato solo quando nel negozio mancano regioni cilene)

Blue Express richiede la regione di un indirizzo cileno (RM, VS, ecc.) per la tariffa in tempo reale. La regione viene presa dalla zona dell'indirizzo, dal suo codice o dal suo nome. La sezione mostra quante zone ha il Cile nel tuo negozio e quali regioni mancano (un negozio OpenCart 3.0.5 standard ne ha 15 su 16, senza Ñuble). Clicca su Add Chilean regions per aggiungere le regioni mancanti come zone del Cile, con i codici usati da Blue Express. Le regioni che hai già, per codice o per nome, non vengono aggiunte due volte. Non viene cambiato nulla finché non clicchi sul pulsante. Puoi anche aggiungerle tu in System > Localisation > Zones.

Avanzate

Debug log: registra richieste e decisioni in storage/logs/vfd_blex_debug.log.php. Il file non può essere letto dal web. Gli errori dell'API vengono sempre registrati. La chiave API e gli indirizzi dei clienti non vengono mai registrati. Disattiva il log quando hai finito. Il log viene ruotato quando raggiunge 5 MB.

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, tariffe memorizzate e log. Se disattivo (predefinito), vengono conservati per una reinstallazione. 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 di ogni opzione attiva. Se è impostata una Geo zone (e Ignore shipping zones è disattivato) e l'indirizzo ne è fuori, Blue Express non viene offerto. Con Ignore shipping zones decide l'elenco Countries. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non rientrano nel subtotale. L'estensione verifica il peso del carrello e il Minimum order subtotal. Il subtotale è il prezzo dei prodotti da spedire, dopo lo sconto del coupon e prima delle imposte. Buoni regalo, punti fedeltà e credito del negozio non vengono considerati. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata alcuna richiesta a Blue Express.

Per una tariffa in tempo reale l'indirizzo deve trovarsi in Cile, con regione e città (comune). L'estensione chiede prima a Blue Express di riconoscere il comune, poi richiede il prezzo per il servizio, il distretto di partenza, la destinazione e i pacchi. Ogni prodotto viene inviato con peso e dimensioni convertiti in kg e cm dalle sue classi di peso e lunghezza. I prodotti senza peso o dimensioni vengono inviati come 0,01 kg, 10 x 10 x 10 cm. Il valore dichiarato viene inviato in CLP. Il prezzo in CLP viene convertito nella valuta predefinita del negozio, arrotondato alle sue decimali e mostrato al cliente nella sua valuta con l'imposta della Tax class selezionata.

Le tariffe vengono memorizzate per 1 ora e i dati dei comuni fino a 12 ore, ma non più a lungo della durata della cache di OpenCart (1 ora per impostazione predefinita). Una chiamata API non riuscita viene ricordata per 5 minuti, e il timeout è di 10 secondi, così un'API lenta o non disponibile non rallenta ogni aggiornamento del checkout. Gli errori dell'API non vengono mai mostrati al cliente: l'opzione viene nascosta, oppure in modalità di riserva si usa il prezzo fisso. Il motivo viene scritto nel log.

L'estensione non crea spedizioni o etichette in Blue Express, non assegna numeri di tracciamento e non mostra aggiornamenti di tracciamento. Crea la spedizione nel tuo account Blue Express. Non ci sono tabelle tariffarie regionali per comune: usa la tariffa API di Blue Express o un prezzo fisso per paese. Le tariffe in tempo reale funzionano solo per il Cile.

Su OpenCart 4 il cliente clicca su Choose nel blocco dei metodi di spedizione della pagina di checkout e sceglie Blue Express o Blue Express pickup point nella finestra Shipping method options. Le opzioni funzionano come su OpenCart 3; il riquadro del punto di ritiro è descritto in Punti di ritiro.

Punti di ritiro

Quando l'opzione punto di ritiro è attiva, sotto Blue Express pickup point compare nel passaggio Delivery Method del checkout di OpenCart un riquadro con il pulsante Choose pickup point. Il pulsante apre la mappa ufficiale di Blue Express, dove il cliente sceglie un punto. Il punto scelto viene mostrato con nome e indirizzo, e il pulsante diventa Change pickup point. Il punto viene salvato per la sessione di checkout e la tariffa viene ricalcolata con il prezzo di ritiro (PUDO) di Blue Express. Se il prezzo cambia, l'opzione mostra il nuovo prezzo. Se l'opzione non è più offerta per quel punto, il passaggio di spedizione si ricarica. Finché non viene scelto un punto, l'opzione mostra il prezzo della consegna a domicilio.

Il cliente non può proseguire senza un punto: Continue nel passaggio di spedizione viene rifiutato con Please choose a Blue Express pickup point. Questo viene verificato nel browser e poi di nuovo dal negozio. Un codice punto non valido viene rifiutato con The selected Blue Express pickup point is not valid. Please choose it again on the map., e la scelta precedente resta. Se il salvataggio non riesce, il cliente vede The pickup point could not be saved. Please try again.

Su OpenCart 4 il cliente clicca su Choose nel blocco dei metodi di spedizione del checkout. La finestra Shipping method options mostra lo stesso riquadro con Choose pickup point sotto Blue Express pickup point mentre quell'opzione è selezionata. Quando il prezzo cambia con il punto scelto, l'opzione nella finestra mostra il nuovo prezzo, e se l'opzione di ritiro era già salvata per il checkout, anche il campo del metodo di spedizione e il blocco di conferma dell'ordine vengono aggiornati. Se l'opzione non è più offerta per quel punto, la finestra si chiude e l'elenco dei metodi di spedizione viene ricaricato. Continue nella finestra senza punto viene bloccato con Please choose a Blue Express pickup point. nel riquadro, e il negozio lo verifica di nuovo. OpenCart 4 conserva un solo ordine per il checkout e lo aggiorna a ogni conferma; il punto di ritiro dell'ordine viene aggiornato insieme e viene rimosso quando l'ordine passa a un altro metodo di spedizione.

Quando l'ordine viene effettuato, il punto viene salvato nell'ordine con il suo codice agenzia Blue Express, nome, indirizzo e regione. Viene inoltre aggiunto al metodo di spedizione dell'ordine dopo il nome dell'opzione di ritiro, per esempio Blue Express pickup point: Blue Point Providencia, Av. Providencia 1234, così il cliente lo vede nelle e-mail d'ordine e nelle pagine ordine del proprio account.

Nella pagina ordine dell'amministratore (Sales > Orders, View) il punto viene mostrato nel riquadro Blue Express pickup point con il suo codice e la sua regione. Se l'ordine non ha un punto, il riquadro mostra Not chosen. Clicca su Edit per scegliere un altro punto con Choose on the Blue Express map oppure per inserire a mano Agency code, Name e Address, poi clicca su Save pickup point. Anche il testo del metodo di spedizione dell'ordine viene aggiornato, e la modifica viene aggiunta alla cronologia dell'ordine senza avvisare il cliente (Blue Express pickup point changed: vecchio codice -> nuovo codice). Cambiare il punto richiede solo il permesso di modifica degli ordini, non l'accesso alle impostazioni dell'estensione. Gli ordini esistenti conservano i dati del punto di ritiro.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza License — VibeFox Blue Express è il primo blocco di Extensions > Extensions > Shipping > VibeFox Blue Express > Edit, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopo di che 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: opencart-shipping-blue-express e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo gli utenti amministratori con il permesso di modifica 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 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, l'estensione continua a funzionare con l'ultimo stato noto.

Una chiave funziona su un dominio: l'indirizzo del negozio dalla 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, Blue Express non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Un utente amministratore connesso all'amministrazione nello stesso browser vede comunque il metodo nel negozio, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e provare l'estensione prima di acquistare una chiave. 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 un cron job. La disinstallazione dell'estensione rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Blue Express non compare al checkout: verifica che la licenza sia attiva e che Enable/Disable (o Pickup point option) sia attivo. Leggi gli avvisi in cima alla pagina dell'estensione. Controlla Geo zone (o Ignore shipping zones e Countries), i limiti di peso, il Minimum order subtotal, e che Fixed prices abbia una riga per il paese se usi i prezzi fissi o la riserva. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.

Le tariffe in tempo reale non compaiono: con Blue Express API only le opzioni vengono nascoste quando non c'è una tariffa. Attiva Debug log, ricarica il checkout e guarda il campo Log nella pagina dell'estensione. Motivi comuni: nessuna chiave API, valuta del negozio non CLP senza tasso di cambio, regione o comune mancante nell'indirizzo, comune non riconosciuto da Blue Express, o un errore dell'API (per esempio HTTP 401 o 403 quando la chiave API viene rifiutata). Con Blue Express API, fixed price if the API gives no rate i clienti ricevono comunque il prezzo fisso mentre risolvi il problema.

Gli indirizzi cileni non hanno una regione: la pagina mostra un avviso sulle regioni mancanti. Clicca su Add Chilean regions nella pagina dell'estensione. I clienti i cui indirizzi sono stati salvati senza regione devono modificare l'indirizzo e scegliere la regione.

Sul prezzo Blue Express si aggiunge la tassa: i prezzi Blue Express includono l'IVA. Imposta Tax class su None (no tax on shipping).

La mappa non si apre: la mappa viene caricata da widget-pudo.blue.cl nel browser del cliente, quindi questo indirizzo deve essere raggiungibile e non bloccato sul tuo sito.

Le tariffe sembrano non aggiornate dopo una modifica: clicca su Save nella pagina dell'estensione. Questo cancella le tariffe e i dati dei comuni memorizzati.

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

Per sviluppatori: gli indirizzi dell'API e della mappa di Blue Express possono essere sostituiti con le impostazioni vfd_blex_api_url e vfd_blex_widget_url (per i test); non hanno campi nella pagina delle impostazioni.

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox Blue Express. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre eliminati. OpenCart ripristina sempre lo stato del metodo, Sort order, Tax class e Geo zone. Le tariffe memorizzate vengono sempre rimosse. Se Remove data on uninstall è attivo, vengono eliminati anche le impostazioni Blue Express e il log. Se è disattivo, le altre impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. I punti di ritiro salvati negli ordini non vengono mai rimossi, e il testo del metodo di spedizione degli ordini esistenti mantiene il punto di ritiro.

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

Blue Express è un marchio del rispettivo titolare. Questa estensione non è affiliata né approvata da Blue Express.