VibeFox iMile for WooCommerce — Guida

Requisiti

WordPress: 5.8 o successivo.

WooCommerce: 5.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.

PHP: 8.0 o successivo.

Tariffa iMile: i prezzi concordati con il team commerciale di iMile. Li inserisci nella tabella prezzi nella valuta 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". Servono un Customer ID e una Secret key (la chiave API che iMile rilascia insieme al Customer ID). Per un client di test, registrati sul portale sviluppatori iMile (developer.imile.com). Le chiavi di produzione vengono fornite dal tuo account manager iMile. Se usi solo la tabella prezzi, non 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 fai clic su Install Now. In alternativa puoi caricare la cartella vfd_imile in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox iMile, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugins.

4. Inserisci la chiave di licenza VibeFox nel blocco licenza in alto nella pagina e fai clic su Activate.

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

6. Aggiungi VibeFox iMile a una zona di spedizione in WooCommerce > Settings > Shipping > Shipping zones (per esempio "United Arab Emirates"), oppure attiva Ignore shipping zones e scegli i paesi.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox iMile. Si applicano a tutte le zone di spedizione. Quando aggiungi il metodo a una zona, la finestra della zona contiene un solo campo:

Title (zone): il nome che i clienti vedono per questa zona. Lascia vuoto per usare il Method title globale.

Ogni volta che salvi le impostazioni, le stime iMile in cache e i token di accesso vengono cancellati. Quando la stima in tempo reale è attiva ma non può funzionare (nessuna chiave, nessuna città o paese di partenza, nessun tasso di cambio, tabella prezzi vuota), sopra le impostazioni compaiono avvisi.

Generali

Enable/Disable: attiva o disattiva il metodo in tutte le zone contemporaneamente.

Method title: il nome del metodo di spedizione mostrato nel carrello e al checkout. Una zona può sostituirlo. Predefinito: iMile.

Tariffe in tempo reale (API) (facoltativo)

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

Live estimate: attivala per ottenere il costo di spedizione da iMile. Predefinito: disattivata. 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 danno prezzi di prova.

Customer ID: il codice cliente (customerId) rilasciato da iMile, per esempio C2102192601.

Secret key: la chiave segreta (chiave API) rilasciata da iMile insieme al Customer ID. Firma le richieste.

Signature: il modo in cui le richieste vengono firmate.

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

Ship-from city: la città da cui vengono spediti i tuoi colli, scritta come nell'elenco città di iMile (per esempio Dubai, Riyadh). Lascia vuoto per usare la città del negozio da WooCommerce > Settings > General.

Ship-from province: facoltativo, 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 calcola le stime nella valuta del paese di destinazione. Inserisci una riga per valuta con il prezzo di 1 unità nella valuta del tuo negozio, per esempio "AED = 0.25" o "SAR = 0.24". Come separatore decimale sono accettati sia il punto sia la virgola. Non serve un tasso per la valuta del negozio stesso. Senza tasso, le stime in quella valuta non vengono usate e si applica invece la tabella prezzi. Lo stesso tasso converte il valore del carrello dichiarato a iMile. Le righe non valide vengono rimosse al salvataggio.

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

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

Price table: una riga per paese di destinazione. Fai clic su + Add country per aggiungere una riga e sulla croce 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 significa spedizione gratuita verso quel paese. Sono accettati sia "9.99" sia "9,99". Le righe senza prezzo, i codici paese non validi e i prezzi negativi vengono rimossi al salvataggio. Viene mantenuta una sola riga per paese.

Price for countries not in the table: un prezzo nella valuta 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. Lascia vuoto per nascondere il metodo in quel 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 tutto il carrello; per articolo richiede ogni collo diverso e moltiplica per il numero di unità. Se il carrello contiene più di 5 colli diversi, si usa la tabella prezzi.

I pesi dei prodotti vengono convertiti dall'unità di peso del negozio in chilogrammi.

Condizioni

Minimum weight (kg): nasconde il metodo quando il carrello pesa meno. 0 significa nessun limite.

Maximum weight (kg): nasconde il metodo quando il carrello pesa di più. Predefinito: 30. 0 significa nessun limite.

Minimum order amount: mostra il metodo 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.

Excluded shipping classes: nasconde il metodo quando il carrello contiene un prodotto di una di queste classi di spedizione di WooCommerce.

Tax status: Taxable aggiunge l'imposta di WooCommerce al costo di spedizione, None non l'aggiunge. Scegli None se i prezzi della tabella e le stime iMile includono già l'IVA.

Disponibilità senza zone di spedizione

Ignore shipping zones: offre iMile per i paesi indicati sotto, anche se il metodo non è aggiunto a nessuna zona di spedizione.

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

Avanzate

Debug log: scrive i calcoli delle tariffe in WooCommerce > Status > Logs (origine "vfd_imile"). 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.

Remove data on uninstall: se attivo, eliminando il plugin vengono rimosse tutte le impostazioni iMile, i metodi di zona e le stime in cache. La disattivazione del plugin non elimina mai nulla.

Come funziona al checkout

Quando il cliente inserisce un indirizzo di consegna, WooCommerce chiede al plugin una tariffa. Il plugin verifica prima le condizioni: paese di consegna, peso del carrello, importo minimo dell'ordine e classi di spedizione escluse. Se si applica la spedizione gratuita, il cliente vede il metodo senza costi e non viene inviata alcuna richiesta a iMile.

Con la stima in tempo reale attiva, il plugin invia a iMile il paese, la provincia e la città di partenza, il paese, 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 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 una città, e solo quando ogni collo 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 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 metodo viene nascosto. Il motivo viene scritto nel log.

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 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 plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in alto in WooCommerce > Settings > Shipping > VibeFox iMile. Incolla la chiave in License key e fai clic 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 lo slot del dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, iMile non viene mostrato ai clienti al checkout. I gestori del negozio con l'accesso lo vedono ancora, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Nella pagina Plugins e nelle pagine di WooCommerce compare un promemoria. 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 controllato di nuovo automaticamente in background.

Risoluzione dei problemi

iMile 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 sia consentito). Controlla i limiti di peso, Minimum order amount e Excluded shipping classes. Verifica che il paese o * abbia una riga nella Price table, oppure che Price for countries not in the table sia impostato.

Al posto della stima iMile viene mostrato il prezzo della tabella: apri WooCommerce > Status > Logs, origine "vfd_imile", e attiva Debug log per i dettagli. Cause comuni: Live estimate è disattivata, mancano le chiavi, il cliente non ha ancora inserito una città, iMile non riconosce la grafia della città, i prodotti non hanno peso, non esiste un tasso di cambio per la valuta di destinazione oppure c'è 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 e 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 associarli con il filtro vfd_imile_live_request e i codici paese con il filtro vfd_imile_live_country_code.

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

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

Le stime sembrano obsolete dopo una modifica: salva la pagina delle impostazioni. Questo cancella le stime iMile in cache.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera uno slot nel tuo account vibefox.net e fai clic su Check now. Se l'indirizzo del sito è cambiato, fai clic 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 tutti i dati. Per rimuoverlo, disattivalo ed eliminalo dalla pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi. Le impostazioni, i metodi di zona e le stime in cache vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano per una reinstallazione successiva. Gli ordini esistenti conservano le loro righe di spedizione.

iMile è un marchio del rispettivo titolare. Questo plugin non è affiliato a iMile né approvato da iMile.