VibeFox Chilexpress for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo, con l'estensione cURL per le tariffe in tempo reale. Il modulo non si installa su versioni di PHP più vecchie.

Chiavi API Chilexpress (solo per le 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 inoltre il codice county di Chilexpress della comuna da cui spedisci, per esempio STGO. Se usi solo prezzi fissi, non servono chiavi API.

Regioni cilene (solo per le tariffe in tempo reale): le tariffe in tempo reale richiedono la regione dell'indirizzo di consegna. PrestaShop non ha regioni cilene per impostazione predefinita; il modulo può aggiungerle per te (vedi Chilean regions più sotto). Il paese Chile deve esistere nel negozio.

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 clicca su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, clicca su Configure, oppure trova più tardi VibeFox Chilexpress nell'elenco dei moduli e clicca su Configure.

3. Inserisci la tua chiave di licenza VibeFox in License key nel blocco licenza in cima alla pagina Configure e clicca su Activate (vedi Chiave di licenza).

4. Compila la tabella Country prices. 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; clicca su Add Chilean regions se la pagina lo chiede; poi scegli la fonte delle tariffe (vedi Configurazione) e clicca su Save.

All'installazione il modulo crea il corriere Chilexpress con il testo dei tempi di consegna Chilexpress courier. Il corriere è collegato alla zona Chile e a tutti i gruppi di clienti. Puoi modificare zone, gruppi di clienti, tempi di consegna, logo e limiti di dimensione in Shipping > Carriers. Non impostare prezzi lì: il prezzo arriva sempre dal modulo. Per offrire Chilexpress in altre zone, aggiungile al corriere in quella pagina oppure attiva Ignore shipping zones.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Chilexpress > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella anche le tariffe Chilexpress e le liste delle comuna salvate in cache. Le modifiche richiedono il permesso "configure" per il modulo; senza di esso la pagina mostra You do not have permission to configure this module.

La pagina elenca in alto i problemi: sono selezionate tariffe API ma manca una chiave, il codice county di origine o il tasso di cambio CLP; la tabella dei prezzi non ha una riga per il Cile o per il valore predefinito; il negozio non ha regioni cilene o il modulo di indirizzo cileno non ha il campo regione; l'unità di peso o di dimensione del negozio non è riconosciuta dal modulo (viene quindi letta come kg o cm; impostala in International > Localization, Local units); il corriere è stato eliminato. I numeri si possono digitare con il punto o con la virgola, come nella lingua del tuo back office. Un numero non valido o negativo, un CLP exchange rate pari a 0, un Min weight (kg) superiore a Max weight (kg) o un Name più lungo di 64 caratteri sono errori, e non si salva nulla finché non li correggi.

Generali

Enable/Disable: attiva o disattiva la spedizione con Chilexpress. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.

Name: il nome del metodo di spedizione mostrato al cliente al checkout. È il nome del corriere. Predefinito: Chilexpress. Obbligatorio, fino a 64 caratteri.

Tax: la regola fiscale del corriere, oppure No tax (il valore predefinito per un nuovo corriere). Le tariffe API di Chilexpress vengono usate esattamente come quotate. Scegli No tax se la quotazione include già l'IVA e il negozio aggiungerebbe l'imposta sopra.

Tariffe

Rate source: da dove arriva 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 di paesi di destinazione con una colonna Price e prezzi opzionali per dimensione del pacco, nella valuta predefinita del negozio, IVA esclusa. 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 sull'icona del cestino per rimuoverne una. La riga * Default vale per i paesi senza una riga propria. Un paese senza riga (e senza * Default) non ha un prezzo fisso, quindi il corriere viene nascosto lì. Una riga il cui prezzo e i prezzi per dimensione sono tutti 0 dà la spedizione gratuita. Una tabella vuota viene mostrata con una riga per il Cile a 0; l'ultima riga non si può rimuovere, solo riportare a 0, quindi inserisci prezzi reali prima di salvare la pagina. Un paese ripetuto o un prezzo non valido viene corretto (il duplicato viene ignorato, il prezzo portato a 0) e un avviso elenca le correzioni.

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)

La sezione inizia con i collegamenti al portale per sviluppatori e alle pagine di sottoscrizione di Rating e Coverage.

Test environment: usa l'ambiente di test di Chilexpress (qaservices.wschilexpress.com). Usalo con chiavi di test e disattivalo su un negozio reale.

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 di Chilexpress della comuna del cliente (il campo City dell'indirizzo, insieme alla sua regione).

Dopo il salvataggio, il campo della chiave resta vuoto e mostra Saved — leave empty to keep it. Digita un valore nuovo solo se vuoi cambiarlo. La chiave viene salvata come l'hai digitata; vengono rimossi solo gli spazi attorno.

Remove the saved Rating API key e Remove the saved Coverage API key: si mostrano solo quando una chiave è salvata. Attiva l'opzione e clicca su Save per eliminare la chiave.

Origin county code: il codice county di Chilexpress (comuna) da cui spedisci, da 2 a 5 lettere, per esempio STGO (Santiago Centro), PROV (Providencia) o VALP (Valparaíso). Dopo l'installazione è vuoto. 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 predefinita del negozio non è CLP: il prezzo di 1 CLP in quella valuta, per esempio 0.001. Senza di esso le tariffe API non vengono usate. Se la valuta del negozio è CLP, lascialo vuoto. Il valore deve essere maggiore di 0.

Chilean regions: le comuna del Cile vengono cercate per regione, quindi le tariffe in tempo reale richiedono la regione dell'indirizzo. Se il negozio non ha regioni cilene, il campo mostra il pulsante Add Chilean regions. Aggiunge le 16 regioni come stati del Cile (codici ISO RM, VS…), attiva "Contains states" per il Cile e aggiunge il campo regione al modulo di indirizzo cileno. Le regioni già presenti (per codice o per nome) non vengono aggiunte due volte. Quando tutto è a posto, il campo mostra Chilean addresses have a region con il numero di regioni.

Disponibilità

Min weight (kg): il peso minimo del carrello perché il corriere compaia. 0 significa nessun limite.

Max weight (kg): il corriere viene nascosto sopra questo peso del carrello. Predefinito: 25. 0 significa nessun limite; un campo vuoto significa 25 kg. Min weight (kg) non può essere superiore a questo valore.

Minimum subtotal: mostra il corriere solo quando il subtotale del carrello (prodotti che richiedono spedizione, dopo gli sconti, IVA esclusa) è almeno questo importo. Lascialo vuoto per mostrarlo sempre.

Ignore shipping zones: offre il corriere per i paesi sotto anche se la loro zona non è collegata: il corriere viene collegato a tutte le zone, e anche le zone create in seguito vengono collegate. Quando lo disattivi, il corriere riprende le zone precedenti.

Countries: i paesi di destinazione per questa modalità, scelti tra i paesi attivi del negozio. Lascialo vuoto per consentire tutti i paesi. Questo campo viene usato solo se Ignore shipping zones è attivo.

Spedizione gratuita

Free shipping: attiva la soglia della spedizione gratuita.

Free shipping from: il subtotale del carrello (prodotti che richiedono spedizione, dopo gli sconti, IVA esclusa) da cui la spedizione è gratuita. Viene usato solo se Free shipping è attivo. In quel caso non viene fatta nessuna richiesta all'API.

Avanzate

Debug log: scrive le richieste API e i calcoli delle tariffe in logs/vfd_chx_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Gli errori dell'API vengono sempre registrati, anche con questa opzione disattivata. Le chiavi API e gli indirizzi dei clienti non vengono mai registrati.

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

Remove data on uninstall: se attivo, disinstallando il modulo vengono eliminate tutte le sue impostazioni, il corriere, le tariffe in cache, i log e i servizi salvati con gli ordini. Se disattivo, tutto viene conservato per una reinstallazione. Gli ordini stessi vengono sempre conservati.

Come funziona al checkout

Nella fase di spedizione PrestaShop chiede al modulo il prezzo Chilexpress. Contano solo i prodotti che richiedono spedizione: i prodotti virtuali non aggiungono peso e non rientrano nel subtotale. Il subtotale è calcolato dopo le regole del carrello (buoni), IVA esclusa, nella valuta predefinita del negozio. Il modulo controlla prima le condizioni: paesi consentiti (con Ignore shipping zones), peso del carrello e subtotale minimo. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata nessuna richiesta a Chilexpress.

Per un indirizzo in Cile e una fonte di tariffe API, il modulo prende la regione dell'indirizzo e la comuna dal campo City, e cerca il codice county di Chilexpress nell'elenco delle comuna di quella regione (Coverage API). 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 direttamente nel campo City. Poi il modulo invia alla Rating API i codici county di origine e di 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 modulo usa il servizio scelto o il più economico, e converte l'importo in pesos nella valuta predefinita del negozio. Il prezzo viene arrotondato alle cifre decimali di quella valuta e poi mostrato nella valuta del carrello del cliente.

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, oppure la comuna o la regione non sono riconosciute, il cliente non vede alcun errore. Nella modalità solo API il corriere viene nascosto, altrimenti si usa il prezzo fisso. Il motivo viene scritto nel log di debug.

Se modifichi il corriere in Shipping > Carriers dopo che ha degli ordini, PrestaShop lo salva come una nuova versione del corriere. Il modulo segue automaticamente la nuova versione.

Il modulo 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 standard City. Le spedizioni internazionali usano i prezzi fissi.

Ordini

Quando un ordine viene effettuato con il corriere Chilexpress, il modulo salva come è stato calcolato il suo prezzo. La pagina dell'ordine nel back office mostra un blocco Chilexpress con Chilexpress service (per una tariffa in tempo reale, il servizio quotato da Chilexpress, per esempio Express) e Price source: Live rate (Chilexpress Rating API), Fixed price o Free shipping.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Chilexpress è il primo blocco della pagina Modules > Module Manager > VibeFox Chilexpress > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopodiché 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 di essi ci sono la riga Product: presta-shipping-chilexpress 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 una modifica 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, 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, il corriere Chilexpress non viene mostrato ai clienti al checkout e non viene calcolata nessuna tariffa. Lo storefront di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il corriere è nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non testarlo al checkout. Un promemoria compare 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 ricontrollato 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 reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Chilexpress non compare al checkout: controlla che la licenza sia attiva e che Enable/Disable sia attivo. In Shipping > Carriers controlla che il corriere copra la zona del paese del cliente e il suo gruppo (oppure che Ignore shipping zones sia attivo e il paese sia in Countries). Controlla i limiti di peso e il Minimum subtotal. Con i prezzi fissi, controlla che il paese o * Default abbia una riga. I prodotti possono anche essere limitati a determinati corrieri nella pagina del prodotto.

La spedizione in Cile è gratuita ma non dovrebbe esserlo: la riga del Cile (o * Default) in Country prices ha 0 in Price e nelle colonne delle dimensioni. Inserisci i prezzi e clicca su Save.

La tariffa in tempo reale non viene mostrata, al suo posto si usa il prezzo fisso: controlla prima gli avvisi in cima alla pagina del modulo. Altrimenti attiva Debug log, ricarica il checkout e guarda il campo Log nella pagina del modulo. Cause tipiche: l'indirizzo non ha una regione o manca il campo regione (usa Add Chilean regions), una comuna che Chilexpress non riconosce (controlla il campo City e la regione), una chiave per il prodotto o l'ambiente sbagliato, oppure una destinazione senza copertura Chilexpress.

HTTP 401 o 403 nel log: la chiave di sottoscrizione è errata, inattiva, oppure è di 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 sono con o senza IVA? Vengono usate esattamente come le quota Chilexpress. Se il tuo negozio aggiunge imposta alla spedizione e la quotazione include già l'IVA, imposta Tax su No tax.

Le tariffe sembrano obsolete dopo una modifica: clicca su Save nella pagina del modulo. Questo cancella le tariffe in cache e le liste delle comuna.

La pagina dice "The Chilexpress carrier was not found": il corriere è stato eliminato in Shipping > Carriers. Reimposta il modulo in Modules > Module Manager per ricrearlo.

La pagina dice "The country Chile does not exist in this shop": aggiungi o attiva il Cile in International > Locations > Countries, poi usa Add Chilean regions.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Chilexpress e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. Le tariffe in cache e le liste delle comuna vengono sempre rimosse. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini conservano la loro cronologia) e vengono rimosse le impostazioni, il log e i servizi salvati con gli ordini. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni restano. Reinstallando il modulo viene ripristinato il corriere salvato con il suo stato precedente. Le regioni cilene aggiunte con Add Chilean regions restano nel negozio.

Chilexpress è un marchio del suo rispettivo proprietario. Questo modulo non è affiliato né approvato da Chilexpress.