VibeFox Melhor Envio 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.
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 token (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 quelli della sandbox sono diversi. Non c'è un pulsante «collega»: incolli il token nelle impostazioni del modulo. Senza token, il corriere usa i prezzi di riserva.
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 Melhor Envio 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. Incolla il token di accesso, la tua e-mail di contatto e il CEP di origine. Se la valuta predefinita del tuo negozio non è BRL, imposta BRL exchange rate. Facoltativamente compila la tabella dei prezzi di riserva (per esempio per il Brasile) o un costo di riserva. Clicca su Save.
All'installazione il modulo crea il corriere Melhor Envio con il testo dei tempi di consegna Delivery by the carriers of your Melhor Envio account. 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 arriva sempre dal modulo.
Configurazione
Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Melhor Envio > Configure. Valgono per tutte le zone del corriere. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio svuota anche le tariffe di Melhor Envio in cache e l'ultimo errore dell'API.
Gli avvisi in cima alla pagina segnalano una configurazione incompleta: un CEP di origine vuoto o non di 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, token mancante, prezzo di riserva mancante (in tal caso il corriere non viene mai mostrato) oppure un'unità di peso o di dimensioni del negozio che il modulo non riconosce (viene quindi letta come kg o cm). Se un campo numerico contiene qualcosa che non è un numero pari o superiore a 0, se Min weight è maggiore di Max weight o se Default product size non è nel formato lunghezza x larghezza x altezza, la pagina mostra un errore e non viene salvato nulla.
General
Enable Melhor Envio shipping: attiva o disattiva il corriere. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.
Name: il nome del corriere mostrato ai clienti al checkout. Predefinito: Melhor Envio. Obbligatorio, massimo 64 caratteri.
Tax: la regola fiscale del corriere, oppure No tax. I prezzi di Melhor Envio sono prezzi finali del corriere. Scegli No tax se PrestaShop non deve aggiungervi imposte.
Melhor Envio API
Access token: il token dell'ambiente selezionato qui sotto. Viene inviato a Melhor Envio come token Bearer. Dopo il salvataggio il campo resta vuoto e mostra A token is saved — leave empty to keep it. Inserisci un nuovo token solo se vuoi cambiarlo. Per eliminare il token salvato, spunta Remove the saved token e salva. Il token non viene mai scritto nel log.
Sandbox: usa la sandbox di Melhor Envio (sandbox.melhorenvio.com.br) per i test. Usala con un token della sandbox. Predefinito: disattivato.
Contact e-mail: un'e-mail di contatto tecnico, inviata a Melhor Envio nell'intestazione User-Agent di ogni richiesta. Melhor Envio la richiede a ogni integrazione. Un indirizzo non valido non viene salvato e un avviso lo segnala.
Origin CEP: il CEP (8 cifre) da cui vengono spediti i pacchi, per esempio 01310-100. Viene salvato nel formato 00000-000. Senza un CEP di origine valido non vengono richieste tariffe.
Services: ID dei servizi di Melhor Envio separati da virgole, da quotare (facoltativo), 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 al checkout 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 è disattivo, le tariffe vengono calcolate senza valore dichiarato: sono più economiche, ma i pacchi non sono assicurati. Predefinito: attivo.
BRL exchange rate: Melhor Envio calcola le tariffe in real brasiliani. Serve solo se la valuta predefinita del tuo negozio non è BRL: inserisci il prezzo di 1 BRL nella tua valuta predefinita, per esempio 0.17. Senza di esso, le tariffe in tempo reale non vengono usate. Il valore deve essere maggiore di 0. Il valore dichiarato viene convertito in BRL con lo stesso tasso. Se la tua valuta predefinita è BRL, il campo mostra Store currency is BRL.
Default product weight: in kg, per i prodotti senza peso, sia nelle tariffe sia per i limiti di peso. Deve essere maggiore di 0. Predefinito: 0.3.
Default product size: lunghezza x larghezza x altezza in cm, per i prodotti senza dimensioni. Predefinito: 16x11x5.
Prezzi di riserva (nella valuta predefinita del tuo negozio)
I prezzi di riserva vengono usati quando manca il token, manca il CEP di destinazione oppure l'API non dà una tariffa (errore, timeout, nessuna copertura).
Fallback price table: prezzo per paese e peso del carrello. Clicca su Add country per aggiungere una riga e sull'icona del cestino per rimuoverne una. Scegli * Default come paese per ogni paese che non ha una riga propria. Ogni riga ha un Price e 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 con 0 usa 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 la tabella non ha nemmeno un prezzo. Lascialo vuoto per nascondere il corriere 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 uno) e lo moltiplica per la sua quantità. Se un articolo non ha un prezzo, il corriere viene nascosto. Questo vale solo per i prezzi di riserva. Le tariffe di Melhor Envio includono già tutti gli articoli.
Disponibilità
Min weight: nasconde il corriere quando il carrello pesa meno, in kg. 0 significa nessun limite.
Max weight: nasconde il corriere quando il carrello pesa di più, in kg. Predefinito: 30. 0 significa nessun limite. Un campo vuoto significa 30 kg nelle zone del corriere, e nessun limite solo per i paesi di Ignore shipping zones che si trovano al di fuori di esse.
Minimum subtotal: mostra il corriere solo se il subtotale del carrello (prodotti che richiedono spedizione, dopo gli sconti, prima delle tasse) è almeno questo importo. Lascia 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. Lascia vuoto per disattivare.
Ignore shipping zones: offre il corriere nei paesi indicati qui sotto anche se non è assegnato alle loro zone. Finché è attivo, il corriere è collegato a tutte le zone, comprese quelle inattive e quelle create in seguito. Quando lo disattivi, il corriere riottiene le sue zone.
Countries: i paesi di destinazione per quella modalità. Lascia vuoto per tutti i paesi. Questo campo viene usato solo quando Ignore shipping zones è attivo.
Avanzate
Debug log: scrive le richieste all'API e il calcolo delle tariffe in logs/vfd_menv_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori vengono sempre registrati, anche con questa opzione disattiva. Il token non viene mai registrato e il CEP del cliente viene accorciato alle prime 5 cifre.
Log: mostra la dimensione e gli ultimi inserimenti del log di debug. Clicca su Clear log per svuotarlo.
Remove data on uninstall: se attivo, disinstallando il modulo vengono eliminati tutti i suoi dati, il corriere e il log. Se disattivo, tutto viene conservato per una reinstallazione. La cache delle tariffe viene sempre rimossa. I servizi salvati con gli ordini fanno parte dello storico degli ordini e vengono conservati.
Come funziona al checkout
Al passo della spedizione PrestaShop chiede al modulo il prezzo di Melhor Envio. Contano solo i prodotti che richiedono spedizione: i prodotti virtuali non aggiungono peso e non sono inclusi nel subtotale. Il modulo verifica prima le condizioni: i paesi di Ignore shipping zones, il peso del carrello e il subtotale minimo.
Per un indirizzo di consegna in Brasile con un CEP di 8 cifre, il modulo 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 tua valuta predefinita, ordinate per prezzo e poi mostrate nella valuta del carrello del cliente. Se si applica la spedizione gratuita, il servizio più economico costa 0.
Con One option - the cheapest service il corriere mostra il prezzo del servizio più economico e la riga Delivery estimate: sotto il corriere, se Delivery time è attivo. Con One option per service il cliente vede Choose a delivery service: sotto il corriere, con un pulsante di scelta per ogni servizio, il suo prezzo e la stima dei tempi di consegna. La scelta viene salvata subito, e il prezzo del corriere e il riepilogo del carrello vengono aggiornati. Se il servizio non è più offerto per l'indirizzo, il cliente vede This service is not available for your address any more. Please choose another one. e torna la scelta precedente.
Ogni tariffa è memorizzata in cache per 1 ora per pacco, CEP, token e ambiente, quindi lo stesso carrello non genera una nuova richiesta. Una chiamata fallita viene ricordata per 5 minuti, così un'interruzione dell'API non rallenta ogni aggiornamento del checkout. Il timeout dell'API è di 12 secondi.
Se manca il 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, si usano i prezzi di riserva: la riga del paese (o la riga *), altrimenti il costo di riserva. Se si applica la spedizione gratuita, il corriere viene mostrato senza costi anche senza prezzo. Se non c'è alcun prezzo, il corriere viene nascosto. Il cliente non vede mai un errore dell'API.
Se modifichi il corriere in Shipping > Carriers dopo che ha degli ordini, PrestaShop lo salva come una nuova versione del corriere. Il modulo segue automaticamente la nuova versione.
Il modulo 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 all'interno del Brasile. Gli altri paesi ricevono solo i prezzi di riserva.
Ordini
Quando un ordine viene effettuato con una tariffa in tempo reale, il modulo salva con l'ordine il servizio di Melhor Envio e la sua stima dei tempi di consegna. La pagina dell'ordine nel back office mostra un blocco Melhor Envio con Melhor Envio service (con l'ID del servizio) e Delivery estimate, così sai quale servizio acquistare in Melhor Envio. Il cliente vede le stesse informazioni nella pagina del proprio ordine nel suo account. Nell'e-mail di conferma dell'ordine vengono aggiunte dopo il nome del corriere. Gli ordini effettuati con un prezzo di riserva non hanno servizio. Gli ordini esistenti non sono interessati.
Chiave di licenza
Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Melhor Envio è il primo blocco di Modules > Module Manager > VibeFox Melhor Envio > 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 di essi ci sono la riga Product: presta-shipping-melhor-envio e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo i dipendenti con l'autorizzazione Configure per il modulo possono 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 spiega 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 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: il dominio 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 Melhor Envio non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. La vetrina 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 gli aggiornamenti e l'assistenza 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
Melhor Envio non appare al checkout: verifica che la licenza sia attiva e che Enable Melhor Envio shipping 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 gli avvisi in cima alla pagina del modulo, i limiti di peso e Minimum subtotal. Senza token o tariffa, il corriere ha bisogno di un prezzo di riserva: una riga in Fallback price table o un Fallback cost. I prodotti possono anche essere limitati a determinati corrieri nella pagina del prodotto.
Vengono mostrati solo i prezzi di riserva: attiva Debug log, ricarica il checkout e guarda il campo Log nella pagina del modulo. Motivi tipici: manca il token, il CEP di origine non ha 8 cifre, manca il BRL exchange rate per una valuta predefinita diversa da BRL, non c'è ancora un CEP di destinazione oppure 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.
Il cliente vede «The service could not be saved. Please try again.»: la scelta non è arrivata al negozio, per esempio a causa di un errore di rete. Il cliente può scegliere di nuovo il servizio. Anche il servizio selezionato quando il cliente clicca su Continue viene salvato.
Alle tariffe di Melhor Envio viene aggiunta l'imposta: imposta Tax su No tax.
Le tariffe sembrano obsolete dopo una modifica: clicca su Save nella pagina del modulo. Questo svuota la cache delle tariffe.
La pagina dice che il corriere di Melhor Envio non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Ripristina il modulo in Modules > Module Manager per ricrearlo.
Disinstallazione
Vai su Modules > Module Manager, apri il menu accanto a VibeFox Melhor Envio e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. La cache delle tariffe viene sempre rimossa. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini conservano lo storico), vengono ripristinate le sue zone e vengono rimosse le impostazioni, le scelte di servizio dei carrelli aperti e il log. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni restano. Reinstallando il modulo, il corriere riacquista lo stato che aveva prima. I servizi salvati con gli ordini vengono sempre conservati.
Melhor Envio è un marchio registrato del rispettivo proprietario. Questo modulo non è affiliato né approvato da Melhor Envio.