VibeFox iMile for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni precedenti di PHP.

Tariffa iMile: i prezzi concordati con il team commerciale di iMile. Li inserisci nella tabella 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 Customer ID). Per un cliente di test, registrati sul portale sviluppatori di iMile (developer.imile.com). Le chiavi di produzione ti vengono fornite dal tuo account manager iMile. Se usi solo la tabella prezzi, non ti servono chiavi API.

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 cerca più tardi VibeFox iMile 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 fai clic su Activate (vedi Chiave di licenza).

4. Inserisci i tuoi prezzi iMile nella Price table. Facoltativamente, compila la sezione Live rates (API) e attiva Live estimate (vedi Configurazione). Clicca su Save.

All'installazione il modulo crea il corriere iMile con il testo dei tempi di consegna Courier delivery. Il corriere viene assegnato a tutte le zone e a tutti i gruppi di clienti. Puoi modificare zone, gruppi di clienti, tempi di consegna, logo e limiti dimensionali in Shipping > Carriers. Non impostare lì i prezzi: il prezzo proviene sempre dal modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox iMile > Configure. Si applicano a ogni zona del corriere. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella anche le stime iMile in cache e i token di accesso.

Quando Live estimate è attivo ma non può funzionare, compaiono avvisi sopra le impostazioni: Customer ID o 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 prezzi è vuota e non esiste un prezzo per gli altri paesi. Un avviso compare anche quando il modulo non riconosce l'unità di peso del negozio: i pesi dei prodotti vengono allora considerati in chilogrammi, quindi imposta l'unità in International > Localization (Local units). Al salvataggio il modulo verifica che Method title sia valido (massimo 64 caratteri), che i campi di importo e peso siano numeri pari o superiori a 0, che Minimum weight non sia maggiore di Maximum weight e che la regola fiscale esista. In caso contrario mostra un errore e non salva nulla.

Generali

Enable iMile: attiva o disattiva il corriere. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.

Method title: il nome del corriere mostrato nel carrello e al checkout. Predefinito: iMile. Obbligatorio.

Tariffe in tempo reale (API) (facoltativo)

Se iMile non restituisce una stima (nessuna chiave, città non ancora inserita, errore, timeout, nessun tasso di cambio), si usa la tabella prezzi.

Live estimate: attivala 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 test funzionano solo con il server di test e restituiscono prezzi di test.

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 per modificarla.

Signature: come vengono firmate le richieste.

Ship-from country: il paese da cui spedisci. Per impostazione predefinita è il paese del tuo negozio (Shop country). L'elenco contiene solo i paesi per cui il modulo ha i codici paese iMile.

Ship-from city: la città da cui partono i tuoi colli, scritta come nell'elenco città di iMile (ad esempio Dubai, Riyadh). Lascia vuoto per usare la città del negozio indicata in Shop Parameters > Contact > Stores.

Ship-from province: facoltativo, ad 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 tuo paese.

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

Exchange rates: iMile calcola le stime nella valuta del paese di destinazione. Inserisci una riga per valuta con il prezzo di 1 unità nella valuta predefinita del tuo negozio, ad esempio "AED = 0.25" o "SAR = 0.24". Come separatore decimale sono accettati il punto o la virgola. Per la valuta del negozio stesso non serve un tasso. Senza tasso, le stime in quella valuta non vengono usate e al loro posto si usa la tabella prezzi. Lo stesso tasso converte il valore del carrello dichiarato a iMile. Le righe non valide vengono rimosse al salvataggio.

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

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

Price table: una riga per paese di destinazione. Clicca su Add country per aggiungere una riga e sull'icona del cestino per rimuoverla. 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 0) usa il prezzo base. Un prezzo base di 0 significa spedizione gratuita verso quel paese. Sono accettati sia "9.99" sia "9,99". Le righe senza alcun prezzo e i prezzi negativi vengono rimossi al salvataggio. Per ogni paese resta una sola riga.

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 questo peso. Lascialo vuoto per nascondere il corriere in questo caso.

Price applies: come viene addebitato il prezzo della tabella.

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

Pesi e dimensioni dei prodotti vengono convertiti dalle unità del negozio in chilogrammi e centimetri.

Condizioni

Minimum weight: nasconde il corriere quando il carrello pesa meno, in kg. 0 significa nessun limite.

Maximum weight: nasconde il corriere quando il carrello pesa di più, in kg. Predefinito: 30. 0 significa nessun limite.

Minimum order amount: mostra il corriere solo quando il subtotale del carrello (dopo gli sconti, prima delle imposte) raggiunge questo importo. Lascia vuoto per mostrarlo sempre.

Free shipping from: il subtotale del carrello (dopo gli sconti, prima delle imposte) a partire dal quale la consegna iMile è gratuita. Lascia vuoto per non offrire mai la spedizione gratuita.

Tax: la regola fiscale del corriere, oppure No tax. Scegli No tax se i prezzi in tabella e le stime iMile includono già l'IVA.

Disponibilità senza zone di spedizione

Ignore shipping zones: offri iMile per i paesi sotto indicati, indipendentemente dalla zona che corrisponde. Al salvataggio il corriere viene aggiunto a tutte le zone, e anche le zone create in seguito lo ricevono. Disattivando l'opzione, le zone aggiunte vengono rimosse e il corriere riottiene le zone che aveva prima.

Countries: i paesi di destinazione per questa modalità. Lascia vuoto per usare tutti i paesi attivi. Questo campo viene usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: scrive i calcoli delle tariffe in logs/vfd_imle_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Non vengono registrate chiavi né indirizzi dei clienti. Le richieste iMile non riuscite vengono sempre registrate, anche con il log di debug disattivato. Disattiva il log quando hai finito.

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

Remove data on uninstall: se attivo, la disinstallazione del modulo elimina le impostazioni iMile, il corriere, le stime in cache e i log. Se disattivo, tutto viene conservato per una reinstallazione.

Come funziona al checkout

Nel passaggio di spedizione PrestaShop chiede al modulo il prezzo iMile. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nell'importo dell'ordine. Il modulo verifica prima le condizioni: paesi consentiti (se Ignore shipping zones è attivo), peso del carrello e importo minimo dell'ordine. Se si applica la spedizione gratuita, il prezzo è 0 e non parte alcuna richiesta verso iMile.

Con la stima in tempo reale attiva, il modulo invia a iMile il paese, la provincia e la città di partenza, il paese di destinazione, lo stato, la città e il CAP 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 merci. La stima viene sempre richiesta come prepagata, quindi le commissioni di pagamento alla consegna non sono incluse. La 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 del carrello ha un peso. Ogni risposta viene memorizzata nella cache per 1 ora. Una richiesta non riuscita viene memorizzata nella cache 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ì il checkout non attende iMile a ogni aggiornamento. Il timeout delle 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 si usa il prezzo della tabella. Se anche la tabella non ha un prezzo, il corriere viene nascosto. Il motivo viene scritto nel log. Il prezzo viene calcolato nella valuta predefinita e poi mostrato nella valuta del carrello del cliente.

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

Il modulo 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. Per le spedizioni usa il portale iMile.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox iMile è il primo blocco di Modules > Module Manager > VibeFox iMile > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic 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 compaiono la riga Product: presta-shipping-imile e il collegamento 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 oppure 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, 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 iMile non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. La vetrina di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il corriere viene nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non puoi provarlo al checkout. Nella pagina Modules > Module Manager, nella scheda Alerts, compare un promemoria. Gli ordini esistenti non sono interessati.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene controllato di nuovo 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

iMile non compare al checkout: verifica che la licenza sia attiva e che Enable iMile sia attivo. In Shipping > Carriers verifica che il corriere copra la zona del paese del cliente e il gruppo del cliente, oppure attiva Ignore shipping zones e controlla Countries. Controlla i limiti di peso e Minimum order amount. Verifica che il paese o * abbia una riga nella Price table, oppure che Price for countries not in the table sia impostato. I prodotti possono inoltre essere limitati a determinati corrieri nella pagina del prodotto.

Al posto della stima iMile viene mostrato il prezzo della tabella: attiva il Debug log, ricarica il checkout e controlla il campo Log nella pagina del modulo. Cause comuni: Live estimate è disattivato, mancano le chiavi, 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 API. Controlla anche gli avvisi sopra le impostazioni.

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

Le chiavi vengono rifiutate: controlla Customer ID, Secret key ed Environment. Le chiavi di test funzionano solo con il server di test.

I nomi delle città non corrispondono: i nomi delle città devono corrispondere all'elenco città di iMile. Gli sviluppatori possono mapparli con l'hook actionVfdImileLiveRequest, e i codici paese con l'hook actionVfdImileLiveCountryCode.

I prezzi sono nella valuta sbagliata: la tabella 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 applicata due volte: se i tuoi prezzi includono già l'IVA, imposta Tax su No tax.

Le stime sembrano obsolete dopo una modifica: clicca su Save nella pagina del modulo. Questo cancella le stime iMile in cache.

La pagina dice che il corriere iMile non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Ripristina il modulo in Modules > Module Manager per ricrearlo.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox iMile e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi.Le stime in cache e i token di accesso vengono sempre rimossi. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini conservano la cronologia) e vengono rimosse impostazioni e log. Se è disattivo, il corriere viene solo disabilitato e tutte le impostazioni vengono conservate. Reinstallando il modulo viene ripristinato lo stato che il corriere aveva prima.

iMile è un marchio del rispettivo proprietario. Questo modulo non è affiliato a iMile né approvato da iMile.