VibeFox Loggi for PrestaShop — Guida
Requisiti
PrestaShop: da 8.0 a 9.x.
PHP: 8.0 o successivo. Il modulo non si installa su versioni PHP più vecchie.
Account Loggi (solo per i prezzi in tempo reale): il prezzo in tempo reale usa l'API GraphQL di Loggi con una chiave API che Loggi rilascia per gli account business. Chiedi al tuo account manager Loggi o al supporto integrazioni di Loggi (integracoes@loggi.com); vedi anche la documentazione API di Loggi su docs.api.loggi.com. Ti servono tre valori: l'e-mail del tuo account Loggi, la chiave API e l'ID numerico del tuo negozio. Se il tuo account Loggi ha solo credenziali per la nuova API della piattaforma REST di Loggi (client ID e secret), il prezzo in tempo reale non è disponibile e vengono usati i prezzi fissi. Se usi solo i prezzi fissi, non ti serve un account Loggi.
Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un 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 VibeFox Loggi più tardi nell'elenco dei moduli e clicca su Configure.
3. Inserisci la tua chiave di licenza VibeFox in License key, nel blocco licenza in alto nella pagina Configure, e clicca su Activate (vedi Chiave di licenza).
4. Inserisci l'e-mail dell'API Loggi, la chiave API, lo Shop ID e l'indirizzo di ritiro e, se la valuta predefinita del negozio non è BRL, il tasso di cambio BRL. Aggiungi prezzi fissi come rete di sicurezza (vedi Configurazione) e clicca su Save.
5. Aggiungi il Brasile alle zone del corriere Loggi in Shipping > Carriers, oppure attiva Ignore shipping zones e scegli i paesi.
All'installazione il modulo crea il corriere Loggi con il testo dei tempi di consegna Courier delivery in Brazil. Il corriere è assegnato a tutte le zone 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: il prezzo proviene sempre dal modulo.
Configurazione
Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Loggi > Configure. Si applicano a tutte le zone del corriere. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella anche i prezzi Loggi in cache.
Gli avvisi in cima alla pagina segnalano una configurazione incompleta: nessuna credenziale API (si usano solo i prezzi fissi), nessuna credenziale API e nessun prezzo fisso (il corriere non viene mai mostrato), nessun indirizzo di ritiro, nessun tasso di cambio BRL, oppure un'unità di peso o di dimensione del negozio che il modulo non riconosce (viene quindi conteggiata come kg o cm; imposta le unità in International > Localization). Se un valore non è valido, per esempio un numero negativo, la pagina mostra un errore e non salva nulla.
Generale
Enable Loggi: attiva o disattiva il corriere. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.
Method title: il nome del corriere mostrato al cliente nel carrello e al checkout. Predefinito: Loggi. Obbligatorio, massimo 64 caratteri.
API Loggi (prezzo in tempo reale) (lascia le credenziali vuote per usare solo i prezzi fissi)
API e-mail: l'e-mail del tuo account Loggi. La chiave API le appartiene. Deve essere un indirizzo e-mail valido.
API key: la tua chiave API Loggi. Viene inviata solo a Loggi e non viene mai registrata. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it; clear the API e-mail to remove it. Inserisci un nuovo valore solo per cambiarla. Se modifichi API e-mail, inserisci anche la chiave API per la nuova e-mail, altrimenti la pagina mostra un errore e non salva nulla. Per rimuovere la chiave salvata, svuota API e-mail e salva.
Shop ID: l'ID numerico (pk) del tuo negozio nella dashboard Loggi. Viene accettato solo un numero positivo. Un altro valore viene rifiutato con un errore.
Staging: usa l'ambiente di staging di Loggi con credenziali di test. Staging e produzione hanno account e chiavi diversi. Predefinito: disattivato.
Pickup address: dove Loggi ritira i pacchi, su una riga: via e numero civico, quartiere, città, stato e CEP, per esempio Rua Example, 123 - Bairro, São Paulo - SP, 01310-100. Lascialo vuoto per usare l'indirizzo del negozio da Shop Parameters > Contact > Stores, se è in Brasile e ha indirizzo e città. Senza un indirizzo di ritiro Loggi non può stimare e si usano solo i prezzi fissi.
BRL exchange rate: i prezzi Loggi sono in real brasiliani. Se la valuta predefinita del tuo negozio è BRL, questo campo non serve e la pagina lo indica. Altrimenti inserisci quanto vale 1 BRL nella valuta del tuo negozio, per esempio 0.16. Senza di esso i prezzi in tempo reale non vengono usati. Viene accettato solo un numero positivo. Sono accettati sia il punto sia la virgola come separatore decimale.
Prezzi fissi (nella valuta predefinita del negozio, IVA esclusa)
I prezzi fissi vengono usati quando l'API Loggi non è configurata, per destinazioni fuori dal Brasile o senza un CEP completo, e ogni volta che Loggi non restituisce un prezzo (API non disponibile, chiave rifiutata, indirizzo fuori copertura).
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 tutti i paesi senza una riga propria. Ogni riga ha un Base price e colonne di peso: 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. Sono accettati sia "9.99" sia "9,99". Le righe vuote e una seconda riga per lo stesso paese vengono eliminate al salvataggio.
Price for countries not in the table: usato quando non c'è un prezzo Loggi in tempo reale e la tabella non ha una riga per il paese di destinazione (né una riga *). Lascialo vuoto per nascondere il corriere in quel caso.
Fixed price applies: il modo in cui vengono conteggiati i prezzi fissi. Un prezzo Loggi in tempo reale copre già l'intero carrello e non viene mai moltiplicato.
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 weight non può essere maggiore di Maximum weight.
Minimum order amount: mostra il corriere solo quando il subtotale del carrello (dopo gli sconti, IVA esclusa) raggiunge questo importo. Lascialo vuoto per mostrarlo sempre.
Free shipping from: il subtotale del carrello (dopo gli sconti, IVA esclusa) da cui la spedizione Loggi è gratuita. Lascialo vuoto per nessuna spedizione gratuita.
Tax: la regola fiscale del corriere, oppure No tax. Scegli No tax se i tuoi prezzi e il prezzo Loggi includono già le imposte.
Per i limiti di peso e le colonne di peso, un prodotto senza peso conta come 0 kg.
Disponibilità senza zone di spedizione
Ignore shipping zones: offri Loggi per i paesi indicati di seguito, indipendentemente dalla zona corrispondente. Se salvi con questa opzione attiva, il corriere viene aggiunto a tutte le zone, comprese quelle create in seguito. Disattivarla rimuove quelle zone aggiunte, così il corriere riprende le proprie zone.
Countries: i paesi di destinazione per questa modalità. Lascialo vuoto per consentire tutti i paesi attivi del tuo negozio. Questo campo viene usato solo se Ignore shipping zones è attivo.
Avanzate
Debug log: scrive i calcoli dei prezzi e le richieste a Loggi in logs/vfd_lggi_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Gli errori dell'API vengono sempre registrati, anche con questa opzione disattivata. La chiave API e gli indirizzi dei clienti non vengono mai registrati.
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 impostazioni Loggi, il corriere, i prezzi in cache e i log. Se disattivo, tutto viene conservato per una reinstallazione.
Come funziona al checkout
Al passaggio della spedizione PrestaShop chiede al modulo il prezzo Loggi. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nell'importo dell'ordine. Il modulo controlla prima le condizioni: paesi consentiti (con Ignore shipping zones), peso del carrello e importo minimo dell'ordine. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata alcuna richiesta a Loggi.
Per un indirizzo in Brasile con un CEP completo di 8 cifre, il modulo crea pacchi Loggi: ogni articolo viene ruotato in modo che il lato più corto sia l'altezza, e gli articoli vengono impilati in un unico pacco finché resta entro 55 × 55 × 55 cm e 20 kg. I prodotti senza peso o dimensioni contano come 1 cm per lato, e ogni pacco pesa almeno 100 g. Loggi accetta 2 pacchi per stima, quindi i carrelli più grandi vengono inviati con più richieste e i totali vengono sommati. Il modulo invia a Loggi il tuo Shop ID, l'indirizzo di ritiro, l'indirizzo di consegna e i pacchi, e converte il totale Loggi da BRL nella valuta predefinita del tuo negozio. Il prezzo viene poi mostrato nella valuta del carrello del cliente.
Ogni prezzo Loggi è memorizzato in cache per 1 ora per carrello, indirizzo, account e ambiente, così lo stesso carrello non genera una nuova richiesta. Una stima non riuscita viene memorizzata in cache per 10 minuti. Se Loggi non è raggiungibile del tutto, le richieste vengono sospese per 2 minuti, così il checkout non attende Loggi a ogni aggiornamento. Il timeout dell'API è di 10 secondi.
Al posto di ciò si usano i prezzi fissi quando l'API non è configurata, l'indirizzo è fuori dal Brasile o non ha ancora un CEP completo, manca il tasso di cambio BRL, non c'è un indirizzo di ritiro, un prodotto è più grande di un pacco Loggi, il carrello richiede più di 10 pacchi, oppure Loggi restituisce un errore, un pacco rifiutato, un indirizzo fuori copertura o un totale pari a zero. Se non c'è nemmeno un prezzo fisso, il corriere viene nascosto. Il cliente non vede mai un errore dell'API. Il motivo viene scritto nel log di debug.
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 i prezzi. Non crea ordini o spedizioni Loggi, non stampa etichette, non traccia i pacchi, non mostra i tempi di consegna al checkout e non offre punti di ritiro o armadietti. Crea le spedizioni nella dashboard Loggi. Loggi consegna solo in Brasile. Usa i prezzi fissi per gli altri paesi.
Chiave di licenza
Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Loggi è il primo blocco in Modules > Module Manager > VibeFox Loggi > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (ad 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-loggi e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo chi ha il permesso Configure per il modulo può modificare 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, ad 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 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 Loggi non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Lo storefront 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 puoi 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 un rinnovo. Lo stato viene ricontrollato 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
Loggi non appare al checkout: verifica che la licenza sia attiva e che Enable Loggi sia attivo. In Shipping > Carriers verifica che il corriere copra la zona del paese del cliente e il suo gruppo di clienti (oppure che Ignore shipping zones sia attivo e il paese consentito). Controlla gli avvisi in cima alla pagina del modulo, i limiti di peso e Minimum order amount. Se il cliente non ha ancora inserito un CEP completo o Loggi non restituisce alcun prezzo, il corriere ha bisogno di un prezzo fisso: una riga per il paese, una riga * oppure Price for countries not in the table. I prodotti possono anche essere limitati a determinati corrieri nella pagina del prodotto.
Vengono mostrati solo i prezzi fissi: controlla il campo Log nella pagina del modulo. Gli errori vengono sempre registrati. Attiva Debug log per ogni passaggio e ricarica il checkout. Motivi tipici: e-mail, chiave o Shop ID dell'API mancanti, nessun indirizzo di ritiro, nessun BRL exchange rate per una valuta del negozio diversa da BRL, nessun CEP completo di 8 cifre ancora, un prodotto più grande di 55 cm o più pesante di 20 kg, oppure un indirizzo fuori dalla copertura Loggi.
HTTP 401 o 403 nel log: Loggi ha rifiutato l'e-mail o la chiave API. Verificale con Loggi e controlla che Staging corrisponda alle credenziali: le chiavi di staging e di produzione sono diverse.
Il mio negozio vende in euro o dollari: Loggi risponde in BRL. Inserisci il BRL exchange rate (quanto vale 1 BRL nella valuta predefinita del tuo negozio). I prezzi fissi sono sempre nella valuta predefinita del negozio.
I prezzi non sono precisi: compila peso e dimensioni dei tuoi prodotti. Senza questi dati, i prodotti contano come 1 cm per lato e ogni pacco come minimo 100 g.
Per item non moltiplica il prezzo Loggi: è voluto. Un prezzo Loggi in tempo reale copre l'intero carrello. Per item si applica solo ai prezzi fissi.
I prezzi sembrano non aggiornati dopo una modifica: clicca su Save nella pagina del modulo. Così si cancellano i prezzi Loggi in cache.
La pagina dice che il corriere Loggi non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Ripristina il modulo in Modules > Module Manager per crearlo di nuovo.
Disinstallazione
Vai su Modules > Module Manager, apri il menu accanto a VibeFox Loggi e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. I prezzi Loggi in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini conservano la cronologia) e le impostazioni e il log vengono rimossi. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni vengono conservate. Reinstallando il modulo, il corriere salvato riprende lo stato che aveva prima della disinstallazione.
Loggi è un marchio del rispettivo proprietario. Questo modulo non è affiliato a Loggi né approvato da Loggi.