VibeFox Melhor Envio for OpenCart — Guida
Requisiti
OpenCart: 3.0.x (testato su 3.0.5.0) o 4.0.2 e successivi (testato su 4.1.0.3).
PHP: 8.0 o successivo.
Account Melhor Envio (solo per le quotazioni in tempo reale): le quotazioni 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). I token di produzione e quelli di sandbox sono diversi. Non c'è un pulsante «connetti»: incolli il token nelle impostazioni dell'estensione. Senza token il metodo usa i prezzi di riserva.
Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un solo 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_melhor_envio-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_melhor_envio.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. Nel pannello di amministrazione vai su Extensions > Installer, fai clic su Upload e scegli il file vfd_melhor_envio-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non devi aggiornare Extensions > Modifications. Al posto 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 Melhor Envio e fai clic su Install (il pulsante verde +).
3. Fai clic su Edit (il pulsante con la matita) per aprire la pagina delle impostazioni.
4. Inserisci la tua chiave di licenza VibeFox in License key nel blocco della licenza in cima alla pagina Edit e fai clic su Activate (vedi Chiave di licenza).
5. Incolla il token di accesso, la tua e-mail di contatto e il CEP di origine. Se la valuta predefinita del 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. Attiva Enable Melhor Envio shipping e fai clic su Save.
OpenCart 4
1. Nel pannello di amministrazione vai su Extensions > Installer, fai clic su Upload e scegli il file vfd_melhor_envio.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. Fai clic su Install (il pulsante verde +) accanto a esso.
3. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox Melhor Envio, fai clic su Install (il pulsante verde +), poi su Edit (il pulsante con la 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 uguali nelle due versioni.
Dopo l'installazione il metodo resta disattivato finché non attivi Enable Melhor Envio shipping e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni che hai conservato.
Configurazione
Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox Melhor Envio > Edit. Le sezioni sono elencate a sinistra. Un pulsante Save salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella anche le quotazioni di Melhor Envio in cache e l'ultimo errore dell'API. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.
Gli avvisi in cima alla pagina (e dopo ogni salvataggio) segnalano una configurazione incompleta: un CEP di origine vuoto o che non ha 8 cifre, un'e-mail di contatto mancante, un tasso di cambio BRL mancante, nessun token e nessun prezzo di riserva (in tal caso il metodo non viene mostrato mai), l'ultimo errore dell'API di Melhor Envio con la sua data (quando è salvato un token), oppure un negozio senza una classe di peso «kg» o una classe di lunghezza «cm» (le unità vengono quindi convertite in base al nome, e le unità sconosciute vengono lette come kg o cm). Se Name è vuoto, troppo lungo o contiene uno dei caratteri < > ; = # { }, se un campo numerico contiene qualcosa che non è un numero pari o maggiore di 0, se Min weight è maggiore di Max weight, o se Default product size non ha la forma lunghezza x larghezza x altezza, la pagina mostra un errore e non viene salvato nulla.
Generale
Le impostazioni valgono per tutte le zone geografiche. Puoi limitare il metodo a una zona geografica in Availability. Il prezzo proviene sempre dall'estensione.
Enable Melhor Envio shipping: mostra o nasconde Melhor Envio al checkout. Predefinito: off.
Name: il nome del metodo di spedizione mostrato ai clienti nel carrello e al checkout. Predefinito: Melhor Envio. Obbligatorio, massimo 64 caratteri.
Sort order: la posizione di Melhor Envio tra i metodi di spedizione al checkout. Un numero intero.
API Melhor Envio
Access token: il token dell'ambiente selezionato più 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. Digita un nuovo token solo per 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. Con essa usa un token di sandbox. Predefinito: off.
Contact e-mail: un'e-mail di contatto tecnico, inviata a Melhor Envio nell'intestazione User-Agent di ogni richiesta, per esempio tech@example.com. Melhor Envio la richiede da ogni integrazione. Un indirizzo non valido non viene salvato e viene mostrato un avviso.
Origin CEP: il CEP (8 cifre) da cui vengono spediti i pacchi, per esempio 01310-100. OpenCart non ha un codice postale del negozio, quindi le quotazioni in tempo reale richiedono questo campo. Un CEP che non ha 8 cifre viene salvato con un avviso, ma non vengono richieste quotazioni.
Services: ID di servizio di Melhor Envio separati da virgole, facoltativi, da quotare, per esempio 1 = Correios PAC, 2 = Correios SEDEX, 17 = Correios Mini Envios, 3 = Jadlog .Package, 4 = Jadlog .Com. Lascia vuoto per quotare tutti i servizi del tuo account.
Quotes at checkout: come vengono mostrate le quotazioni.
Delivery time: mostra accanto al nome la stima di consegna di Melhor Envio, per esempio «(3-5 business days)». Predefinito: on.
Declared value: dichiara il valore dei prodotti (assicurazione) nelle quotazioni. Quando è disattivo, le quotazioni vengono fatte senza valore dichiarato: più economiche, ma i pacchi non sono assicurati. Predefinito: on.
BRL exchange rate: Melhor Envio quota in real brasiliani. Serve solo se la valuta predefinita del negozio non è BRL: inserisci il prezzo di 1 BRL nella tua valuta predefinita, per esempio 0.17. Senza di esso le quotazioni 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 valuta predefinita è BRL, il campo indica che i prezzi di Melhor Envio vengono usati così come sono.
Default product weight (kg): usato per i prodotti senza peso, sia nelle quotazioni sia per i limiti di peso. Deve essere maggiore di 0. Predefinito: 0.3.
Default product size (cm): lunghezza x larghezza x altezza, usato 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 o l'API non fornisce alcuna quotazione (errore, timeout, mancanza di copertura).
Fallback price table: prezzo per paese e peso del carrello, imposte escluse. Fai clic su Add country per aggiungere una riga (una nuova riga parte dal Brasile) e sul pulsante di rimozione per eliminarne una. Scegli * Any country per ogni paese senza una riga propria. Ogni riga ha un Price e colonne di peso: XS fino a 1 kg, S da 1 a 2 kg, M da 2 a 3 kg, L da 3 a 5 kg e XL oltre 5 kg. Una colonna vuota o 0 usa il Price, e un Price di 0 significa spedizione gratuita. Sono accettati sia «9.99» sia «9,99». I valori che non sono numeri vengono segnalati dopo il salvataggio e ignorati. Le righe senza alcun prezzo vengono eliminate.
Fallback cost: usato quando anche la tabella non ha un prezzo. Lascialo vuoto per nascondere il metodo in quel caso.
Fallback calculation: Per order (predefinito) 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à. Questo vale solo per i prezzi di riserva. Le quotazioni di Melhor Envio includono già tutti gli articoli.
Disponibilità
Min weight (kg): nasconde il metodo quando il carrello pesa meno. 0 significa nessun limite (predefinito).
Max weight (kg): nasconde il metodo quando il carrello pesa di più. Predefinito: 30. 0 significa nessun limite. Un campo vuoto significa 30 kg, oppure nessun limite quando Ignore shipping zones è attivo.
Minimum subtotal: mostra il metodo solo se il subtotale del carrello (prodotti che richiedono la spedizione, dopo il coupon, prima delle imposte) è almeno questo importo. Lascialo vuoto per mostrarlo sempre.
Free shipping from: il subtotale del carrello a partire dal quale 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.
Tax class: la classe fiscale aggiunta sopra il costo di spedizione, oppure No tax (predefinito). I prezzi di Melhor Envio sono tariffe finali dei corrieri. Scegli No tax se OpenCart non deve aggiungervi imposte.
Geo zone: offri Melhor Envio 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.
Disponibilità senza zone di spedizione
Normalmente il metodo viene offerto nella zona geografica selezionata in Availability (tutte le zone quando non ne è selezionata nessuna).
Ignore shipping zones: offri il metodo per i paesi indicati sotto, qualunque sia la zona geografica selezionata. In questa modalità la zona geografica non viene verificata.
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: scrive le richieste all'API e il calcolo delle tariffe in storage/logs/vfd_menv_debug.log.php (su OpenCart 4 system/storage/logs/vfd_menv_debug.log.php). Il file non può essere letto dal web. Gli errori dell'API vengono sempre registrati, anche con questa opzione disattivata. Il token non viene mai registrato e il CEP del cliente viene abbreviato alle prime 5 cifre. Quando il file raggiunge 5 MB, viene spostato in vfd_menv_debug.old.log.php e si avvia un nuovo log.
Log: mostra la dimensione e le ultime voci del log di debug. Fai clic su Clear log per svuotarlo.
Remove data on uninstall: quando è attivo, disinstallando l'estensione vengono eliminate tutte le sue impostazioni e il log. Quando è disattivo (predefinito), vengono conservati per una reinstallazione. La cache delle quotazioni viene sempre rimossa. I servizi salvati con gli ordini fanno parte dello storico degli ordini e vengono conservati.
Importa / Esporta
Export: fai clic su Download JSON per salvare le impostazioni in un file JSON. Il token di accesso non viene esportato.
Import: incolla un JSON esportato in precedenza e fai clic su Import per ripristinare le impostazioni, per esempio su un altro negozio. I valori vengono verificati come in un normale salvataggio. Il token di accesso salvato viene conservato.
Funzionamento al checkout
Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di Melhor Envio. Se è impostata una Geo zone e l'indirizzo è al di fuori di essa, Melhor Envio non viene offerto. Con Ignore shipping zones la zona geografica non viene verificata: Melhor Envio viene offerto solo quando il paese è in Countries (o Countries è vuoto). Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri prodotti non aggiungono peso e non sono inclusi nel subtotale. L'estensione verifica poi il peso del carrello e il subtotale minimo.
Per un indirizzo di consegna in Brasile con un CEP di 8 cifre, l'estensione invia a Melhor Envio il CEP di origine e quello di destinazione, e ogni articolo spedibile con peso, dimensioni, quantità e valore dichiarato, insieme all'elenco dei servizi se ne hai impostato uno. Il Model del prodotto viene inviato come ID dell'articolo. I servizi con errore o senza prezzo vengono saltati. Le quotazioni vengono convertite nella valuta predefinita, arrotondate ai suoi decimali, ordinate per prezzo e mostrate nella valuta del cliente con l'imposta della Tax class selezionata. Se si applica la spedizione gratuita, il servizio più economico costa 0.
Con One option - the cheapest service il cliente vede un'unica opzione, per esempio Melhor Envio (6-7 business days). Con One option per service il cliente vede un'opzione per servizio, per esempio Melhor Envio: Correios SEDEX (1-2 business days). La stima di consegna viene aggiunta solo quando Delivery time è attivo.
Ogni quotazione viene memorizzata in cache per 1 ora, così lo stesso carrello non genera una nuova richiesta. Una chiamata non riuscita viene ricordata per 5 minuti, così un guasto dell'API non rallenta 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 quella tratta, si usano i prezzi di riserva: la riga del paese (o la riga * quando il paese non ha una riga), altrimenti il costo di riserva. Tale opzione si chiama semplicemente come indicato in Name. Se si applica la spedizione gratuita, il metodo viene mostrato senza costi anche senza un prezzo. Se non c'è alcun prezzo, il metodo viene nascosto. Il cliente non vede mai un errore dell'API. Il motivo viene scritto nel log.
Su OpenCart 4 il cliente fa clic su Choose nel blocco del metodo di spedizione della pagina di checkout e sceglie un'opzione di Melhor Envio nella finestra Shipping method options. Opzioni e prezzi sono gli stessi di OpenCart 3.
L'estensione 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 di agenzie di spedizione (punti di consegna). 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
OpenCart salva il nome dell'opzione scelta come metodo di spedizione dell'ordine, quindi il servizio e la stima di consegna compaiono nelle e-mail degli ordini, nell'account del cliente e in Sales > Orders.
Quando un ordine viene effettuato con una quotazione in tempo reale, l'estensione salva anche il servizio di Melhor Envio esattamente come lo ha visto il cliente al passaggio di consegna, senza una nuova richiesta. La pagina dell'ordine nel pannello di amministrazione, in Sales > Orders, mostra un blocco Melhor Envio con Melhor Envio service, Service ID e Delivery estimate, così sai quale servizio acquistare in Melhor Envio. Il cliente vede Melhor Envio service e Delivery estimate nella pagina dell'ordine del suo account. Gli ordini effettuati con un prezzo di riserva non hanno un servizio. Gli ordini esistenti non sono interessati.
Su OpenCart 4 il blocco Melhor Envio viene mostrato sopra il blocco History. OpenCart 4 mantiene un unico ordine per il checkout e lo aggiorna ogni volta che il cliente conferma di nuovo: il servizio salvato viene aggiornato insieme ad esso, ed è rimosso quando il cliente passa a un altro metodo di spedizione o quando all'ordine viene assegnato un prezzo di riserva.
Chiave di licenza
L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox Melhor Envio è il primo blocco di Extensions > Extensions > Shipping > VibeFox Melhor Envio > Edit, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (per esempio la data fino a cui 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 si trovano la riga Product: opencart-shipping-melhor-envio 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 modificare la chiave. I testi del blocco seguono la lingua del pannello di amministrazione (sono inclusi l'inglese e il 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 la modifica dell'indirizzo del negozio, o dopo aver liberato uno slot di dominio nel tuo account, fai clic 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 solo 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, Melhor Envio non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Un utente amministratore che ha effettuato l'accesso al pannello di amministrazione nello stesso browser vede comunque il metodo nel negozio, contrassegnato da (unlicensed — visible to admins only), così puoi configurare e provare 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 del pannello di amministrazione compare un promemoria. Chiudilo con × per nasconderlo per 7 giorni. Gli ordini esistenti non sono interessati.
Quando una licenza scade, l'estensione continua a funzionare, ma aggiornamenti e assistenza richiedono il rinnovo. Lo stato viene controllato di nuovo automaticamente quando apri la Dashboard del pannello di amministrazione o la pagina Edit: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve alcun cron job. La disinstallazione dell'estensione rimuove sempre la chiave di licenza e lo stato della licenza.
Risoluzione dei problemi
Melhor Envio non compare al checkout: verifica che la licenza sia attiva e che Enable Melhor Envio shipping sia attivo. Controlla la Geo zone, oppure attiva Ignore shipping zones e controlla Countries. Consulta gli avvisi in cima alla pagina dell'estensione, i limiti di peso e il Minimum subtotal. Senza token o quotazione, il metodo ha bisogno di un prezzo di riserva: una riga nella Fallback price table oppure un Fallback cost. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.
Vengono mostrati solo i prezzi di riserva: attiva Debug log, ricarica il checkout e controlla il campo Log nella pagina dell'estensione. Motivi tipici: manca il token, un CEP di origine che non ha 8 cifre, manca il BRL exchange rate con una valuta predefinita diversa dal 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. È errato, scaduto o revocato, oppure appartiene all'altro ambiente. Genera un nuovo token e verifica che Sandbox corrisponda.
Al prezzo di Melhor Envio viene aggiunta un'imposta: imposta Tax class su No tax.
Dopo una modifica le quotazioni sembrano obsolete: fai clic su Save nella pagina dell'estensione. Questo svuota la cache delle quotazioni.
La pagina dice "Warning: You do not have permission to modify VibeFox Melhor Envio!": il tuo gruppo di utenti amministratori può solo visualizzare le impostazioni. Dai al gruppo il permesso di modifica per extension/shipping/vfd_melhor_envio (OpenCart 3) o extension/vfd_melhor_envio/shipping/vfd_melhor_envio (OpenCart 4) in System > Users > User Groups.
Per gli sviluppatori: l'indirizzo dell'API di quotazione di Melhor Envio può essere sostituito con l'impostazione vfd_menv_api_url (per i test); non ha un campo nella pagina delle impostazioni.
Disinstallazione
Vai su Extensions > Extensions, scegli il tipo Shipping e fai clic su Uninstall (il pulsante rosso −) accanto a VibeFox Melhor Envio. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable Melhor Envio shipping, Sort order, Tax class e Geo zone. La cache delle quotazioni viene sempre rimossa. Se Remove data on uninstall è attivo, anche le altre impostazioni e il log di debug vengono eliminati. Se è disattivo, vengono conservati e riutilizzati quando reinstalli l'estensione. I servizi salvati con gli ordini vengono sempre conservati, e gli ordini esistenti mantengono il loro metodo di spedizione e il loro costo.
Su OpenCart 4, per rimuovere anche i file dell'estensione, dopo la disinstallazione vai su Extensions > Installer e fai clic su Uninstall (il pulsante arancione −) accanto a VibeFox Melhor Envio nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per eliminare il pacchetto caricato.
Melhor Envio è un marchio del suo legittimo proprietario. Questa estensione non è affiliata né approvata da Melhor Envio.