VibeFox Chilexpress 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.
Chiavi API Chilexpress (solo per tariffe in tempo reale): crea un account sul portale per sviluppatori di Chilexpress (developers.wschilexpress.com) e sottoscrivi due prodotti: Rating (Cotizador) e Coverage (Coberturas / Georreferencia). Ogni prodotto ha la propria chiave di sottoscrizione. Le chiavi di test funzionano solo con l'ambiente di test; le chiavi di produzione vengono rilasciate ai clienti business di Chilexpress con un contratto cliente. Ti serve anche il codice county Chilexpress della comuna da cui spedisci, per esempio STGO. Se usi solo prezzi fissi, non ti servono chiavi API.
Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un solo dominio.
Installazione
1. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e clicca su Install Now. Puoi anche caricare la cartella vfd_chilexpress in /wp-content/plugins/ via FTP.
2. Clicca su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox Chilexpress, oppure clicca 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 clicca su Activate.
5. Compila la tabella dei prezzi. Per le tariffe in tempo reale, inserisci entrambe le chiavi di sottoscrizione, il codice county di origine e, se la valuta del negozio non è CLP, il tasso di cambio CLP, quindi scegli la fonte delle tariffe (vedi Configurazione).
6. Aggiungi VibeFox Chilexpress a una zona di spedizione per il Cile in WooCommerce > Settings > Shipping > Shipping zones, oppure attiva Ignore shipping zones e scegli i paesi.
Configurazione
Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox Chilexpress. Valgono per tutte le zone di spedizione. Quando aggiungi il metodo a una zona, la finestra della zona ha un solo campo:
Title (zone): il nome di questa opzione di spedizione al checkout per questa zona. Lascialo vuoto per usare il Name globale.
La pagina delle impostazioni mostra in alto i problemi: sono selezionate tariffe API ma manca una chiave, il codice county di origine o il tasso di cambio CLP, oppure la tabella dei prezzi non ha una riga per il Cile o per * Default. Ogni volta che salvi le impostazioni, le tariffe e le liste delle comuna salvate in cache vengono cancellate. I numeri si possono digitare con il punto o con la virgola; un numero non valido non viene salvato e appare un errore.
Generali
Enable/Disable: attiva o disattiva la spedizione Chilexpress in tutte le zone contemporaneamente.
Name: il nome del metodo di spedizione mostrato al cliente al checkout. Default: Chilexpress.
Tax status: Taxable aggiunge l'imposta di WooCommerce al costo di spedizione (se le imposte sono attive), None non la aggiunge. Le tariffe API di Chilexpress sono usate esattamente come quotate. Scegli None se la quota include già l'IVA e il tuo negozio aggiungerebbe l'imposta sopra.
Tariffe
Rate source: da dove proviene il prezzo.
Le tariffe in tempo reale sono disponibili solo per destinazioni in Cile. Gli altri paesi usano sempre i prezzi fissi.
Country prices: una tabella dei paesi di destinazione con una colonna Price e prezzi opzionali per dimensione del pacco nella valuta del negozio. La dimensione deriva dal peso del carrello: XS fino a 1 kg, S fino a 2 kg, M fino a 3 kg, L fino a 5 kg, XL oltre 5 kg. Una dimensione lasciata a 0 usa Price. Clicca su + Add country per aggiungere una riga e sulla croce per rimuoverla. La riga * Default si applica ai paesi senza una riga propria. Un paese senza riga (e senza *) non ha un prezzo fisso. Una riga con prezzo e prezzo per dimensione entrambi a 0 dà la spedizione gratuita.
Calculation type: Per order addebita il prezzo fisso una sola volta. Per item (fixed price x number of items) lo moltiplica per il numero di articoli nel carrello. Una tariffa API di Chilexpress è sempre quotata per l'intero pacco.
API Chilexpress (tariffe in tempo reale)
Test environment: usa l'ambiente di test di Chilexpress (qaservices.wschilexpress.com). Usalo con chiavi di test e disattivalo in un negozio live.
Rating API key: la chiave di sottoscrizione del prodotto Rating (Cotizador).
Coverage API key: la chiave di sottoscrizione del prodotto Coverage (Coberturas / Georreferencia). Serve a trovare il codice county Chilexpress della comuna del cliente (il campo Città al checkout).
Origin county code: il codice county Chilexpress (comuna) da cui spedisci, 2–5 lettere, per esempio STGO (Santiago Centro), PROV (Providencia), LCON (Las Condes), VALP (Valparaíso) o CONC (Concepción). Un valore che non è un codice county viene rifiutato con un errore.
Service: il servizio Chilexpress usato per la tariffa. Se non è offerto per la destinazione, si usa il servizio più economico disponibile.
CLP exchange rate: Chilexpress quota in pesos cileni. Serve solo se la valuta del negozio non è CLP: il prezzo di 1 CLP nella valuta del negozio, per esempio 0.001. Senza di esso le tariffe API non vengono usate.
Disponibilità
Min weight (kg): il peso minimo del carrello perché il metodo appaia. 0 significa nessun limite.
Max weight (kg): il metodo viene nascosto sopra questo peso del carrello. Default: 25. 0 significa nessun limite.
Minimum subtotal: mostra il metodo solo se il subtotale del carrello (dopo gli sconti, senza imposte) è almeno questo importo. Lascia vuoto per mostrarlo sempre.
Excluded shipping classes: nasconde il metodo se un articolo del carrello appartiene a una di queste classi di spedizione di WooCommerce.
Ignore shipping zones: offre il metodo per i paesi indicati sotto anche senza averlo aggiunto a una zona di spedizione.
Countries: i paesi di destinazione per quella modalità. Lascia vuoto per usare tutti i paesi di spedizione del negozio. Questo campo viene usato solo quando Ignore shipping zones è attivo.
Spedizione gratuita
Free shipping: attiva la soglia di spedizione gratuita.
Free shipping from: il subtotale del carrello da cui la spedizione è gratuita. Usato solo quando Free shipping è attivo. In quel caso non viene fatta alcuna richiesta all'API.
Avanzate
Debug log: registra le richieste API e i calcoli delle tariffe in WooCommerce > Status > Logs, origine vfd-chilexpress. Gli errori API vengono sempre registrati, anche con questa opzione disattivata. Le chiavi API non vengono mai registrate.
Remove data on uninstall: se attivo, eliminando il plugin vengono rimosse le sue impostazioni e i metodi delle zone. La disattivazione non elimina mai le impostazioni. Le righe di spedizione degli ordini esistenti vengono sempre conservate.
Come funziona al checkout
Quando il cliente inserisce un indirizzo di consegna, WooCommerce chiede al plugin una tariffa. Il plugin controlla prima le condizioni: peso del carrello, subtotale minimo e classi di spedizione escluse. Se si applica la spedizione gratuita, il cliente riceve una tariffa gratuita e non viene inviata alcuna richiesta a Chilexpress.
Per un indirizzo in Cile e una fonte di tariffe API, il plugin prende la regione e la comuna dal campo Città e cerca il codice county Chilexpress nell'elenco delle comuna di quella regione (API Coverage). Accenti, spazi e varianti ortografiche vengono ignorati, quindi Ñuñoa e Nunoa corrispondono, e Santiago corrisponde a Santiago Centro. Viene accettato anche un codice county digitato nel campo Città. Poi il plugin invia all'API Rating i codici county di origine e destinazione, il peso del carrello (almeno 0,1 kg), le dimensioni del pacco (lunghezza e larghezza del prodotto più grande, altezze sommate) e il subtotale del carrello in CLP come valore dichiarato. Chilexpress restituisce i suoi servizi; il plugin usa il servizio scelto o il più economico e converte l'importo in pesos nella valuta del tuo negozio. Il nome del servizio viene salvato sulla riga di spedizione dell'ordine come Chilexpress service.
Le tariffe sono salvate in cache per 1 ora e le liste delle comuna per 7 giorni. Una richiesta non riuscita viene ricordata per 5 minuti, così un'API lenta o non disponibile non rallenta ogni aggiornamento del checkout. Il timeout dell'API è di 10 secondi. Se Chilexpress restituisce un errore, nessun servizio con prezzo o una comuna sconosciuta, il cliente non vede alcun errore. Il metodo viene nascosto nella modalità solo API, oppure si usa il prezzo fisso. Il motivo viene scritto nel log di WooCommerce.
Il metodo funziona con il checkout classico e con i blocchi Carrello e Checkout. È compatibile con l'archiviazione ad alte prestazioni degli ordini di WooCommerce (HPOS).
Il plugin calcola solo le tariffe. Non crea spedizioni o ordini di trasporto (OT), non stampa etichette, non prenota ritiri e non traccia i pacchi; prenota la spedizione nel tuo account Chilexpress. I clienti non possono scegliere un ufficio Chilexpress, e non c'è un selettore di comuna: il cliente digita la comuna nel campo Città standard. Le spedizioni internazionali usano i prezzi fissi.
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 Chilexpress. Incolla la chiave in License key e clicca 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 solo dominio. Rimuovere la chiave da un sito non libera il suo slot di dominio. Liberalo nel tuo account vibefox.net.
Senza una chiave attiva, Chilexpress non viene mostrato ai clienti al checkout. I gestori del negozio con accesso lo vedono ancora, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e testare 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 verificato di nuovo automaticamente in background.
Risoluzione dei problemi
Chilexpress non compare al checkout: controlla che la licenza sia attiva, che Enable/Disable sia attivo e che il metodo sia aggiunto alla zona del paese del cliente (oppure che Ignore shipping zones sia attivo e il paese consentito). Controlla i limiti di peso, Minimum subtotal e Excluded shipping classes. Con i prezzi fissi, verifica che il paese o * Default abbia una riga.
La tariffa in tempo reale non viene mostrata e si usa il prezzo fisso: controlla prima gli avvisi in cima alla pagina delle impostazioni. Altrimenti attiva Debug log, ricarica il checkout e apri WooCommerce > Status > Logs, origine vfd-chilexpress. Cause tipiche: una comuna che Chilexpress non riconosce (controlla il campo Città e la regione), una chiave per il prodotto o l'ambiente sbagliato, o una destinazione senza copertura Chilexpress.
HTTP 401 o 403 nel log: la chiave di sottoscrizione è errata, inattiva o riferita a un altro prodotto o ambiente. Le chiavi di test funzionano solo con Test environment attivo.
Le tariffe API non vengono usate in un negozio con un'altra valuta: inserisci il CLP exchange rate.
Le tariffe API includono l'IVA o no? Vengono usate esattamente come le quota Chilexpress. Se il tuo negozio aggiunge imposte alla spedizione e la quota include già l'IVA, imposta Tax status su None.
Le tariffe sembrano obsolete dopo una modifica: salva la pagina delle impostazioni. Questo cancella le tariffe e le liste delle comuna salvate in cache.
Il blocco licenza mostra un errore: segui il messaggio nel blocco. Ad esempio, se la chiave è già usata su un altro dominio, libera uno slot nel tuo account vibefox.net e clicca su Check now. Se l'indirizzo del sito è cambiato, clicca 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; cancella solo le tariffe e le liste delle comuna in cache. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin, insieme alle cache, vengono sempre rimossi. Impostazioni e metodi delle zone vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano per una successiva reinstallazione. Le righe di spedizione degli ordini esistenti vengono sempre conservate.
Chilexpress è un marchio registrato del suo rispettivo titolare. Questo plugin non è affiliato né approvato da Chilexpress.