VibeFox Melhor Envio for WooCommerce — Guida
Requisiti
WordPress: 5.8 o successivo.
WooCommerce: 7.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.
PHP: 8.0 o successivo.
Account Melhor Envio (solo per le tariffe in tempo reale): le tariffe in tempo reale richiedono un token di accesso. Nel tuo account Melhor Envio apri la pagina dei permessi di accesso per i token (Integrações > Permissões de acesso, melhorenvio.com.br/painel/gerenciar/tokens) e genera un token con il permesso «shipping-calculate». Per i test, genera un token nella sandbox di Melhor Envio (sandbox.melhorenvio.com.br/painel/gerenciar/tokens). I token di produzione e di sandbox sono diversi. I token scadono. Non c'è un pulsante «connetti»: incolli il token nelle impostazioni. Senza token il metodo usa i prezzi di riserva.
Chiave di licenza VibeFox: si acquista 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 clicca su Install Now. Puoi anche caricare la cartella vfd_melhor_envio in /wp-content/plugins/ via FTP.
2. Clicca su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox Melhor Envio, oppure clicca su Settings sotto il nome del plugin nella pagina Plugin.
4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e clicca su Activate.
5. Incolla il token di accesso, la tua e-mail di contatto e il CEP di origine. Se la valuta del negozio non è BRL, imposta il BRL exchange rate. Facoltativamente, compila la tabella dei prezzi di riserva (per esempio per il Brasile) oppure un costo di riserva.
6. Aggiungi una zona per il Brasile in WooCommerce > Settings > Shipping > Shipping zones e aggiungi VibeFox Melhor Envio, oppure attiva Ignore shipping zones e scegli i paesi.
Configurazione
Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox Melhor Envio. Valgono per tutte le zone di spedizione. Quando aggiungi il metodo a una zona, la finestra della zona ha un solo campo:
Title (zone): il nome di questa opzione al checkout. Lascialo vuoto per usare il Name globale.
Gli avvisi in cima alla pagina segnalano una configurazione incompleta: un CEP di origine che non ha 8 cifre, un'e-mail di contatto mancante, un tasso di cambio BRL mancante, l'ultimo errore dell'API di Melhor Envio con la sua data, oppure nessun token e nessun prezzo di riserva. Ogni volta che salvi le impostazioni, le tariffe in cache vengono svuotate.
Generale
Enable/Disable: attiva o disattiva la spedizione Melhor Envio in tutte le zone contemporaneamente.
Name: il nome del metodo di spedizione mostrato ai clienti al checkout. Predefinito: Melhor Envio.
Tax status: Taxable aggiunge l'imposta di WooCommerce al costo di spedizione, None non la aggiunge.
API Melhor Envio
Access token: il token dell'ambiente selezionato qui sotto. Non viene mai scritto nel log.
Sandbox: usa la sandbox di Melhor Envio (sandbox.melhorenvio.com.br) per i test. Usala con un token sandbox. Predefinito: disattivato.
Contact e-mail: un'e-mail di contatto tecnico, inviata a Melhor Envio con ogni richiesta. Melhor Envio la richiede da ogni integrazione.
Origin CEP: il CEP (8 cifre) da cui vengono spediti i pacchi, per esempio 01310-100. Senza un CEP di origine valido non viene richiesta alcuna tariffa.
Services: ID dei servizi di Melhor Envio da quotare, facoltativi e separati da virgole, per esempio 1 = Correios PAC, 2 = Correios SEDEX, 17 = Correios Mini Envios, 3 = Jadlog .Package, 4 = Jadlog .Com. Lascialo vuoto per quotare tutti i servizi del tuo account.
Quotes at checkout: come vengono mostrate le tariffe.
Delivery time: mostra accanto al nome la stima dei tempi di consegna di Melhor Envio, per esempio «(3-5 business days)». Predefinito: attivo.
Declared value: dichiara il valore del prodotto (assicurazione) nelle tariffe. Quando è disattivato, le tariffe vengono richieste senza valore dichiarato: costano meno, ma i pacchi non sono assicurati. Predefinito: attivo.
BRL exchange rate: Melhor Envio calcola le tariffe in real brasiliani. Serve solo se la valuta del tuo negozio non è BRL: inserisci il prezzo di 1 BRL nella valuta del negozio, per esempio 0.17. Senza di esso le tariffe in tempo reale non vengono usate. Il valore dichiarato viene convertito in BRL con lo stesso tasso.
Default product weight (kg): usato per i prodotti senza peso, sia nelle tariffe sia nei limiti di peso. Predefinito: 0.3.
Default product size (cm): lunghezza x larghezza x altezza usate per i prodotti senza dimensioni. Predefinito: 16x11x5.
Fallback prices (nella valuta del tuo negozio)
I prezzi di riserva vengono usati quando manca il token, manca il CEP di destinazione o l'API non restituisce alcuna tariffa (errore, timeout, nessuna copertura).
Fallback price table: prezzo per paese e peso del carrello. Clicca su + Add country per aggiungere una riga e sulla croce per rimuoverne una. Scegli * Any country per tutti i paesi senza una riga propria. Ogni riga ha un Price e le colonne di peso: XS fino a 1 kg, S 1-2 kg, M 2-3 kg, L 3-5 kg e XL oltre 5 kg. Una colonna vuota o a 0 usa il Price. Sono accettati sia «9.99» sia «9,99». I valori che non sono numeri vengono segnalati dopo il salvataggio e ignorati.
Fallback cost: usato quando anche la tabella non ha un prezzo. Lascialo vuoto per nascondere il metodo in quel caso.
Fallback calculation: Per order addebita il prezzo di riserva una sola volta. Per item (each item priced by its own weight x quantity) cerca il prezzo di riserva per il peso di ogni articolo (il peso predefinito se non ne ha) e lo moltiplica per la sua quantità. Vale solo per i prezzi di riserva. Le tariffe di Melhor Envio includono già tutti gli articoli.
Availability
Min weight (kg): nasconde il metodo quando il carrello pesa meno. 0 significa nessun limite.
Max weight (kg): nasconde il metodo quando il carrello pesa di più. Predefinito: 30. 0 significa nessun limite.
Minimum subtotal: mostra il metodo solo se il subtotale del carrello (dopo gli sconti, prima delle tasse) è almeno questo importo. Lascialo vuoto per mostrarlo sempre.
Free shipping from: il subtotale del carrello da cui la spedizione è gratuita. Con un'opzione per servizio, diventa gratuito solo il servizio più economico. I servizi più veloci mantengono il loro prezzo. Lascialo vuoto per disattivare.
Excluded shipping classes: nasconde il metodo quando il carrello contiene articoli di una qualsiasi di queste classi di spedizione di WooCommerce.
Ignore shipping zones: offre il metodo per i paesi indicati qui sotto, anche se non è aggiunto a una zona di spedizione.
Countries: i paesi di destinazione per questa modalità. Lascialo vuoto per tutti i paesi. Questo campo viene usato solo quando Ignore shipping zones è attivo.
Avanzate
Debug log: registra le richieste all'API e il calcolo delle tariffe in WooCommerce > Status > Logs (origine vfd-melhor-envio). Gli errori vengono sempre registrati, anche con questa opzione disattivata. Il token e gli indirizzi dei clienti non vengono mai registrati.
Remove data on uninstall: se attivo, eliminando il plugin vengono rimosse tutte le sue impostazioni e i metodi nelle zone. Disattivare il plugin non cancella 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: peso del carrello, subtotale minimo e classi di spedizione escluse.
Per un indirizzo di consegna in Brasile con un CEP di 8 cifre, il plugin invia a Melhor Envio il CEP di origine e di destinazione e ogni articolo spedibile con peso, dimensioni, quantità e valore dichiarato, più l'elenco dei servizi se ne hai impostato uno. Le tariffe vengono convertite nella valuta del negozio e ordinate per prezzo. Il cliente vede il servizio più economico oppure un'opzione per servizio, con la stima dei tempi di consegna se è attiva. Se si applica la spedizione gratuita, il servizio più economico costa 0.
Ogni tariffa viene memorizzata in cache per 1 ora per pacco, CEP e ambiente, così lo stesso carrello non genera una nuova richiesta. Una chiamata fallita viene ricordata per 5 minuti, in modo che un'interruzione dell'API non rallenti ogni aggiornamento del checkout. Il timeout dell'API è di 12 secondi.
Se non c'è un token, l'indirizzo è fuori dal Brasile o non ha ancora un CEP valido, manca il tasso di cambio BRL, oppure Melhor Envio restituisce un errore o nessun servizio per la tratta, vengono usati i prezzi di riserva: la riga del paese (o la riga *), altrimenti il costo di riserva. Se si applica la spedizione gratuita, il metodo viene mostrato a costo zero anche senza prezzo. Se non c'è alcun prezzo, il metodo viene nascosto. Il cliente non vede mai un errore dell'API.
Il metodo funziona sul checkout classico e sui blocchi Carrello e Checkout. È compatibile con l'archiviazione ad alte prestazioni degli ordini di WooCommerce (HPOS).
Il plugin calcola solo i prezzi. Non acquista né genera etichette, non aggiunge spedizioni al carrello di Melhor Envio, non traccia i pacchi, non programma ritiri e non invia i dati della fattura (NF-e). Non offre la scelta delle agenzie (punti di consegna) di Jadlog, Azul o LATAM, né i servizi extra «consegna in mano propria» e «avviso di ricevimento». Gestisci le spedizioni nel tuo pannello di Melhor Envio. Melhor Envio spedisce solo in Brasile. Gli altri paesi ricevono solo i prezzi di riserva.
Ordini
Quando l'ordine viene effettuato con una tariffa in tempo reale, il servizio e la stima dei tempi di consegna vengono salvati sulla riga di spedizione dell'ordine. Sono mostrati nella schermata dell'ordine e nelle e-mail degli ordini come Melhor Envio service e Delivery estimate, così sai quale servizio acquistare in Melhor Envio. Gli ordini esistenti mantengono le loro righe di spedizione.
Chiave di licenza
Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Shipping > VibeFox Melhor Envio. Incolla la chiave in License key e clicca su Activate. Il blocco mostra lo stato, per esempio la data fino alla quale la licenza è attiva, e il tuo dominio. Usa Check now per verificare di nuovo 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 lo slot del dominio. Liberalo nel tuo account vibefox.net.
Senza una chiave attiva, Melhor Envio non viene mostrato ai clienti al checkout. I gestori del negozio con accesso lo vedono ancora, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugin e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati.
Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene verificato di nuovo automaticamente in background.
Risoluzione dei problemi
Melhor Envio 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 sia consentito). Controlla gli avvisi in cima alla pagina delle impostazioni, i limiti di peso, Minimum subtotal ed Excluded shipping classes. Senza token o senza tariffa, il metodo ha bisogno di un prezzo di riserva: una riga in Fallback price table oppure un Fallback cost.
Vengono mostrati solo i prezzi di riserva: attiva il Debug log, ricarica il checkout e apri WooCommerce > Status > Logs, origine vfd-melhor-envio. Motivi tipici: nessun token, un CEP di origine che non ha 8 cifre, nessun BRL exchange rate per una valuta del negozio diversa da BRL, nessun CEP di destinazione ancora o nessun servizio copre la tratta.
HTTP 401 o 403 nel log o negli avvisi: Melhor Envio ha rifiutato il token di accesso. È sbagliato, scaduto o revocato, oppure appartiene all'altro ambiente. Genera un nuovo token e verifica che Sandbox corrisponda.
Quale prezzo vedono i clienti: con un'opzione, il servizio più economico restituito da Melhor Envio. Con un'opzione per servizio, ogni servizio che copre la tratta. Per item vale solo per i prezzi di riserva.
Le tariffe sembrano obsolete dopo una modifica: salva la pagina delle impostazioni. Così vengono svuotate le tariffe in cache.
Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera uno slot nel tuo account vibefox.net e clicca su Check now. Se l'indirizzo del sito è cambiato, clicca 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. Viene svuotata solo la cache delle tariffe. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin, così come le tariffe in cache, vengono sempre rimossi. Le impostazioni e i metodi nelle zone vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano per una futura reinstallazione. Gli ordini esistenti mantengono le loro righe di spedizione.
Melhor Envio è un marchio del suo rispettivo titolare. Questo plugin non è affiliato né approvato da Melhor Envio.