VibeFox Blue Express 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 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.

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 dominio.

Installazione

1. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e fai clic su Install Now. Puoi anche caricare la cartella vfd_blue_express in /wp-content/plugins/ tramite FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox Blue Express, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugins.

4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.

5. Inserisci la chiave API, il servizio, il codice distretto di origine (per esempio SCL), il tasso di cambio CLP se la valuta del tuo negozio non è il CLP, e i prezzi fissi (per esempio CL=4500). Vedi Configurazione.

6. Vai su WooCommerce > Settings > Shipping > Shipping zones e aggiungi VibeFox Blue Express alla tua zona Cile. Nelle impostazioni del metodo scegli il titolo e il tipo di consegna (a domicilio o ritiro in un punto Blue Express). Aggiungilo due volte per offrire entrambe le opzioni.

Configurazione

Le impostazioni principali si trovano in WooCommerce > Settings > Shipping > VibeFox Blue Express. Si applicano a tutte le zone di spedizione. In cima alla pagina compaiono avvisi su impostazioni che nasconderebbero il metodo o la tariffa in tempo reale (nessuna chiave API, nessun tasso di cambio CLP, tabella dei prezzi fissi vuota). Salvare le impostazioni svuota la cache.

Finestra della zona (quando aggiungi il metodo a una zona di spedizione)

Title: il nome del metodo di spedizione mostrato al cliente per questa zona. Lascialo vuoto per usare il Name globale.

Delivery type: As in the global settings (predefinito), Home delivery oppure Pickup at a Blue Express point (PUDO). Aggiungi il metodo due volte a una zona per offrire consegna a domicilio e ritiro.

Generale

Enable/Disable: attiva o disattiva il metodo ovunque, in tutte le zone di spedizione.

Name: il nome del metodo di spedizione mostrato al checkout. Una zona può impostare un titolo proprio. Predefinito: Blue Express.

Tax status: i prezzi Blue Express includono l'IVA. Scegli None se WooCommerce non deve aggiungere tasse sopra, oppure Taxable se deve farlo.

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.

Service: il servizio Blue Express usato per la tariffa: Express (EX) (predefinito), Prioritario (PY) o 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). Se non sei sicuro, chiedilo a Blue Express.

CLP per 1 (your currency): i prezzi Blue Express sono in pesos cileni (CLP). Se il tuo negozio usa un'altra valuta, indica quanti CLP vale un'unità di quella valuta, per esempio 1050. Senza questo valore le tariffe in tempo reale non vengono usate. Viene ignorato se la valuta del negozio è il CLP.

Prezzo

Rate source: come viene calcolato il prezzo.

Fixed prices: una riga per paese nel formato COUNTRY_CODE=PRICE, nella valuta del tuo negozio, per esempio CL=4500 in un negozio in CLP o CL=4.50 in un negozio in EUR. Come separatore decimale sono accettati la virgola o il punto. Le righe non valide vengono segnalate al salvataggio. 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 riguarda sempre l'intera spedizione.

Condizioni

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

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

Minimum order subtotal: mostra il metodo solo a partire da questo subtotale del carrello (valuta del negozio). Lascia vuoto per mostrarlo sempre.

Excluded shipping classes: se un articolo del carrello appartiene a una classe di spedizione WooCommerce selezionata, il metodo viene nascosto.

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) a partire dal quale la spedizione è gratuita.

Ritiro nei punti Blue Express (PUDO)

Pickup point by default: se attivo, i metodi Blue Express consegnano in un punto Blue Express scelto dal cliente. È il valore predefinito per i metodi di zona con Delivery type = As in the global settings. Il cliente deve scegliere un punto per completare l'ordine.

Disponibilità senza zone di spedizione

Ignore shipping zones: offre il metodo anche quando non è aggiunto alla zona di spedizione corrispondente. Usa quindi le impostazioni globali (nessun titolo di zona né tipo di consegna).

Countries: i paesi di destinazione per questa modalità. Lascia vuoto per usare tutti i paesi verso cui spedisci. Usato solo con Ignore shipping zones.

Avanzate

Debug log: registra richieste e decisioni in WooCommerce > Status > Logs, origine "vfd-blue-express". Gli errori API vengono sempre registrati. La chiave API e gli indirizzi dei clienti non vengono mai registrati.

Remove data on uninstall: se attivo, eliminando il plugin vengono rimosse le sue impostazioni e i metodi di zona. La disattivazione non elimina mai le impostazioni. I punti di ritiro salvati negli ordini vengono mantenuti.

Come funziona al checkout

Quando il cliente inserisce un indirizzo di consegna, il plugin controlla il peso del carrello, il Minimum order subtotal e le Excluded shipping classes. Se si applica la spedizione gratuita, la tariffa è 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). Il plugin chiede prima a Blue Express di riconoscere il comune, poi richiede il prezzo per il servizio, il distretto di origine, la destinazione e i pacchi. Ogni prodotto viene inviato con peso e dimensioni convertiti in kg e cm. 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 del tuo negozio.

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 metodo viene nascosto oppure, in modalità di riserva, viene usato il prezzo fisso. Il motivo viene scritto nel log.

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

Il plugin 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 API di Blue Express oppure un prezzo fisso per paese. Le tariffe in tempo reale funzionano solo per il Cile.

Punti di ritiro

Con il tipo di consegna Pickup at a Blue Express point (PUDO), il cliente vede Choose pickup point sotto l'opzione Blue Express, sia nel checkout classico sia in quello a blocchi. 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. La tariffa viene poi ricalcolata con il prezzo di ritiro Blue Express (PUDO).

L'ordine non può essere completato senza un punto: il cliente vede Please choose a Blue Express pickup point. Questo controllo viene eseguito sul server.

Il punto scelto viene salvato nell'ordine con il codice agenzia Blue Express, il nome e l'indirizzo. Nella schermata ordine dell'amministrazione viene mostrato sotto l'indirizzo di spedizione come Blue Express pickup point. Fai clic su Edit per scegliere un altro punto sulla mappa Blue Express oppure per inserire a mano codice agenzia, nome e indirizzo, poi fai clic su Save pickup point. La modifica viene registrata in una nota dell'ordine. Il cliente vede il punto nella pagina dell'ordine e nelle email d'ordine (HTML e testo semplice). Le email inviate al negozio mostrano anche il codice agenzia. Gli ordini esistenti mantengono 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 cima a WooCommerce > Settings > Shipping > VibeFox Blue Express. Incolla la chiave in License key e fai clic 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 controllare 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 dominio. Rimuovere la chiave da un sito 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. I gestori del negozio che hanno effettuato l'accesso lo vedono ancora, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugins 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 ricontrollato automaticamente in background.

Risoluzione dei problemi

Blue Express non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che il metodo sia aggiunto alla zona dell'indirizzo del cliente (oppure che Ignore shipping zones sia attivo e il paese consentito). Leggi gli avvisi in cima alla pagina delle impostazioni. Controlla i limiti di peso, il Minimum order subtotal e le Excluded shipping classes, e che Fixed prices abbia una riga per il paese se usi i prezzi fissi o la riserva.

Le tariffe in tempo reale non compaiono: con Blue Express API only il metodo viene nascosto quando non c'è una tariffa. Attiva Debug log, ricarica il checkout e apri WooCommerce > Status > Logs (origine "vfd-blue-express"). Motivi tipici: nessuna chiave API, valuta del negozio diversa dal CLP senza tasso di cambio, regione o comune mancanti 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.

Viene aggiunta un'imposta sopra il prezzo Blue Express: i prezzi Blue Express includono l'IVA. Imposta Tax status su None se WooCommerce non deve aggiungere tasse sopra.

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

Blue Express è un marchio del suo rispettivo titolare. Questo plugin non è affiliato a Blue Express né da essa approvato.