VibeFox iMile for OpenCart — Guida

Requisiti

OpenCart: 3.0.x (testato con la versione 3.0.5.0) o 4.0.2 o successivo (testato con la versione 4.1.0.3).

PHP: 8.0 o successivo.

Tariffa iMile: i prezzi concordati con il team commerciale di iMile. Li inserisci nella tabella dei prezzi nella valuta predefinita del tuo negozio.

Account API iMile (solo per la stima in tempo reale): la stima in tempo reale usa l'OpenAPI di iMile "Estimated order delivery costs". Ti servono un Customer ID e una Secret key (la chiave API che iMile rilascia insieme al tuo Customer ID). Per un client di prova, registrati sul portale sviluppatori di iMile (developer.imile.com). Le chiavi di produzione vengono fornite dal tuo account manager iMile. Se usi solo la tabella dei prezzi, non ti servono chiavi API.

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un solo dominio.

Installazione

Il file scaricato è un unico zip con i pacchetti per entrambe le versioni di OpenCart. Decomprimilo sul tuo computer. Contiene README.txt, il pacchetto per OpenCart 3 vfd_imile-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_imile.ocmod.zip. Installa solo il pacchetto per la tua versione di OpenCart. La chiave di licenza è la stessa per entrambe le versioni.

OpenCart 3

1. Nell'area di amministrazione vai su Extensions > Installer, fai clic su Upload e scegli il file vfd_imile-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non devi aggiornare Extensions > Modifications. Invece dell'installer, puoi copiare il contenuto della cartella upload di questo pacchetto nella cartella radice del tuo negozio.

2. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox iMile e fai clic su Install (il pulsante verde +).

3. Fai clic su Edit (il pulsante con la matita) per aprire la pagina delle impostazioni.

4. Inserisci la tua chiave di licenza VibeFox nel campo License key del blocco di licenza in cima alla pagina Edit e fai clic su Activate (vedi Chiave di licenza).

5. Inserisci le tue tariffe iMile nella Price table. Facoltativamente compila la sezione Live rates (API) e attiva Live estimate (vedi Configurazione). Attiva Enable iMile e fai clic su Save.

OpenCart 4

1. Nell'area di amministrazione vai su Extensions > Installer, fai clic su Upload e scegli il file vfd_imile.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. Fai clic su Install (il pulsante verde +) accanto a esso.

3. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox iMile, fai clic su Install (il pulsante verde +), poi su Edit (il pulsante con la 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 resta disattivato finché non attivi Enable iMile e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni iMile che avevi conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox iMile > Edit. Le sezioni sono elencate a sinistra. Un pulsante Save salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella anche le stime iMile memorizzate e i token di accesso. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.

Al salvataggio l'estensione verifica che Method title sia valido (massimo 64 caratteri, senza < > ; = # { }), che i campi di prezzo, importo e peso siano numeri di 0 o più, che Minimum weight (kg) non sia maggiore di Maximum weight (kg), che Sort order sia un numero intero e che la classe fiscale e la zona geografica esistano. In caso contrario mostra un errore e non salva nulla.

Sopra le impostazioni compaiono avvisi (e di nuovo dopo un salvataggio) quando Live estimate è attivo ma non può funzionare: il Customer ID o la Secret key sono vuoti, manca la città o il paese di partenza (oppure il paese non è un mercato iMile), non ci sono tassi di cambio, oppure la tabella dei prezzi è vuota e non c'è un prezzo per gli altri paesi. Compare un avviso anche quando il negozio non ha una classe di peso in kg e l'unità della classe di peso predefinita non è riconosciuta dall'estensione: i pesi dei prodotti vengono allora considerati in chilogrammi, quindi aggiungi una classe di peso kg in System > Localisation > Weight Classes.

Generale

Le impostazioni valgono per tutte le zone geografiche. Puoi limitare il metodo a una zona geografica in Conditions, oppure attivare Ignore shipping zones in Countries per limitarlo a un elenco di paesi.

Enable iMile: mostra o nasconde iMile al checkout. Predefinito: disattivato.

Method title: il nome del metodo di spedizione mostrato al cliente nel carrello e al checkout. Predefinito: iMile. Obbligatorio.

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

Tariffe in tempo reale (API) (facoltativo)

Se iMile non restituisce alcuna stima (nessuna chiave, nessuna città ancora inserita, errore, timeout, nessun tasso di cambio), viene usata la tabella dei prezzi.

Live estimate: attivalo per ottenere il costo di spedizione da iMile. Predefinito: disattivato. Con la stima in tempo reale disattivata, durante il checkout non viene inviato nulla a iMile.

Environment: Production (openapi.imile.com) (predefinito) oppure Test (test-openapi.52imile.cn). Le chiavi di prova funzionano solo con il server di test e danno prezzi di prova.

Customer ID: il codice cliente (customerId) rilasciato da iMile, per esempio C2102192601. Svuotarlo cancella anche la Secret key salvata.

Secret key: la chiave segreta (chiave API) rilasciata da iMile insieme al Customer ID. Firma le richieste. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarla.

Signature: come vengono firmate le richieste.

Ship-from country: il paese da cui spedisci. La prima opzione, Store country, usa il paese del tuo negozio. L'elenco contiene solo i paesi per i quali l'estensione conosce i codici paese iMile.

Ship-from city: la città da cui vengono spediti i tuoi pacchi, scritta come nell'elenco delle città iMile (per esempio Dubai, Riyadh). Obbligatoria per le stime in tempo reale: OpenCart non ha una città del negozio, quindi senza questo campo viene usata solo la tabella dei prezzi.

Ship-from province: facoltativa, per esempio Dubai o Riyadh Province.

iMile service: il tipo di ordine inviato a iMile: Delivery order (100) (predefinito) oppure Express order (1100). Express deve essere abilitato per il tuo account e per il paese.

Goods category: il tipo di merce inviato a iMile: Normal goods (predefinito), Sensitive (cosmetics, liquids...), With battery, Batteries / power banks, Documents oppure Parcel.

Exchange rates: iMile stima nella valuta del paese di destinazione. Inserisci una riga per valuta con il prezzo di 1 unità nella valuta predefinita del tuo negozio, per esempio "AED = 0.25" o "SAR = 0.24". Non serve un tasso per la valuta del negozio stesso. Senza un tasso, le stime in quella valuta non vengono usate e si usa invece la tabella dei prezzi. Lo stesso tasso converte anche il valore del carrello dichiarato a iMile.

Prezzi (usati quando la stima in tempo reale è disattivata, e come alternativa quando iMile non restituisce alcuna stima)

Inserisci la tua tariffa iMile nella valuta predefinita del negozio, IVA esclusa. Se è in AED, SAR o un'altra valuta, convertila prima.

Price table: una riga per ogni paese di destinazione. Fai clic su Add country per aggiungere una riga e sul pulsante × per rimuoverne una. Scegli * All other countries per una riga che copre tutti i paesi senza una riga propria. Ogni riga ha un Base price e colonne di peso facoltative: XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg e XL >5 kg. Una colonna di peso vuota (o a 0) usa il prezzo base. Un prezzo base di 0 corrisponde a spedizione gratuita verso quel paese. Sono accettati sia "9.99" sia "9,99".

Price for countries not in the table: un prezzo nella valuta predefinita del negozio. Viene usato quando la tabella non ha una riga per il paese di destinazione (e non c'è una riga *), oppure quando la riga non ha un prezzo per quel peso. Lascialo vuoto per nascondere il metodo in questo caso.

Price applies: come viene addebitato il prezzo.

La stessa scelta vale per la stima in tempo reale: per ordine invia un pacco con l'intero carrello; per articolo chiede una stima per ogni pacco diverso e moltiplica per il numero di unità. Se il carrello contiene più di 5 pacchi diversi, si usa la tabella dei prezzi.

I pesi dei prodotti vengono convertiti dalla loro classe di peso di OpenCart in chilogrammi, e le dimensioni dalla loro classe di lunghezza in centimetri.

Condizioni

Minimum weight (kg): nasconde il metodo sotto questo peso del carrello. 0 significa nessun limite (predefinito).

Maximum weight (kg): nasconde il metodo sopra questo peso del carrello. Predefinito: 30. 0 significa nessun limite. Se lasci il campo vuoto, si usano 30 kg.

Minimum order amount: mostra il metodo solo quando il subtotale dei prodotti da spedire (dopo il coupon, prima delle imposte) raggiunge questo importo. Lascialo vuoto per mostrarlo sempre.

Free shipping from: il subtotale dei prodotti da spedire (dopo il coupon, prima delle imposte) a partire dal quale la consegna iMile è gratuita. Lascialo vuoto per non offrire mai la spedizione gratuita.

Tax class: la classe fiscale del costo di spedizione, oppure No tax (predefinito). Scegli No tax se i prezzi della tabella e le stime iMile includono già l'IVA.

Geo zone: offre iMile solo per gli indirizzi di questa zona geografica. All zones (predefinito) significa nessun limite. La zona geografica non viene controllata quando Ignore shipping zones è attivo. Le zone geografiche si gestiscono in System > Localisation > Geo Zones.

Paesi

Ignore shipping zones: quando è attivo, la Geo zone non viene controllata e iMile viene offerto per i paesi elencati sotto. Quando è disattivo (predefinito), vale solo la Geo zone.

Countries: i paesi di destinazione consentiti. Lascialo vuoto per consentire tutti i paesi attivati nel negozio. Questo campo viene usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: scrive i calcoli delle tariffe in storage/logs/vfd_imile_debug.log.php (su OpenCart 4 system/storage/logs/vfd_imile_debug.log.php). Il file non può essere letto dal web. Non vengono registrate chiavi né indirizzi dei clienti. Le richieste iMile non riuscite vengono sempre registrate, anche con il registro di debug disattivato. Disattiva il registro quando hai finito. Quando il file raggiunge 5 MB, viene spostato in vfd_imile_debug.old.log.php e ne viene avviato uno nuovo.

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

Remove data on uninstall: quando è attivo, disinstallando l'estensione vengono eliminate le impostazioni iMile e il registro. Quando è disattivo (predefinito), le impostazioni vengono conservate per una reinstallazione. Le stime memorizzate e i token di accesso vengono sempre eliminati.

Importa / Esporta

Export: fai clic su Download JSON per salvare le impostazioni in un file JSON. La Secret key non viene esportata.

Import: incolla un JSON esportato in precedenza e fai clic su Import per ripristinare le impostazioni, per esempio su un altro negozio. I valori vengono controllati come in un normale salvataggio. La Secret key salvata viene mantenuta.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo iMile. Se è impostata una Geo zone, Ignore shipping zones è disattivo e l'indirizzo è al di fuori della zona geografica, iMile non viene offerto. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri prodotti non aggiungono peso e non sono inclusi nell'importo dell'ordine. L'estensione verifica poi le condizioni: paesi consentiti (quando Ignore shipping zones è attivo), peso del carrello e importo minimo dell'ordine. L'importo dell'ordine è il prezzo dei prodotti da spedire, dopo lo sconto del coupon e prima delle imposte. Buoni regalo, punti fedeltà e credito del negozio non vengono considerati. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata alcuna richiesta a iMile.

Con la stima in tempo reale attiva, l'estensione invia a iMile il paese, la provincia e la città di partenza, il paese di destinazione, la regione, la città e il codice postale di destinazione, il peso del carrello in kg, le dimensioni in cm³ (dalle dimensioni dei prodotti), il valore del carrello, il servizio iMile e la categoria di merce. La stima viene sempre richiesta come prepagata, quindi le commissioni di pagamento alla consegna non sono incluse. Una stima in tempo reale viene richiesta solo dopo che il cliente ha inserito un indirizzo di consegna con una città, e solo quando ogni prodotto nel carrello ha un peso.

Ogni risposta viene memorizzata per 1 ora. Una richiesta non riuscita viene memorizzata per 5 minuti. Dopo un timeout o un errore del server, iMile non viene interrogato per 2 minuti; dopo chiavi rifiutate, per 5 minuti, così che il checkout non attenda iMile a ogni aggiornamento. Il timeout dell'API è di 12 secondi. Un token di accesso scaduto viene rinnovato automaticamente.

La stima viene convertita nella valuta predefinita del negozio con i tuoi tassi di cambio. Se iMile non fornisce una stima utilizzabile (chiavi non impostate, città non ancora inserita, città sconosciuta, errore, timeout, nessun tasso di cambio), il cliente non vede alcun errore e viene usato il prezzo della tabella. Se anche la tabella non ha un prezzo, il metodo viene nascosto. Il motivo viene scritto nel registro. Il prezzo viene calcolato nella tua valuta predefinita, arrotondato ai suoi decimali e mostrato al cliente nella sua valuta con l'imposta della Tax class selezionata.

Su OpenCart 4 il cliente fa clic su Choose nel blocco del metodo di spedizione nella pagina di checkout e sceglie iMile nella finestra Shipping method options. Il metodo funziona come su OpenCart 3.

L'estensione calcola solo le tariffe. Non crea spedizioni iMile, non stampa etichette AWB, non richiede ritiri, non traccia i pacchi, non riconcilia i pagamenti alla consegna e non offre punti di ritiro o armadietti. Non aggiunge nulla agli ordini: l'ordine mostra il nome del metodo di spedizione e il costo come qualsiasi altro metodo di spedizione OpenCart. Per le spedizioni usa il portale iMile.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox iMile è il primo blocco nella pagina Extensions > Extensions > Shipping > VibeFox iMile > Edit, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopo l'attivazione 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: opencart-shipping-imile e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo gli utenti amministratori con il permesso di modifica 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 uno slot di dominio nel tuo account, fai clic 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 dalla configurazione di OpenCart. 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 metodo di spedizione iMile non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Un utente amministratore collegato all'amministrazione nello stesso browser vede comunque il metodo nel negozio, contrassegnato con (unlicensed — visible to admins only), così da poter configurare e provare 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 un rinnovo. Lo stato viene controllato di nuovo automaticamente quando apri la Dashboard dell'amministrazione o la pagina Edit: 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

iMile non compare al checkout: verifica che la licenza sia attiva e che Enable iMile sia attivo. Controlla Geo zone, Ignore shipping zones e Countries, i limiti di peso e Minimum order amount. Verifica che il paese o * All other countries abbia una riga nella Price table, oppure che sia impostato Price for countries not in the table. Controlla che i prodotti abbiano Requires Shipping impostato su Yes.

Al posto della stima iMile viene mostrato il prezzo della tabella: attiva Debug log, ricarica il checkout e controlla il campo Log nella pagina dell'estensione. Cause comuni: Live estimate è disattivo, mancano le chiavi, Ship-from city è vuoto, il cliente non ha ancora inserito una città, iMile non riconosce la grafia della città, i prodotti non hanno peso, non c'è un tasso di cambio per la valuta di destinazione, oppure un errore dell'API. Controlla anche gli avvisi sopra le impostazioni.

"sign is invalid" nel registro: controlla la Secret key, poi prova Signature = SimpleKey.

Le chiavi vengono rifiutate: controlla il Customer ID, la Secret key e l'Environment. Le chiavi di prova funzionano solo con il server di test.

I nomi delle città non corrispondono: i nomi delle città devono corrispondere all'elenco delle città iMile. Gli sviluppatori possono modificare la richiesta con l'evento OpenCart vfd_imile/live_request, e i codici paese con l'evento vfd_imile/live_country_code.

I prezzi sono nella valuta sbagliata: la tabella dei prezzi è nella valuta predefinita del negozio. Converti una tariffa in AED, SAR o MXN quando la inserisci. Le stime in tempo reale vengono convertite con Exchange rates.

L'imposta sulla spedizione viene addebitata due volte: se i tuoi prezzi includono già l'IVA, imposta Tax class su No tax.

Le stime sembrano superate dopo una modifica: fai clic su Save nella pagina dell'estensione. Questo cancella le stime iMile memorizzate.

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

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e fai clic su Uninstall (il pulsante rosso −) accanto a VibeFox iMile. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable iMile, Sort order, Tax class e Geo zone. Le stime memorizzate e i token di accesso vengono sempre rimossi. Se Remove data on uninstall è attivo, vengono eliminate anche le impostazioni iMile e il registro di debug. Se è disattivo, le altre impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. Gli ordini esistenti mantengono il loro metodo di spedizione e il loro costo.

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

iMile è un marchio del suo titolare. Questa estensione non è affiliata a iMile né approvata da iMile.