VibeFox Blue Express 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 Blue Express (solo per le tariffe in tempo reale): le tariffe in tempo reale richiedono un account e-commerce Blue Express e la relativa 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 abilitato nel tuo contratto 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 il tuo negozio non ha regioni per il Cile, il modulo può aggiungerle per te (vedi Configurazione).
Punti di ritiro: la mappa 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 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 più tardi VibeFox Blue Express nell'elenco dei moduli e fai clic su Configure.
3. Incolla la tua chiave di licenza VibeFox in License key nel blocco licenza in cima alla pagina Configure e fai clic su Activate (vedi Chiave di licenza).
4. Inserisci la chiave API, il servizio, il codice del distretto di origine (per esempio SCL), il tasso di cambio CLP se la valuta del tuo negozio non è CLP e i prezzi fissi (per esempio CL=4500). Attiva Pickup point carrier se vuoi offrire il ritiro nei punti Blue Express. Fai clic su Save. Vedi Configurazione.
All'installazione il modulo crea due corrieri: Blue Express (consegna a domicilio, testo del tempo di consegna Home delivery, attivo) e Blue Express pickup point (testo del tempo di consegna Pickup at a Blue Express point, disattivato finché non lo attivi). Entrambi sono assegnati alla zona Cile e a tutti i gruppi di clienti. Puoi modificare zone, gruppi di clienti, tempo 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 Blue Express > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella anche le tariffe Blue Express e i dati dei comuni in cache. In cima alla pagina compaiono avvisi su impostazioni che nasconderebbero i corrieri o la tariffa in tempo reale: nessuna chiave API, valuta del negozio diversa da CLP senza tasso di cambio, tabella dei prezzi fissi vuota, nessuna regione per il Cile, un'unità di peso o di dimensione del negozio che il modulo non riconosce (i pesi vengono letti come kg e le dimensioni come cm), oppure un corriere eliminato. I valori non validi vengono rifiutati con un errore e non viene salvato nulla: un nome di corriere vuoto o non valido, un nome più lungo di 64 caratteri, un numero negativo o non valido, oppure Min weight (kg) maggiore di Max weight (kg). Le condizioni e i prezzi qui sotto valgono per entrambi i corrieri.
Generale
Enable/Disable: attiva o disattiva il corriere per la consegna a domicilio. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.
Name: il nome del corriere mostrato al checkout per la consegna a domicilio. Predefinito: Blue Express. Obbligatorio, massimo 64 caratteri.
Tax status: None (no tax on shipping) oppure Taxable con una delle tue regole fiscali. I prezzi Blue Express includono IVA. Scegli None se PrestaShop non deve aggiungere tasse sopra. Vale per entrambi i corrieri.
Ritiro nei punti Blue Express (PUDO)
Pickup point carrier: offre la consegna in un punto Blue Express scelto dal cliente, come secondo corriere accanto alla consegna a domicilio. Disattivato per impostazione predefinita. È lo stesso interruttore dello stato del corriere Blue Express pickup point in Shipping > Carriers.
Pickup point name: il nome del corriere mostrato al checkout per il ritiro in 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 cambiarla. Seleziona Remove the saved API key e salva per eliminarla.
Service: il servizio Blue Express usato per la tariffa: Express (EX) (predefinito), Prioritario (PY) oppure SameDay (MD). Deve essere abilitato nel tuo contratto 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 unit of store currency: quando la valuta predefinita del tuo negozio non è CLP, l'etichetta la mostra, 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 COUNTRY_CODE=PRICE, nella valuta predefinita del tuo negozio, IVA esclusa, per esempio CL=4500 in un negozio in CLP oppure CL=4.50 in un negozio in EUR. Come separatore decimale sono accettati la virgola o il punto. Le righe non valide vengono ignorate ed elencate in un avviso quando salvi. Un paese senza riga non ha prezzo fisso, quindi i corrieri vengono nascosti per quel paese quando serve il prezzo fisso. I prezzi fissi possono essere usati per qualsiasi paese.
Fixed price per: Order addebita il prezzo una sola 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 intera.
Condizioni
Min weight (kg): nasconde i corrieri quando il carrello pesa meno. 0 significa nessun limite.
Max weight (kg): nasconde i corrieri quando il carrello pesa di più. Predefinito: 100. 0 significa nessun limite, un campo vuoto significa 100 kg. Min weight (kg) non può essere maggiore di Max weight (kg).
Minimum order subtotal: mostra i corrieri solo a partire da questo subtotale del carrello (valuta del negozio, dopo gli sconti, IVA esclusa). Lascia vuoto per mostrarli sempre.
Spedizione gratuita
Free shipping: attiva la spedizione gratuita a partire da un subtotale del carrello.
Free from subtotal: il subtotale del carrello (valuta del negozio, dopo gli sconti, IVA esclusa) a partire dal quale la spedizione è gratuita. Viene usato solo quando Free shipping è attivo.
Disponibilità senza zone di spedizione
Ignore shipping zones: offre entrambi i corrieri in ogni zona. I paesi vengono quindi limitati dall'elenco sotto. Vengono aggiunte anche le zone create in seguito. Quando lo disattivi di nuovo, i corrieri riprendono le zone che avevano prima.
Countries: i paesi di destinazione per questa modalità. Lascia vuoto per usare tutti i paesi in cui spedisci. Viene usato solo con Ignore shipping zones.
Avanzate
Debug log: registra richieste e decisioni in logs/vfd_blex_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori API vengono sempre registrati. La chiave API e gli indirizzi dei clienti non vengono mai registrati. Disattiva il log quando hai finito.
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 i corrieri. I punti di ritiro salvati negli ordini vengono conservati.
Regioni cilene (mostrato solo quando il tuo negozio non ha regioni cilene utilizzabili)
Blue Express richiede la regione di un indirizzo cileno (RM, VS e così via) per la tariffa in tempo reale. PrestaShop non include di default le regioni cilene. Fai clic su Add Chilean regions per aggiungere le 16 regioni cilene come stati del Cile, con i codici usati da Blue Express, e per mostrare il campo regione nel modulo degli indirizzi cileni. Le regioni che hai già, per codice o per nome, non vengono aggiunte due volte. Non viene cambiato nulla finché non fai clic sul pulsante. Puoi anche aggiungerle tu in International > Locations > States con i codici RM, VS e così via.
Come funziona al checkout
Nel passaggio di spedizione PrestaShop chiede al modulo il prezzo di ciascun corriere Blue Express. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nel subtotale. Il modulo controlla Countries (con Ignore shipping zones), il peso del carrello e il Minimum order subtotal. 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 una regione e una città (comune). Il modulo chiede prima a Blue Express di riconoscere il comune, poi richiede il prezzo per il servizio, il distretto di origine, la destinazione e i colli. Ogni prodotto viene inviato con peso e dimensioni convertiti in kg e cm. I prodotti senza peso o dimensione 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 tuo negozio e poi mostrato nella valuta del carrello del cliente.
Le tariffe sono memorizzate nella cache per 1 ora e i dati dei comuni per 12 ore. 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 API non vengono mai mostrati al cliente: il corriere viene nascosto oppure, nella modalità con prezzo fisso di riserva, viene usato il prezzo fisso. Il motivo viene scritto nel log.
Se modifichi un 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 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 esistono tabelle tariffarie regionali per comune: usa la tariffa dell'API Blue Express oppure un prezzo fisso per paese. Le tariffe in tempo reale funzionano solo per il Cile.
Punti di ritiro
Quando il cliente seleziona Blue Express pickup point nel passaggio di consegna, compare sotto 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 nel carrello e la tariffa viene ricalcolata con il prezzo di ritiro Blue Express (PUDO). Se il prezzo cambia, la pagina si ricarica per mostrarlo. Finché non viene scelto un punto, il corriere mostra il prezzo della consegna a domicilio.
Il cliente non può proseguire senza un punto: Please choose a Blue Express pickup point. Il negozio lo verifica quando il cliente fa clic su Continue nel passaggio di consegna. Un codice di punto malformato viene rifiutato con The selected Blue Express pickup point is not valid. Please choose it again on the map., e la scelta precedente resta invariata.
Quando l'ordine viene effettuato, il punto viene salvato nell'ordine con il suo codice agenzia Blue Express, il nome e l'indirizzo. Nella pagina ordine dell'amministrazione viene mostrato nel blocco Blue Express pickup point. Fai clic 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 fai clic su Save pickup point. La modifica viene registrata come messaggio privato dell'ordine. Per cambiare il punto servono solo i permessi di modifica degli ordini, non l'accesso alle pagine Moduli. Il cliente vede il punto nella pagina di conferma dell'ordine, nella pagina di dettaglio dell'ordine e nell'email di conferma dell'ordine, accanto al nome del corriere. La nuova email d'ordine per il negozio (dal modulo Mail alerts) mostra anch'essa il codice agenzia. Gli ordini esistenti mantengono i dati del loro punto di ritiro.
Chiave di licenza
Il modulo funziona con una chiave di licenza VibeFox acquistata su vibefox.net. Il blocco licenza License — VibeFox Blue Express è il primo blocco di Modules > Module Manager > VibeFox Blue Express > Configure, sopra le impostazioni. Incolla la chiave in License key e fai clic 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-blue-express 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, 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 slot di dominio. Libera lo slot nel tuo account vibefox.net.
Senza una chiave attiva, i corrieri Blue Express non vengono mostrati 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 i corrieri vengono nascosti 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
Blue Express non compare al checkout: verifica che la licenza sia attiva e che Enable/Disable (o Pickup point carrier) sia attivo. In Shipping > Carriers verifica che il corriere copra la zona del paese del cliente e il gruppo del cliente, oppure attiva Ignore shipping zones e controlla Countries. Leggi gli avvisi in cima alla pagina del modulo. Controlla i limiti di peso, il Minimum order subtotal e che Fixed prices abbia una riga per il paese se usi i prezzi fissi o il ripiego. I prodotti possono anche essere limitati a determinati corrieri nella pagina del prodotto.
Le tariffe in tempo reale non compaiono: con Blue Express API only i corrieri vengono nascosti quando non c'è una tariffa. Attiva Debug log, ricarica il checkout e guarda il campo Log nella pagina del modulo. Cause tipiche: nessuna chiave API, valuta del negozio diversa da CLP senza tasso di cambio, regione o comune mancante nell'indirizzo, comune non riconosciuto da Blue Express oppure errore 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. Fai clic su Add Chilean regions nella pagina del modulo. I clienti i cui indirizzi sono stati salvati senza regione devono modificare l'indirizzo e scegliere la regione.
Sopra la tariffa Blue Express viene aggiunta un'imposta: i prezzi Blue Express includono IVA. Imposta Tax status 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 obsolete dopo una modifica: fai clic su Save nella pagina del modulo. Questo cancella le tariffe e i dati dei comuni in cache.
La pagina indica che manca un corriere Blue Express: il corriere è stato eliminato in Shipping > Carriers. Reimposta il modulo in Modules > Module Manager per ricrearlo. Il ripristino mantiene le tue impostazioni e lo stato dei corrieri.
Disinstallazione
Vai su Modules > Module Manager, apri il menu accanto a VibeFox Blue Express e scegli Uninstall. La chiave di licenza, lo stato della licenza e le tariffe in cache vengono sempre rimosse. Se Remove data on uninstall è attivo, entrambi i corrieri vengono eliminati (gli ordini mantengono la cronologia), e vengono rimosse le impostazioni, il log e i punti di ritiro non collegati a un ordine. Se è disattivo, i corrieri vengono solo disattivati e tutte le impostazioni vengono mantenute. Reinstallare il modulo ripristina i corrieri con lo stato che avevano prima. I punti di ritiro salvati negli ordini non vengono mai rimossi.
Blue Express è un marchio registrato del suo rispettivo titolare. Questo modulo non è affiliato a Blue Express né approvato da Blue Express.