VibeFox Loggi for OpenCart — Guida

Requisiti

OpenCart: 3.0.x (testato su 3.0.5.0) oppure 4.0.2 e successive (testato su 4.1.0.3).

PHP: 8.0 o successivo.

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. Chiedila al tuo account manager Loggi o al supporto integrazioni di Loggi (integracoes@loggi.com); vedi anche la documentazione dell'API Loggi su docs.api.loggi.com. 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 credenziali solo per la nuova API della piattaforma REST di Loggi (client ID e secret), il prezzo in tempo reale non è disponibile e si usano 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

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_loggi-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_loggi.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. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_loggi-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non serve aggiornare Extensions > Modifications. Invece dell'Installer puoi copiare il contenuto della cartella upload di questo pacchetto nella cartella principale del tuo negozio.

2. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox Loggi e clicca su Install (il pulsante verde +).

3. Clicca su Edit (il pulsante a forma di matita) per aprire la pagina delle impostazioni.

4. Incolla la tua chiave di licenza VibeFox in License key, nel blocco della licenza in alto nella pagina Edit, e clicca su Activate (vedi Chiave di licenza).

5. Inserisci l'e-mail API di Loggi, la chiave API, l'ID del negozio 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), attiva Enable Loggi e clicca su Save.

OpenCart 4

1. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_loggi.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 ad esso.

3. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox Loggi, 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 gli stessi in entrambe le versioni.

All'installazione l'estensione crea una piccola tabella per i prezzi Loggi in cache. Il metodo è disattivato finché non attivi Enable Loggi e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni Loggi che hai conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox Loggi > Edit. Le sezioni sono elencate a sinistra. Valgono per tutte le zone geografiche. Un pulsante Save in fondo salva tutta la pagina senza ricaricarla. Ogni salvataggio cancella anche i prezzi Loggi in cache. Se un valore non è valido, per esempio un numero negativo, un'e-mail non corretta o un ID negozio che non è un numero, la pagina mostra un errore e non viene salvato nulla. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.

Gli avvisi sopra le impostazioni (mostrati di nuovo dopo ogni salvataggio) segnalano una configurazione incompleta: nessuna credenziale API (si usano solo i prezzi fissi), nessuna credenziale API e nessun prezzo fisso (il metodo non viene mai mostrato), nessun indirizzo di ritiro o nessun tasso di cambio BRL. Un altro avviso compare quando il negozio non ha una classe di peso con l'unità kg o una classe di lunghezza con l'unità cm e l'unità della classe predefinita non è riconosciuta. I pesi dei prodotti vengono allora contati come kg e le dimensioni come cm. Aggiungi le classi in System > Localisation > Weight Classes e Length Classes.

Generale

Enable Loggi: mostra o nasconde Loggi al checkout. Predefinito: disattivato.

Method title: il nome del metodo di spedizione mostrato al cliente nel carrello e al checkout. Predefinito: Loggi. Obbligatorio, massimo 64 caratteri, senza i caratteri < > ; = # { }.

Sort order: la posizione di Loggi tra i metodi di spedizione al checkout. Un numero intero.

API Loggi (prezzo in tempo reale) (lascia vuote le credenziali 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. Cancellarla cancella anche la chiave API salvata.

API key: la tua chiave API Loggi. Viene inviata solo a Loggi e non viene mai registrata nei log. 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 cambi API e-mail, inserisci anche la chiave API per la nuova e-mail, altrimenti la pagina mostra un errore e non viene salvato nulla.

Shop ID: l'ID numerico (pk) del tuo negozio nella dashboard di Loggi, per esempio 12345. Qualsiasi 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 sola riga: via e numero civico, quartiere, città, stato e CEP, per esempio Rua Example, 123 - Bairro, São Paulo - SP, 01310-100. Obbligatorio per i prezzi in tempo reale: l'indirizzo del negozio in OpenCart è testo libero e non viene mai usato al suo posto. 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 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 di Loggi non è configurata, per destinazioni al di fuori del 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 sul pulsante di rimozione per eliminarne una. Scegli * All other countries per tutti i paesi senza una riga propria. Ogni riga ha un Base price e colonne di peso: 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. 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: viene usato quando non c'è un prezzo Loggi in tempo reale e la tabella non ha una riga per il paese di destinazione (e non c'è una riga *). Lascialo vuoto per nascondere il metodo 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 (kg): nasconde il metodo quando il peso del carrello è inferiore a questo valore. 0 significa nessun limite (predefinito).

Maximum weight (kg): nasconde il metodo quando il peso del carrello è superiore a questo valore. Predefinito: 30. 0 significa nessun limite. Minimum weight non può essere maggiore di Maximum weight.

Minimum order amount: mostra il metodo solo quando il subtotale dei prodotti che richiedono spedizione (dopo il coupon, prima delle imposte) raggiunge questo importo. Lascialo vuoto per mostrarlo sempre.

Free shipping from: il subtotale dei prodotti che richiedono spedizione (dopo il coupon, prima delle imposte) a partire dal quale la spedizione Loggi è gratuita. Lascialo vuoto se non c'è spedizione gratuita.

Tax class: la classe fiscale del costo di spedizione, oppure No tax (predefinito). Scegli No tax se i tuoi prezzi e il prezzo Loggi includono già le imposte.

Geo zone: offri Loggi solo per gli indirizzi in questa zona geografica. All zones (predefinito) significa nessun limite. Le zone geografiche si gestiscono in System > Localisation > Geo Zones. La zona geografica non viene verificata quando Ignore shipping zones è attivo.

Per i limiti di peso e le colonne di peso, un prodotto senza peso conta come 0 kg.

Paesi

OpenCart non ha zone dei corrieri: la Geo zone limita il metodo agli indirizzi di una zona geografica. Puoi invece attivare Ignore shipping zones e scegliere un elenco di paesi.

Ignore shipping zones: offri Loggi per i paesi qui sotto, indipendentemente dalla Geo zone. La zona geografica non viene verificata in questa modalità. Predefinito: disattivato.

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

Avanzate

Debug log: scrive i calcoli delle tariffe e le richieste a Loggi in storage/logs/vfd_lggi_debug.log.php (su OpenCart 4 system/storage/logs/vfd_lggi_debug.log.php). Il file non può essere letto 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. Quando il file raggiunge 5 MB, viene spostato in vfd_lggi_debug.old.log.php e ne viene avviato uno nuovo.

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 l'estensione vengono cancellate le impostazioni di Loggi e il log. Se disattivo (predefinito), le impostazioni vengono conservate per una reinstallazione. I prezzi in cache vengono sempre rimossi.

Importa / Esporta

Export: clicca su Download JSON per salvare le impostazioni come file JSON. La chiave API non viene esportata.

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

Funzionamento al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di Loggi. Se è impostata una Geo zone, Ignore shipping zones è disattivato e l'indirizzo è al di fuori della zona geografica, Loggi non viene offerto. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non sono inclusi nell'importo dell'ordine. L'estensione controlla poi le condizioni: paesi consentiti (con Ignore shipping zones), peso del carrello e importo minimo dell'ordine. L'importo dell'ordine è il prezzo dei prodotti che richiedono spedizione, dopo lo sconto del coupon e prima delle imposte. Buoni regalo, punti fedeltà e credito del negozio non vengono considerati. 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, l'estensione costruisce i colli Loggi: ogni articolo viene ruotato in modo che il suo lato più corto sia l'altezza, e gli articoli vengono impilati in un unico collo finché resta entro 55 × 55 × 55 cm e 20 kg. I prodotti senza peso o dimensioni contano come 1 cm per lato, e ogni collo pesa almeno 100 g. Loggi accetta 2 colli per stima, quindi i carrelli più grandi vengono inviati con più richieste e i totali vengono sommati. L'estensione invia a Loggi l'ID del tuo negozio, l'indirizzo di ritiro, l'indirizzo di consegna (via, città, stato e CEP) e i colli, e converte il totale Loggi da BRL nella valuta predefinita del negozio. Il prezzo viene arrotondato alle cifre decimali di quella valuta e mostrato al cliente nella sua valuta con l'imposta della Tax class selezionata.

Ogni prezzo Loggi viene memorizzato nella 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 nella cache per 10 minuti. Se Loggi non è raggiungibile, le richieste vengono sospese per 2 minuti, così il checkout non attende Loggi a ogni aggiornamento. Il timeout dell'API è di 10 secondi.

I prezzi fissi vengono usati al loro posto quando l'API non è configurata, l'indirizzo è al di fuori del 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 collo Loggi, il carrello richiede più di 10 colli, oppure Loggi restituisce un errore, un collo rifiutato, un indirizzo fuori copertura o un totale pari a zero. Se non c'è nemmeno un prezzo fisso, il metodo viene nascosto. Il cliente non vede mai un errore dell'API. Il motivo viene scritto nel log di debug.

Su OpenCart 4 il cliente clicca su Choose nel blocco del metodo di spedizione della pagina di checkout e sceglie Loggi nella finestra Shipping method options. Il metodo funziona come su OpenCart 3.

L'estensione 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. 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. Crea le spedizioni nella dashboard di Loggi. Loggi consegna solo in Brasile. Usa i prezzi fissi per gli altri paesi.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco della licenza License — VibeFox Loggi è il primo blocco in Extensions > Extensions > Shipping > VibeFox Loggi > 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 di essi ci sono la riga Product: opencart-shipping-loggi 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 uno slot di 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 dominio: l'indirizzo del negozio dalla configurazione di OpenCart. 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 metodo di spedizione Loggi non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Un utente amministratore che ha effettuato l'accesso all'amministrazione nello stesso browser vede comunque il metodo nel negozio, contrassegnato come (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 dell'amministrazione compare un promemoria. Chiudilo con × per nasconderlo per 7 giorni. Gli ordini esistenti non vengono modificati.

Quando una licenza scade, l'estensione continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene controllato di nuovo automaticamente quando apri la Dashboard dell'amministrazione o la pagina Edit: 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 l'estensione rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Loggi non compare al checkout: verifica che la licenza sia attiva e che Enable Loggi sia attivo. Controlla Geo zone, Ignore shipping zones e Countries, gli avvisi in alto nella pagina dell'estensione, i limiti di peso e Minimum order amount. Se il cliente non ha ancora inserito un CEP completo o Loggi non restituisce un prezzo, il metodo ha bisogno di un prezzo fisso: una riga per il paese, una riga * oppure Price for countries not in the table. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.

Vengono mostrati solo i prezzi fissi: guarda il campo Log nella pagina dell'estensione. Gli errori vengono sempre registrati. Attiva il Debug log per ogni passaggio e ricarica il checkout. Motivi tipici: e-mail, chiave o ID negozio 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, un prodotto più grande di 55 cm o più pesante di 20 kg, oppure un indirizzo fuori dalla copertura di 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 di essi, i prodotti contano come 1 cm per lato e ogni collo come almeno 100 g.

Per articolo 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 obsoleti dopo una modifica: clicca su Save nella pagina dell'estensione. Questo cancella i prezzi Loggi in cache.

La pagina dice "Warning: You do not have permission to modify VibeFox Loggi!": il tuo gruppo utenti amministratori può solo visualizzare le impostazioni. Concedi al gruppo il permesso di modifica per extension/shipping/vfd_loggi (per OpenCart 3) oppure extension/vfd_loggi/shipping/vfd_loggi (per OpenCart 4) in System > Users > User Groups.

Per gli sviluppatori: l'indirizzo dell'API di Loggi può essere sostituito con l'impostazione vfd_lggi_api_url (per i test); non ha un campo nella pagina delle impostazioni.

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox Loggi. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable Loggi, Sort order, Tax class e Geo zone. I prezzi Loggi in cache (con la loro tabella) vengono sempre rimossi. Se Remove data on uninstall è attivo, vengono cancellate anche le impostazioni di Loggi e il log di debug. Se è disattivo, le altre impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. Gli ordini esistenti mantengono il loro metodo di spedizione e il loro 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 Loggi nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per rimuovere il pacchetto caricato.

Loggi è un marchio del suo rispettivo proprietario. Questa estensione non è affiliata né approvata da Loggi.