VibeFox Loggi 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.
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 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 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 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. Puoi anche caricare la cartella vfd_loggi in /wp-content/plugins/ via FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox Loggi, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugins.
4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.
5. Inserisci l'e-mail dell'API Loggi, la chiave API, lo Shop ID e l'indirizzo di ritiro e, se la valuta del tuo negozio non è BRL, il tasso di cambio BRL. Aggiungi prezzi fissi come rete di sicurezza (vedi Configurazione).
6. Aggiungi VibeFox Loggi a una zona di spedizione per il Brasile in WooCommerce > Settings > Shipping > Shipping zones, oppure attiva Ignore shipping zones e scegli i paesi.
Configurazione
Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox Loggi. Si applicano a tutte le zone di spedizione. Quando aggiungi il metodo a una zona, la finestra della zona ha un solo campo:
Title (zone): il nome che il cliente vede per questa zona. Lascialo vuoto per usare il Method title globale.
Gli avvisi in cima alla pagina segnalano una configurazione incompleta: nessuna credenziale API, nessun indirizzo di ritiro o nessun tasso di cambio BRL. Ogni volta che salvi le impostazioni, i prezzi Loggi in cache vengono cancellati.
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: Loggi.
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 appartiene a questo account.
API key: la tua chiave API Loggi. Viene inviata solo a Loggi e non viene mai registrata.
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 e resta quello salvato.
Staging: usa l'ambiente di staging di Loggi con credenziali di prova. 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 WooCommerce > Settings > General se si trova in Brasile. Senza un indirizzo di ritiro Loggi non può stimare e vengono usati solo i prezzi fissi.
BRL exchange rate: i prezzi Loggi sono in real brasiliani. Se la valuta del tuo negozio è BRL, questo campo non serve. 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. Sono accettati sia il punto sia la virgola come separatore decimale.
Prezzi fissi (nella valuta del tuo negozio)
I prezzi fissi vengono usati quando l'API 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. Fai clic su + Add country per aggiungere una riga e sulla croce 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. Prezzo base 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 metodo in quel caso.
Fixed price applies: il modo in cui si calcolano 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 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. Lascialo vuoto per mostrarlo sempre.
Free shipping from: il subtotale del carrello (dopo gli sconti, prima delle imposte) a partire dal quale la spedizione Loggi è gratuita. Lascialo vuoto se non c'è spedizione gratuita.
Excluded shipping classes: nasconde il metodo quando il carrello contiene un prodotto di una qualsiasi 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 tuoi prezzi e il prezzo Loggi includono già le imposte.
Disponibilità senza zone di spedizione
Ignore shipping zones: offre Loggi per i paesi indicati di seguito, anche se il metodo non è aggiunto a nessuna zona di spedizione.
Countries: i paesi di destinazione per questa modalità. Lascialo vuoto per usare tutti i paesi verso cui spedisci. Questo campo viene usato solo quando Ignore shipping zones è attivo.
Avanzate
Debug log: registra ogni calcolo della tariffa e ogni richiesta a Loggi in WooCommerce > Status > Logs (origine vfd-loggi). Gli errori dell'API vengono sempre registrati, anche con questa opzione disattivata. La chiave API e gli indirizzi dei clienti non vengono mai registrati.
Remove data on uninstall: se attiva, eliminando il plugin vengono rimosse tutte le impostazioni Loggi e i metodi nelle zone. Disattivare il plugin non elimina mai le impostazioni.
Come funziona al checkout
Quando il cliente inserisce un indirizzo di consegna, WooCommerce chiede al plugin una tariffa. Il plugin controlla 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 Loggi.
Per un indirizzo in Brasile con un CEP completo di 8 cifre, il plugin costruisce i 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 plugin invia a Loggi il tuo Shop ID, l'indirizzo di ritiro, l'indirizzo di consegna e i pacchi, converte il totale Loggi da BRL nella valuta del tuo negozio e lo mostra.
Ogni prezzo Loggi viene 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 Loggi vengono usati 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, 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 esiste nemmeno un prezzo fisso, il metodo viene nascosto. Il cliente non vede mai un errore dell'API. Il motivo viene scritto nel registro.
Il metodo funziona con il checkout classico e con i blocchi Carrello e Checkout. È compatibile con WooCommerce High-Performance Order Storage (HPOS).
Il plugin calcola solo i prezzi. Non crea ordini o spedizioni Loggi, non stampa etichette, non traccia i pacchi, non mostra il tempo di consegna al checkout e non offre punti di ritiro o armadietti. Crea le spedizioni nella dashboard Loggi. Loggi consegna solo in Brasile. Per gli altri paesi usa i prezzi fissi.
Chiave di licenza
Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza si trova in cima a WooCommerce > Settings > Shipping > VibeFox Loggi. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, per esempio la data fino a cui la licenza è attiva e il tuo dominio. Usa Check now per ricontrollare 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 il suo posto per il dominio. Libera il posto nel tuo account vibefox.net.
Senza una chiave attiva, Loggi non viene mostrato ai clienti al checkout. I gestori del negozio con accesso effettuato lo vedono ancora, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Sulla pagina Plugins e sulle 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 un rinnovo. Lo stato viene ricontrollato automaticamente in background.
Risoluzione dei problemi
Loggi non compare al checkout: verifica 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 consentito). Controlla gli avvisi in cima alla pagina delle impostazioni, i limiti di peso, Minimum order amount e Excluded shipping classes. 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.
Vengono mostrati solo i prezzi fissi: apri WooCommerce > Status > Logs, origine vfd-loggi. Gli errori vengono sempre registrati. Attiva Debug log per vedere ogni passaggio. 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, un prodotto più lungo di 55 cm o più pesante di 20 kg, oppure un indirizzo fuori dalla copertura di Loggi.
HTTP 401 o 403 nel registro: Loggi ha rifiutato l'e-mail o la chiave API. Verificali 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 del tuo negozio). I prezzi fissi sono sempre nella valuta del tuo 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 obsoleti dopo una modifica: salva la pagina delle impostazioni. Così vengono cancellati i prezzi Loggi in cache.
Il blocco della licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera un posto 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 tutte le impostazioni. Vengono cancellati solo i prezzi Loggi in cache. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin e i prezzi in cache vengono sempre rimossi. Impostazioni e metodi nelle zone vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano per una reinstallazione futura. Gli ordini esistenti mantengono le loro righe di spedizione.
Loggi è un marchio di proprietà del rispettivo titolare. Questo plugin non è affiliato a Loggi né approvato da Loggi.