VibeFox Chilexpress for OpenCart — Guida

Requisiti

OpenCart: 3.0.x (testato su 3.0.5.0) o 4.0.2 e successive (testato su 4.1.0.3).

PHP: 8.0 o successivo.

Chiavi API Chilexpress (solo per le tariffe in tempo reale): crea un account sul portale per sviluppatori di Chilexpress (developers.wschilexpress.com) e abbonati a due prodotti: Rating (Cotizador) e Coverage (Coberturas / Georreferencia). Ogni prodotto ha la propria chiave di abbonamento. 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. Ti serve anche il codice county di Chilexpress del 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 (zona) dell'indirizzo di consegna. OpenCart 3.0.5.0 include 15 delle 16 regioni cilene; l'estensione può aggiungere quelle mancanti (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

Il download è un unico file zip con i pacchetti per entrambe le versioni di OpenCart. Decomprimilo sul tuo computer. Contiene README.txt, il pacchetto per OpenCart 3 vfd_chilexpress-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_chilexpress.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_chilexpress-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 principale del negozio.

2. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox Chilexpress 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 alto nella pagina Edit, e clicca su Activate (vedi Chiave di licenza).

5. Compila la tabella Country prices. Per le tariffe in tempo reale, inserisci entrambe le chiavi di abbonamento, il codice county di origine e, se la valuta del negozio non è CLP, il tasso di cambio in CLP; clicca su Add Chilean regions se la pagina mostra regioni mancanti, poi scegli la fonte delle tariffe (vedi Configurazione). Attiva Enable/Disable e clicca su Save.

OpenCart 4

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

Dopo l'installazione il metodo è disattivato finché non attivi Enable/Disable e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni Chilexpress che hai conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox Chilexpress > Edit. Le sezioni sono elencate a sinistra. Un solo pulsante Save in fondo salva l'intera pagina senza ricaricarla. Dopo il salvataggio vedi Settings saved. Cached Chilexpress rates and comuna lists were cleared. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni, svuotare il registro o aggiungere regioni.

La pagina mostra in alto i problemi: sono selezionate le tariffe API ma la chiave Rating API è vuota; la chiave Coverage API è vuota; il codice county di origine è vuoto o non valido; la valuta del negozio non è CLP e non è impostato un tasso di cambio CLP; Country prices non ha una riga per il Cile o per il predefinito; il Cile non ha zone nel negozio; l'unità di peso o di lunghezza del negozio non è riconosciuta dall'estensione (i pesi vengono letti come kg e le dimensioni come cm; usa kg, g, lb o oz e cm, mm, m o in in System > Localisation). I numeri si possono digitare con il punto o con la virgola. Non viene salvato nulla e la pagina elenca gli errori se Name è vuoto, contiene uno dei caratteri < > ; = # { } o supera 64 caratteri, se un numero non è valido o è negativo, se CLP exchange rate è 0, se Min weight (kg) è maggiore di Max weight (kg), se Origin county code non è un codice county, o se Sort order non è un numero intero.

Generale

Un unico metodo di spedizione "Chilexpress" per ogni zona geografica, o per la zona geografica selezionata in Disponibilità.

Enable/Disable: mostra o nasconde Chilexpress al checkout. Predefinito: disattivato.

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

Tax class: la classe fiscale del costo di spedizione, oppure No tax (predefinito). Le tariffe API di Chilexpress vengono usate esattamente come quotate. Scegli No tax se la quota include già l'IVA e il negozio aggiungerebbe un'imposta sopra.

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

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: un elenco di paesi di destinazione con una colonna Price e prezzi facoltativi per dimensione del pacco, nella valuta predefinita del negozio, IVA esclusa. La dimensione dipende 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. La riga * Default (other countries) si applica ai paesi senza una riga propria. Un paese senza riga (e senza la riga predefinita) non ha un prezzo fisso, quindi il metodo viene nascosto. Una riga salvata il cui prezzo e i prezzi per dimensione sono tutti 0 dà la spedizione gratuita. Una tabella vuota mostra una riga per il Cile a 0, quindi inserisci prezzi reali prima di salvare la pagina. Un paese duplicato o un prezzo non valido vengono corretti (il duplicato viene ignorato, il prezzo portato a 0) e un avviso elenca le correzioni.

Calculation type: Per order (predefinito) 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 il pacco intero.

API Chilexpress (tariffe in tempo reale)

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

Test environment: usa l'ambiente di test di Chilexpress (qaservices.wschilexpress.com). Usalo con chiavi di test e disattivalo in un negozio live. Predefinito: disattivato.

Rating API key: la chiave di abbonamento del prodotto Rating (Cotizador).

Coverage API key: la chiave di abbonamento del prodotto Coverage (Coberturas / Georreferencia). Serve a trovare il codice county di Chilexpress del 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. Inserisci un nuovo valore solo per 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: attiva una di queste opzioni e clicca su Save per eliminare quella chiave.

Origin county code: il codice county di Chilexpress del 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, viene usato 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: i comuna del Cile vengono cercati per regione, quindi le tariffe in tempo reale richiedono la regione (zona) dell'indirizzo. Il campo mostra quante zone ha il Cile e quali regioni mancano, con il pulsante Add Chilean regions. Aggiunge solo le regioni mancanti come zone del Cile; le zone esistenti non vengono modificate e una regione non viene aggiunta due volte. Quando tutte le 16 regioni sono presenti, il campo dice All 16 Chilean regions are zones of Chile. Se il Cile non è un paese del negozio, il campo lo segnala: aggiungilo in System > Localisation > Countries.

Disponibilità

Min weight (kg): il peso minimo del carrello perché il metodo appaia. 0 significa nessun limite (predefinito).

Max weight (kg): il metodo viene nascosto sopra questo peso del carrello. Predefinito: 25. 0 significa nessun limite; un campo vuoto significa 25 kg.

Minimum subtotal: mostra il metodo solo quando il subtotale del carrello (prodotti da spedire, dopo i coupon, IVA esclusa) è almeno questo importo. Lascialo vuoto per mostrarlo sempre.

Geo zone: offre il metodo solo per indirizzi in questa zona geografica. All zones (predefinito) significa nessun limite. Le zone geografiche si gestiscono in System > Localisation > Geo Zones. Non viene usato mentre Ignore shipping zones è attivo.

Ignore shipping zones: offre il metodo per i paesi sotto senza verificare la zona geografica.

Countries: i paesi di destinazione per quella modalità. Lascialo vuoto per consentire tutti i paesi. Questo campo viene usato solo quando Ignore shipping zones è attivo.

Spedizione gratuita

Free shipping: attiva la soglia della spedizione gratuita.

Free shipping from: il subtotale del carrello (prodotti da spedire, dopo i coupon, IVA esclusa) da cui la spedizione è gratuita. Usato solo quando 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 storage/logs/vfd_chx_debug.log.php. Il file non può essere letto dal web. Gli errori dell'API vengono sempre registrati, anche quando questa opzione è disattivata. Le chiavi API e gli indirizzi dei clienti non vengono mai registrati. Quando il file raggiunge 5 MB, viene spostato in vfd_chx_debug.old.log.php e si inizia un nuovo registro.

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

Remove data on uninstall: se attivo, la disinstallazione dell'estensione elimina tutte le sue impostazioni, le tariffe in cache e il registro. Se disattivo (predefinito), tutto viene conservato per una reinstallazione. Gli ordini e i servizi Chilexpress salvati con essi restano sempre.

Importazione / Esportazione

Export: clicca su Download JSON per salvare le impostazioni in un file JSON. Le chiavi API non vengono esportate.

Import: incolla un JSON esportato in precedenza e clicca su Import per ripristinare le impostazioni, per esempio in un altro negozio. I valori vengono controllati come in un normale salvataggio. Le chiavi API salvate vengono mantenute.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo Chilexpress. Se è impostata una Geo zone, Ignore shipping zones è disattivato e l'indirizzo è fuori dalla zona, Chilexpress non viene offerto. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non sono inclusi nel subtotale. I pesi vengono convertiti in chilogrammi e le dimensioni in centimetri in base alle classi di peso e di lunghezza dei prodotti. Il subtotale è il prezzo dei prodotti da spedire, dopo lo sconto del coupon, IVA esclusa, nella valuta predefinita del negozio. Buoni regalo, punti premio e credito del negozio non vengono considerati. L'estensione 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 con una fonte di tariffe API, l'estensione prende la regione (zona) dell'indirizzo e il comuna dal campo City e cerca il codice county di Chilexpress nell'elenco dei comuna di quella regione (API Coverage). Accenti, spazi e varianti ortografiche vengono ignorati, quindi Ñuñoa e Nunoa coincidono e Santiago coincide con Santiago Centro. Viene accettato anche un codice county digitato nel campo City. Poi l'estensione 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; l'estensione usa quello 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 cliente con l'imposta della Tax class selezionata.

Le tariffe sono memorizzate in cache per 1 ora. Gli elenchi dei comuna sono memorizzati in cache fino a 7 giorni, ma non più a lungo di quanto OpenCart conservi le proprie voci di cache (1 ora per impostazione predefinita). 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 il comuna o la regione sono sconosciuti, il cliente non vede alcun errore. Il metodo viene nascosto in modalità solo API, oppure si usa il prezzo fisso. Il motivo viene scritto nel registro di debug.

L'estensione 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 il comuna nel campo City standard. Le spedizioni internazionali usano i prezzi fissi.

Su OpenCart 4 il cliente clicca su Choose nel blocco dei metodi di spedizione della pagina di checkout e sceglie Chilexpress nella finestra Shipping method options, per esempio Chilexpress - $5.49. Il metodo funziona come su OpenCart 3.

Ordini

Quando un ordine viene effettuato con Chilexpress, l'estensione salva come è stato calcolato il prezzo. In Sales > Orders la pagina dell'ordine mostra un pannello Chilexpress con Chilexpress service (per una tariffa in tempo reale, il servizio quotato da Chilexpress, per esempio Express; altrimenti un trattino) e Price: Live rate (Chilexpress Rating API), Fixed price oppure Free shipping. Il pannello viene mostrato anche quando il metodo è disattivato. Su OpenCart 4 il pannello Chilexpress è mostrato sopra History, e quando un ordine viene confermato di nuovo al checkout o cambiato con un altro metodo di spedizione, il pannello segue la modifica.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco della licenza License — VibeFox Chilexpress è il primo blocco di Extensions > Extensions > Shipping > VibeFox Chilexpress > Edit, sopra le impostazioni. Incolla 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 ci sono la riga Product: opencart-shipping-chilexpress e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo gli utenti amministratori con il permesso Modify 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 aver cambiato l'indirizzo del negozio, o dopo aver liberato un posto per il 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 solo dominio: l'indirizzo del negozio nella configurazione di OpenCart. Rimuovere la chiave dal negozio non libera il suo posto per il dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, Chilexpress non viene mostrato ai clienti al checkout e non viene calcolata nessuna tariffa. Un utente amministratore che ha effettuato l'accesso all'amministrazione nello stesso browser vede comunque il metodo nel negozio, contrassegnato da (unlicensed — visible to admins only), così puoi configurare e testare l'estensione prima di acquistare una chiave. Su OpenCart 4 questa anteprima non è disponibile: il negozio non vede l'accesso all'amministrazione, quindi senza una chiave attiva il metodo è nascosto a tutti. 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 ricontrollato automaticamente quando apri la Dashboard o la pagina Edit dell'amministrazione: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve alcun cron job. La disinstallazione dell'estensione rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Chilexpress non compare al checkout: verifica che la licenza sia attiva e che Enable/Disable sia attivo. Controlla Geo zone (oppure Ignore shipping zones e Countries), i limiti di peso e Minimum subtotal. Con i prezzi fissi, verifica che il paese o * Default (other countries) abbia una riga. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.

La spedizione in Cile è gratuita quando non dovrebbe esserlo: la riga di Country prices per il Cile (o la riga predefinita) ha 0 in Price e nelle colonne delle dimensioni. Inserisci i prezzi e clicca su Save.

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

HTTP 401 o 403 nel registro: la chiave di abbonamento è sbagliata, inattiva oppure appartiene 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 negozio aggiunge l'imposta alla spedizione e la quota include già l'IVA, imposta Tax class su No tax.

Le tariffe sembrano obsolete dopo una modifica: clicca su Save nella pagina dell'estensione. Questo svuota le tariffe e gli elenchi dei comuna in cache.

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

Per gli sviluppatori: l'indirizzo base dell'API Chilexpress può essere sostituito con l'impostazione vfd_chx_api_base_url (per i test); non ha un campo nella pagina delle impostazioni.

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox Chilexpress. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable/Disable, Sort order, Tax class e Geo zone. Le tariffe e gli elenchi dei comuna in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, vengono eliminate anche le altre impostazioni e il registro di debug. Se è disattivo, restano e vengono riutilizzati quando reinstalli l'estensione. I servizi Chilexpress salvati con gli ordini non vengono mai eliminati, e gli ordini esistenti mantengono il loro metodo di spedizione e il costo. Le regioni cilene aggiunte con Add Chilean regions restano nel negozio.

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

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