VibeFox GIG Logistics 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.

Credenziali API di GIG Logistics (solo per i prezzi in tempo reale): i prezzi in tempo reale usano l'API di terze parti di GIG Logistics. GIG Logistics rilascia ai clienti business un nome utente API (di solito un indirizzo e-mail) e una password. Richiedili nella pagina per sviluppatori di GIG Logistics (giglogistics.com/developer). Le credenziali di test funzionano solo con l'API di test. Se usi solo la tabella dei prezzi e il costo di riserva, non ti servono credenziali API.

Nigeria nel tuo negozio: i prezzi in tempo reale vengono richiesti solo per gli indirizzi di consegna in Nigeria. OpenCart include già il paese Nigeria con i suoi 37 stati; deve essere attivato in System > Localisation > Countries.

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_gig_logistics-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_gig_logistics.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. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_gig_logistics-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non serve aggiornare Extensions > Modifications. Invece dell'installer puoi anche 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 GIG Logistics 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 di licenza in cima alla pagina Edit e clicca su Activate (vedi Chiave di licenza).

5. Compila la tabella dei prezzi e/o il costo di riserva. Per i prezzi in tempo reale inserisci anche il nome utente e la password API, il telefono di ritiro, via, città e stato, e il tasso di conversione della valuta se la valuta predefinita non è il NGN (vedi Configurazione). Attiva Enable/Disable e clicca su Save.

OpenCart 4

1. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_gig_logistics.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 a esso.

3. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox GIG Logistics, 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 resta disattivato finché non attivi Enable/Disable e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni che hai conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox GIG Logistics > Edit. Le sezioni sono elencate a sinistra. Un unico pulsante Save in fondo salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella anche i prezzi GIG Logistics, i token API e le coordinate degli indirizzi in cache. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.

In cima alla pagina, e di nuovo dopo ogni salvataggio, l'estensione mostra avvisi quando i prezzi in tempo reale non possono essere usati: è stato inserito solo il nome utente o la password API, manca il Sender phone oppure la città e lo stato di ritiro, oppure la valuta predefinita non è il NGN e non è impostato alcun Currency conversion rate. Avvisa anche se nel negozio non esiste una classe di peso con unità kg (System > Localisation > Weight Classes); i pesi dei prodotti vengono allora convertiti in base al nome della loro unità (kg, g, lb, oz), e le altre unità vengono lette come kg. Al salvataggio viene segnalato un numero non valido (un importo negativo, un Currency conversion rate pari a 0, una latitudine fuori da -90 a 90, una longitudine fuori da -180 a 180), un Min weight (kg) superiore a Max weight (kg), un Method title vuoto o non valido, un ordinamento che non è un numero intero, oppure una classe fiscale o una zona geografica sconosciuta, e non viene salvato nulla.

Generale

Il metodo viene offerto per la zona geografica selezionata in Conditions, oppure per i paesi di Ignore shipping zones. Le impostazioni di questa pagina valgono per tutte le zone.

Enable/Disable: mostra o nasconde GIG Logistics al checkout (lo stato di questa estensione). Predefinito: disattivato.

Method title: il nome del metodo di spedizione mostrato nel carrello e al checkout. Predefinito: GIG Logistics. Obbligatorio, da 1 a 64 caratteri, senza i caratteri < > ; = # { }.

Tax class: la classe fiscale del costo di spedizione, oppure No tax. Una classe fiscale aggiunge la tua imposta di spedizione sopra il costo. Scegli No tax se il prezzo GIG include già tutto ciò che vuoi addebitare.

Sort order: la posizione del metodo tra i metodi di spedizione. Un numero intero.

API di GIG Logistics (prezzi in tempo reale) (facoltativo)

Con le credenziali API il prezzo viene richiesto a GIG Logistics per ogni indirizzo in Nigeria e memorizzato nella cache per un'ora. Senza credenziali, oppure quando l'API non restituisce un prezzo, si usano la tabella dei prezzi e il costo di riserva. La sezione contiene un link alla pagina per sviluppatori di GIG Logistics.

API username: il tuo nome utente dell'API di terze parti di GIG Logistics, di solito il tuo indirizzo e-mail.

API password: la tua password dell'API di terze parti di GIG Logistics. Serve solo ad accedere all'API e non viene mai registrata. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. To remove it, clear the API username and save. Inserisci un nuovo valore solo per cambiarla.

Test mode: usa l'API di test (dev) di GIG Logistics. Le credenziali di test funzionano solo con l'API di test. Disattivala per i prezzi reali. Predefinito: disattivato.

Currency conversion rate: GIG Logistics restituisce i prezzi in NGN. Se la valuta predefinita del tuo negozio non è il NGN, inserisci quanto vale 1 NGN nella tua valuta predefinita (1 NGN = ? della tua valuta, per esempio 0.0006). Il tasso deve essere superiore a 0. Senza di esso i prezzi GIG in tempo reale non vengono usati. Se la valuta predefinita è il NGN, il campo lo indica e non serve.

Indirizzo di ritiro (mittente)

Dove GIG Logistics ritira i pacchi, in Nigeria. OpenCart non ha un indirizzo del negozio strutturato, quindi inserisci qui la via e la città. Quando il paese del tuo negozio è la Nigeria, un State vuoto usa la regione del negozio di System > Settings > Store > Local.

Sender name: il nome del mittente inviato a GIG Logistics. Se vuoto, si usa il nome del negozio.

Sender phone: il tuo numero di telefono, per esempio 08030000000. GIG Logistics lo richiede per i prezzi in tempo reale.

Street address: la via del ritiro, per esempio 1 Adeola Odeku Street.

City / area: la città o la zona del ritiro, per esempio Victoria Island. Obbligatoria per i prezzi in tempo reale.

State: lo stato nigeriano dell'indirizzo di ritiro, scelto tra i 37 stati. L'opzione predefinita, Store region (System > Settings > Store > Local), usa la regione del tuo negozio quando il negozio si trova in Nigeria. Obbligatorio per i prezzi in tempo reale.

Pickup latitude: latitudine facoltativa del punto di ritiro sulla mappa, per esempio 6.4281. GIG Logistics calcola i prezzi in base alla distanza. Se vuota, le coordinate vengono cercate a partire dall'indirizzo.

Pickup longitude: longitudine facoltativa del punto di ritiro sulla mappa, per esempio 3.4219.

Address lookup: cerca le coordinate sulla mappa degli indirizzi con OpenStreetMap (Nominatim). GIG Logistics calcola il prezzo dalle coordinate di ritiro e di consegna. Via, città e stato del cliente vengono inviati a nominatim.openstreetmap.org, e i risultati sono memorizzati nella cache per 30 giorni. Senza questa opzione viene inviato solo il testo dell'indirizzo, e GIG Logistics potrebbe non restituire un prezzo. Predefinito: attivo.

Tabella dei prezzi e riserva

Si usa per gli altri paesi, quando i prezzi in tempo reale non sono configurati o quando GIG Logistics non restituisce un prezzo. I prezzi sono nella valuta predefinita del tuo negozio, IVA esclusa.

Country prices: una tabella con un prezzo base per paese. Clicca su Add country per aggiungere una riga. Scegli * Any other country per tutti i paesi senza una riga propria. Le colonne XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg e XL >5 kg sono prezzi facoltativi per fascia di peso: un prezzo di fascia superiore a 0 sostituisce il prezzo base per i carrelli di quella fascia. Un prezzo pari a 0 significa spedizione gratuita. Le celle dei prezzi vuote o non valide vengono salvate come 0, quindi compila il prezzo base per ogni riga che aggiungi. I valori corretti vengono elencati dopo il salvataggio in un avviso che inizia con Country prices:. I paesi senza riga (quando non c'è una riga *) non ricevono un prezzo dalla tabella.

Fallback cost: usato quando né GIG Logistics né la tabella forniscono un prezzo. Vuoto significa che il metodo viene nascosto in quel caso.

Table / fallback price is: Per order addebita il prezzo una sola volta. Per item (multiplied by the number of items) lo moltiplica per il numero di articoli nel carrello. I prezzi GIG in tempo reale valgono sempre per l'intero ordine.

Condizioni

Free shipping from: il subtotale del carrello (prodotti che richiedono spedizione, dopo il coupon, IVA esclusa) da cui la spedizione è gratuita. Vuoto significa mai gratuita.

Minimum subtotal: mostra il metodo solo quando il subtotale del carrello raggiunge questo importo. Vuoto significa sempre.

Min weight (kg): il peso minimo del carrello in kg. I pesi dei prodotti vengono convertiti con la loro classe di peso. 0 significa nessun limite.

Max weight (kg): il peso massimo del carrello in kg. Predefinito: 30. 0 significa nessun limite.

Geo zone: offri il metodo solo per indirizzi di questa zona geografica. All zones significa nessun limite. Non si usa con Ignore shipping zones. Le zone geografiche si gestiscono in System > Localisation > Geo Zones.

Disponibilità senza zone di spedizione

Ignore shipping zones: offri il metodo per i paesi indicati di seguito, qualunque sia la zona geografica. La Geo zone in Conditions non viene verificata in questo caso.

Countries: i paesi di destinazione per questa modalità, scelti tra i paesi attivi del tuo negozio. Vuoto significa tutti i paesi verso cui spedisci. Si usa solo con Ignore shipping zones.

Avanzate

Debug log: scrive i calcoli dei prezzi in storage/logs/vfd_gigl_debug.log.php (su OpenCart 4 system/storage/logs/vfd_gigl_debug.log.php). Il file non è leggibile dal web. Gli errori dell'API e della ricerca degli indirizzi vengono sempre registrati, anche con il registro disattivato. Non vengono scritte password, token o indirizzi dei clienti. Quando il file raggiunge 5 MB, viene spostato in vfd_gigl_debug.old.log.php e si avvia 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, disinstallando l'estensione vengono eliminate le impostazioni e i registri. Se disattivo, tutto viene conservato per una reinstallazione. I prezzi in cache vengono sempre rimossi. Gli ordini vengono sempre conservati.

Importa / Esporta

Export: clicca su Download JSON per salvare le impostazioni in un file JSON. La password API non viene esportata.

Import: incolla un JSON esportato in precedenza e clicca su Import per ripristinare le impostazioni, per esempio su un altro negozio. I valori vengono verificati come in un normale salvataggio. La password API salvata viene conservata.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di GIG Logistics. Se è impostata una Geo zone (e Ignore shipping zones è disattivato) e l'indirizzo è al di fuori di essa, il metodo non viene offerto. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non sono inclusi nel subtotale. Il subtotale è il prezzo di questi prodotti dopo lo sconto del coupon, IVA esclusa. Buoni regalo, punti fedeltà e credito del negozio non vengono considerati. L'estensione controlla prima le condizioni: il paese di consegna (con Ignore shipping zones), il peso del carrello e il subtotale minimo. Se il subtotale raggiunge Free shipping from, il prezzo è 0 e non viene inviata alcuna richiesta a GIG Logistics.

Poi il prezzo viene preso dalla prima fonte che ne fornisce uno. Prima, il prezzo GIG Logistics in tempo reale, se sono inserite le credenziali API, l'indirizzo si trova in Nigeria, l'indirizzo ha una città o uno stato, il telefono, la città e lo stato di ritiro sono impostati, e per i negozi la cui valuta predefinita non è il NGN è impostato un tasso di conversione. L'estensione accede all'API di GIG Logistics e invia gli indirizzi e le coordinate di ritiro e di consegna e gli articoli del carrello con nomi, quantità, pesi e valori. I prodotti senza peso vengono inviati come 1 kg. Il prezzo viene richiesto per la consegna in bicicletta. Secondo, la tabella Country prices. Terzo, il Fallback cost. Se nessuna fonte fornisce un prezzo, il metodo viene nascosto per quel carrello. Il prezzo viene calcolato nella valuta predefinita, arrotondato secondo i suoi decimali e mostrato al cliente nella sua valuta con l'imposta della Tax class selezionata.

Ogni risposta di GIG viene memorizzata nella cache per 1 ora, così lo stesso carrello non attiva una nuova richiesta. Una richiesta non riuscita o un accesso non riuscito viene memorizzato nella cache per 10 minuti, così il checkout non attende GIG Logistics a ogni aggiornamento. Il token di accesso viene mantenuto per 30 minuti e rinnovato automaticamente quando GIG lo rifiuta. Le coordinate degli indirizzi vengono conservate per 30 giorni, e un indirizzo non trovato per 1 giorno. Il timeout dell'API è di 10 secondi, quello della ricerca degli indirizzi di 5 secondi.

Se GIG Logistics restituisce un errore o un prezzo pari a zero, il cliente non vede alcun errore. Si usa il prezzo della tabella o il costo di riserva, e l'errore viene scritto nel registro di debug.

L'estensione calcola solo i prezzi. Non crea spedizioni, lettere di vettura o etichette GIG Logistics, non prenota ritiri, non traccia i pacchi e non permette ai clienti di scegliere un centro di servizio. Non aggiunge nulla agli ordini: l'ordine mostra il titolo del metodo e il costo di spedizione come qualsiasi altro metodo di spedizione di OpenCart. I prezzi in tempo reale vengono richiesti solo per gli indirizzi nigeriani. Per gli altri paesi usa la tabella dei prezzi.

Su OpenCart 4 il cliente clicca su Choose nel blocco dei metodi di spedizione della pagina di checkout e sceglie GIG Logistics nella finestra Shipping method options, dove l'opzione mostra il titolo del metodo e il prezzo, per esempio GIG Logistics - $4.50. Il metodo funziona allo stesso modo di OpenCart 3.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox GIG Logistics è il primo blocco di Extensions > Extensions > Shipping > VibeFox GIG Logistics > Edit, 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 si trovano la riga Product: opencart-shipping-gig-logistics 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 oppure License expired on con 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 dalla configurazione di OpenCart. Rimuovere la chiave dal negozio non libera il suo posto per il dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, il metodo di spedizione GIG Logistics non viene mostrato ai clienti al checkout e non viene calcolato alcun prezzo. Un amministratore che ha effettuato l'accesso al pannello nello stesso browser vede comunque il metodo nel negozio, contrassegnato con (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 dell'amministratore, quindi senza una chiave attiva il metodo è nascosto a tutti. Dopo aver aperto una volta la pagina Edit, nella Dashboard del pannello 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 controllato di nuovo 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

GIG Logistics non appare al checkout: verifica che la licenza sia attiva e che Enable/Disable sia attivo. Controlla la Geo zone, oppure Ignore shipping zones e Countries, i limiti di peso e il Minimum subtotal. Verifica che la tabella (il paese o *) o il Fallback cost diano un prezzo per il paese. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.

Il prezzo proviene dalla tabella, non da GIG Logistics: i prezzi in tempo reale richiedono nome utente e password API, Sender phone, città e stato di ritiro, un indirizzo di consegna in Nigeria con città o stato e, per i negozi la cui valuta predefinita non è il NGN, il Currency conversion rate. Controlla gli avvisi in cima alla pagina Edit. Attiva il Debug log, ricarica il checkout e controlla il campo Log nella pagina dell'estensione per vedere il motivo. Una richiesta non riuscita viene ripetuta dopo 10 minuti.

Accesso non riuscito nel registro: GIG Logistics ha rifiutato il nome utente o la password API. Controllali e verifica la Test mode: le credenziali di test funzionano solo con l'API di test. Salva le impostazioni per riprovare subito.

GIG Logistics non restituisce un prezzo: GIG calcola i prezzi in base alla distanza. Mantieni attivo Address lookup, oppure inserisci Pickup latitude e Pickup longitude. Conferma i prezzi con il tuo account GIG Logistics prima di andare in produzione.

L'avviso su città e stato di ritiro resta: scegli uno stato in State e compila City / area. La regione del negozio viene usata solo quando il paese del negozio in System > Settings > Store > Local è la Nigeria.

Sul prezzo GIG viene applicata un'imposta: imposta Tax class su No tax se il prezzo GIG include già tutto ciò che vuoi addebitare.

I prezzi sembrano obsoleti dopo una modifica: clicca su Save nella pagina dell'estensione. Questo cancella i prezzi, i token e le coordinate in cache.

La pagina dice "Warning: You do not have permission to modify VibeFox GIG Logistics!": il gruppo utenti amministratori potrebbe poter solo visualizzare le impostazioni. Concedi al gruppo il permesso di modifica per extension/shipping/vfd_gig_logistics (OpenCart 3) o extension/vfd_gig_logistics/shipping/vfd_gig_logistics (OpenCart 4) in System > Users > User Groups.

Per gli sviluppatori: l'indirizzo dell'API di GIG Logistics e quello della ricerca degli indirizzi possono essere sostituiti con le impostazioni vfd_gigl_api_base_url e vfd_gigl_geocode_url (per i test); non hanno campi nella pagina delle impostazioni.

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox GIG Logistics. 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. I prezzi, i token e le coordinate in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, vengono eliminate anche le altre impostazioni e il registro di debug. Se è disattivo, vengono conservate e riutilizzate quando reinstalli l'estensione. Gli ordini esistenti conservano il loro metodo di spedizione e il costo.

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

GIG Logistics è un marchio registrato del rispettivo titolare. Questa estensione non è affiliata a GIG Logistics né approvata da GIG Logistics.