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

Credenziali API di GIG Logistics (solo per le tariffe in tempo reale): le tariffe 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 tariffe e il costo di riserva, non ti servono credenziali API.

La Nigeria nel tuo negozio: le tariffe in tempo reale vengono richieste solo per gli indirizzi di consegna in Nigeria, quindi il paese Nigeria deve esistere ed essere attivo in International > Locations > Countries.

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 trova più tardi VibeFox GIG Logistics nell'elenco dei moduli e clicca su Configure.

3. Incolla la tua chiave di licenza VibeFox in License key, nel blocco licenza in cima alla pagina Configure, e clicca su Activate (vedi Chiave di licenza).

4. Compila la tabella tariffe e/o il costo di riserva. Per le tariffe in tempo reale, inserisci anche il nome utente e la password API, il telefono, la città e lo stato di ritiro, e il tasso di conversione valutaria se la tua valuta predefinita non è NGN (vedi Configurazione). Clicca su Save.

5. Se il campo Nigerian states mostra il pulsante Add Nigerian states, cliccalo (vedi Configurazione).

All'installazione il modulo crea il corriere GIG Logistics con il testo dei tempi di consegna Courier delivery. Il corriere viene collegato alla zona della Nigeria (in un negozio predefinito, Africa) e a tutti i gruppi di clienti. Puoi modificare zone, gruppi di clienti, tempi di consegna, logo e limiti di dimensione in Shipping > Carriers. Non impostare lì i prezzi: la tariffa arriva sempre dal modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox GIG Logistics > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella anche le tariffe GIG Logistics, i token API e le coordinate degli indirizzi in cache.

Sopra le sezioni, la pagina mostra avvisi quando le tariffe in tempo reale non possono essere usate: è inserito solo il nome utente o solo la password API, mancano Sender phone o la città o lo stato di ritiro, oppure la valuta predefinita non è NGN e non è impostato un Currency conversion rate. Compare anche un avviso se il corriere GIG Logistics non viene trovato, e se l'unità di peso del negozio (International > Localization > Local units) non è riconosciuta dal modulo, nel qual caso i pesi dei prodotti vengono letti come kg. Al salvataggio viene segnalato un numero errato (un importo negativo, un Currency conversion rate di 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, oppure una regola fiscale sconosciuta, e non viene salvato nulla.

General

Le impostazioni di questa pagina si applicano a tutte le zone del corriere.

Enable/Disable: 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 nel checkout. Predefinito: GIG Logistics. Obbligatorio.

Tax: la regola fiscale del corriere, oppure No tax. Una regola fiscale aggiunge la tua imposta sulla spedizione al costo. Scegli No tax se la tariffa GIG include già tutto ciò che vuoi addebitare.

GIG Logistics API (live prices) (facoltativo)

Con le credenziali API, la tariffa viene richiesta a GIG Logistics per ogni indirizzo in Nigeria. Senza credenziali, oppure quando l'API non restituisce una tariffa, vengono usate la tabella tariffe e il costo di riserva.

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

API password: la tua password API di terze parti di GIG Logistics. Serve solo per accedere all'API e non viene mai registrata. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarla. Per rimuovere la password, svuota API username e salva.

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

Currency conversion rate: GIG Logistics restituisce le tariffe in NGN. Se la valuta predefinita del tuo negozio non è NGN, indica quanto vale un NGN nella tua valuta predefinita (1 NGN = ? della tua valuta, per esempio 0.0006). Il tasso deve essere maggiore di 0. Senza di esso, le tariffe GIG in tempo reale non vengono usate. Se la tua valuta predefinita è NGN, il campo lo indica e non serve. Sono accettati sia il punto sia la virgola come separatore decimale.

Pickup (sender) address

Dove GIG Logistics ritira i pacchi, in Nigeria. Se il tuo negozio è in Nigeria, i campi vuoti di via, città e stato usano l'indirizzo del negozio da Shop Parameters > Contact > Stores.

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 le tariffe in tempo reale.

Street address: l'indirizzo stradale del ritiro.

City / area: la città o la zona del ritiro, per esempio Victoria Island. Obbligatorio per le tariffe in tempo reale.

State: lo stato nigeriano dell'indirizzo di ritiro, da scegliere tra i 37 stati. L'opzione predefinita, Shop state (Shop parameters > Contact > Stores), usa lo stato dell'indirizzo del negozio. Obbligatorio per le tariffe in tempo reale.

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

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

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

Nigerian states: lo stato dell'indirizzo di consegna viene inviato a GIG Logistics e alla ricerca degli indirizzi. PrestaShop non ha stati nigeriani di default; senza di essi si usano solo via e città. Il pulsante Add Nigerian states aggiunge i 37 stati (codici LA, FC e così via), attiva Contains states per la Nigeria e aggiunge il campo stato al modulo degli indirizzi nigeriani. Gli stati già esistenti (per codice o per nome) non vengono aggiunti due volte. Quando tutto è pronto, il campo mostra quanti stati hanno gli indirizzi nigeriani. Non cambia nulla finché non clicchi il pulsante.

Price table and fallback

Usata per gli altri paesi, quando le tariffe in tempo reale non sono configurate o quando GIG Logistics non restituisce una tariffa. Le tariffe sono nella valuta predefinita del tuo negozio, IVA esclusa.

Country prices: una tabella con una tariffa base per paese. Clicca su Add country per aggiungere una riga e sull'icona del cestino per rimuoverne una. Scegli * Any other country per tutti i paesi senza una riga propria. Le colonne XS (fino a 1 kg), S (fino a 2 kg), M (fino a 3 kg), L (fino a 5 kg) e XL (oltre 5 kg) sono tariffe facoltative per fascia di peso: una tariffa di fascia maggiore di 0 sostituisce la tariffa base per i carrelli di quella fascia. Una tariffa di 0 significa spedizione gratuita. Le celle delle tariffe vuote vengono salvate come 0, quindi compila la tariffa base per ogni riga che aggiungi. Se un paese compare due volte, viene mantenuta la riga successiva. I valori corretti sono elencati in un avviso dopo il salvataggio. I paesi senza riga (quando non esiste una riga *) non ricevono una tariffa dalla tabella.

Fallback cost: usato quando né GIG Logistics né la tabella forniscono una tariffa. Se vuoto, in quel caso il corriere viene nascosto.

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

Conditions

Free shipping from: il subtotale del carrello (prodotti che richiedono spedizione, dopo sconti, IVA esclusa) a partire dal quale la spedizione è gratuita. Se vuoto, non è mai gratuita.

Minimum subtotal: mostra il corriere solo quando il subtotale del carrello raggiunge questo importo. Se vuoto, è sempre mostrato.

Min weight (kg): il peso minimo del carrello in kg. I pesi dei prodotti vengono convertiti dall'unità di peso del tuo negozio. 0 significa nessun limite.

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

Availability without shipping zones

Ignore shipping zones: offre il corriere per i paesi indicati sotto, anche se le sue zone non li includono. Quando lo attivi, il corriere viene collegato a tutte le zone attive, e anche le zone create in seguito vengono collegate. Quando lo disattivi, il corriere riprende le sue zone precedenti.

Countries: i paesi di destinazione per questa modalità. Se vuoto, sono tutti i paesi verso cui spedisci. Usato solo con Ignore shipping zones.

Advanced

Debug log: scrive i calcoli delle tariffe in logs/vfd_gigl_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori API vengono sempre registrati, anche con il log disattivato. Non vengono scritte password, token o indirizzi dei clienti.

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

Remove data on uninstall: se attivo, disinstallando il modulo vengono eliminate le sue impostazioni, il corriere, le cache e i log. Se disattivo, tutto viene conservato per una reinstallazione. Gli ordini vengono sempre conservati.

Come funziona nel checkout

Nel passaggio di spedizione PrestaShop chiede al modulo la tariffa GIG Logistics. Contano solo i prodotti che richiedono spedizione: i prodotti virtuali non aggiungono peso e non sono inclusi nel subtotale. Il modulo 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, la tariffa è 0 e non viene inviata alcuna richiesta a GIG Logistics.

Poi la tariffa viene presa dalla prima fonte che ne fornisce una. Prima la tariffa GIG Logistics in tempo reale, se sono inserite le credenziali API, l'indirizzo è in Nigeria, l'indirizzo ha una città o uno stato, sono impostati telefono, città e stato di ritiro e, per i negozi con valuta predefinita diversa da NGN, è impostato un tasso di conversione. Il modulo accede all'API di GIG Logistics e invia gli indirizzi e le coordinate di ritiro e di consegna, oltre agli articoli del carrello con nomi, quantità, pesi e valori. I prodotti senza peso vengono inviati come 1 kg. La tariffa viene richiesta per la consegna in bici. Secondo, la tabella Country prices. Terzo, il Fallback cost. Se nessuna fonte fornisce una tariffa, il corriere viene nascosto per quel carrello. La tariffa viene calcolata nella valuta predefinita e poi mostrata nella valuta del carrello del cliente.

Ogni risposta di GIG è in cache per 1 ora, quindi lo stesso carrello non genera una nuova richiesta. Una richiesta o un accesso non riusciti sono in 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. Il timeout dell'API è di 10 secondi, quello della ricerca degli indirizzi di 5 secondi.

Se GIG Logistics restituisce un errore o una tariffa pari a zero, il cliente non vede alcun errore. Viene usata la tariffa della tabella o il costo di riserva, e l'errore viene scritto nel log di debug.

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

Il modulo calcola solo le tariffe. Non crea spedizioni, documenti di trasporto o etichette GIG Logistics, non prenota ritiri, non traccia i pacchi e non permette ai clienti di scegliere un centro di servizio. Gli ordini vengono spediti tramite il tuo account GIG Logistics come di consueto. Le tariffe in tempo reale vengono richieste solo per indirizzi nigeriani. Per gli altri paesi usa la tabella tariffe.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox GIG Logistics è il primo blocco di Modules > Module Manager > VibeFox GIG Logistics > Configure, 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 compaiono la riga Product: presta-shipping-gig-logistics e il link 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 o License expired on seguito da una data. Dopo una modifica dell'indirizzo del negozio, o dopo aver liberato uno slot di dominio nel tuo account, clicca 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: quello 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 GIG Logistics non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Il front office di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il corriere viene nascosto anche a te: puoi configurare il modulo prima di acquistare una chiave, ma non provarlo al checkout. Un promemoria compare in Modules > Module Manager, nella scheda Alerts. Gli ordini esistenti non sono interessati.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono il 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 a 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

GIG Logistics non compare nel checkout: verifica che la licenza sia attiva e che Enable/Disable 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 il Minimum subtotal. Verifica che la tabella (il paese o *) o il Fallback cost diano una tariffa per il paese. I prodotti possono anche essere limitati a certi corrieri nella pagina del prodotto.

La tariffa arriva dalla tabella, non da GIG Logistics: le tariffe in tempo reale richiedono nome utente e password API, Sender phone, città e stato di ritiro, un indirizzo di consegna nigeriano con città o stato e, per i negozi con valuta predefinita diversa da NGN, il Currency conversion rate. Controlla gli avvisi in cima alla pagina di configurazione. Attiva il Debug log, ricarica il checkout e guarda il campo Log nella pagina del modulo per scoprire il motivo. Una richiesta non riuscita viene ritentata dopo 10 minuti.

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

GIG Logistics non restituisce una tariffa: GIG calcola le tariffe in base alla distanza. Tieni attivo Address lookup, oppure inserisci Pickup latitude e Pickup longitude. Clicca su Add Nigerian states in modo che venga inviato anche lo stato di consegna. Verifica le tariffe 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. L'indirizzo del negozio viene usato solo quando il paese del negozio è la Nigeria, e lo stato del negozio è noto solo dopo aver aggiunto gli stati nigeriani e averne scelto uno in Shop Parameters > Contact > Stores.

L'imposta viene addebitata oltre la tariffa GIG: imposta Tax su No tax se la tariffa GIG include già tutto ciò che vuoi addebitare.

Le tariffe sembrano obsolete dopo una modifica: clicca su Save nella pagina del modulo. Questo cancella le tariffe, i token e le coordinate in cache.

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

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox GIG Logistics e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. Tariffe, token e coordinate degli indirizzi in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini conservano la loro cronologia) e vengono rimosse impostazioni e log. Se è disattivo, il corriere viene solo disabilitato e tutte le impostazioni vengono conservate. Reinstallando il modulo, il corriere salvato riprende il suo stato precedente. Gli stati nigeriani aggiunti con Add Nigerian states restano nel tuo negozio in entrambi i casi.

GIG Logistics è un marchio del rispettivo titolare. Questo modulo non è affiliato a GIG Logistics né approvato da essa.