VibeFox Mercado Envios 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 Mercado Pago (solo per le tariffe in tempo reale): le tariffe in tempo reale provengono dal calcolatore Mercado Envios del tuo account Mercado Pago in Argentina, Brasile o Messico. Mercado Envios deve essere attivo per l'account. I pacchi vengono quotati dall'indirizzo di spedizione configurato in quell'account. Ti serve l'access token di produzione (inizia con APP_USR-): in Mercado Pago Developers apri la tua applicazione e le sue credenziali di produzione. Non c'è un pulsante di accesso: incolla il token nelle impostazioni dell'estensione. Se usi solo i prezzi per paese, non ti serve un account Mercado Pago.

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_mercado_envios-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_mercado_envios.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_mercado_envios-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non devi 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 Mercado Envios e fai clic su Install (il pulsante verde +).

3. Fai clic su Edit (il pulsante a forma di 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. Per le tariffe in tempo reale, incolla l'access token, scegli il paese di Mercado Envios e, se la valuta predefinita del tuo negozio non è ARS, BRL o MXN, il tasso di cambio. Facoltativamente compila Country prices e Fallback cost (usati senza tariffe in tempo reale). Attiva Enable Mercado Envios 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_mercado_envios.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 Mercado Envios, 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 è disattivato finché non attivi Enable Mercado Envios 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 Mercado Envios > Edit. Le sezioni sono elencate a sinistra. Un solo pulsante Save salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella anche le tariffe Mercado Envios 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 nella sezione General (e dopo ogni salvataggio) mostrano problemi di configurazione: manca il tasso di cambio, non c'è un access token e nessun prezzo (in tal caso il metodo non viene mai mostrato), l'ultimo errore dell'API Mercado Envios con la sua data, e un'unità di peso o di lunghezza del negozio che l'estensione non riconosce (viene quindi letta come kg o cm). Se Name è vuoto o più lungo di 64 caratteri, Exchange rate non è un numero positivo, un altro campo numerico non è un numero maggiore o uguale a 0, oppure Min weight è maggiore di Max weight, la pagina mostra un errore e non viene salvato nulla.

Generale

Il cliente vede una sola tariffa Mercado Envios. Puoi limitare il metodo a una zona geografica o a paesi in Availability. Queste impostazioni valgono per tutte le zone.

Enable Mercado Envios shipping: mostra o nasconde Mercado Envios al checkout. Predefinito: disattivato.

Name: il nome del metodo di spedizione mostrato ai clienti nel carrello e al checkout. Predefinito: Mercado Envios. Obbligatorio, massimo 64 caratteri.

Tax class: la classe fiscale del costo di spedizione, oppure No tax (predefinito). Mercado Envios fornisce prezzi finali. No tax li mostra così come sono; una classe fiscale aggiunge sopra l'imposta sulla spedizione del tuo negozio.

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

API Mercado Envios (tariffe in tempo reale) (senza token si usano solo i prezzi qui sotto)

Access token: il tuo access token di produzione di Mercado Pago (APP_USR-...). Viene inviato solo a api.mercadopago.com e non viene mai registrato. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un valore nuovo solo per modificarlo.

Remove the saved access token: attivalo e salva per eliminare il token salvato. Si useranno solo i prezzi qui sotto. Un token inserito sopra sostituisce invece quello salvato.

Mercado Envios country: il paese del tuo account Mercado Pago: Argentina (ARS) (predefinito), Brazil (BRL) o Mexico (MXN). Le tariffe in tempo reale vengono richieste solo per destinazioni in questo paese e sono quotate nella sua valuta.

Exchange rate: necessario solo quando la valuta predefinita del negozio è diversa da quella di Mercado Envios: il prezzo di 1 ARS, BRL o MXN nella valuta predefinita del negozio, per esempio 0.001. Senza di esso le tariffe in tempo reale non vengono usate. Deve essere un numero positivo. Sono accettati sia il punto sia la virgola come separatore decimale.

Prezzi senza tariffe in tempo reale

Questi prezzi si usano quando non c'è un access token, per destinazioni fuori dal paese di Mercado Envios e quando l'API non fornisce una tariffa (una richiesta non riuscita viene ripetuta dopo 5 minuti). Sono nella valuta predefinita del negozio, al netto delle imposte.

Country prices: una tabella di paesi di destinazione e prezzi. Fai clic 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. Price è il prezzo per il paese. Le colonne XS (fino a 1 kg), S (1-2 kg), M (2-3 kg), L (3-5 kg) e XL (oltre 5 kg) lo sostituiscono per quel peso del carrello. Una colonna vuota o con 0 usa Price. Un Price pari a 0 significa spedizione gratuita verso quel paese. Sono accettati sia 9.99 sia 9,99. I valori che non sono numeri vengono segnalati dopo il salvataggio e cancellati. Le righe senza alcun prezzo vengono eliminate al salvataggio.

Fallback cost: usato quando né l'API né Country prices forniscono un prezzo. Lascialo vuoto per nascondere il metodo in quel caso.

Calculation type: Per order (predefinito) addebita il prezzo una sola volta. Per item (each item priced by its own weight x quantity) cerca in Country prices (o in Fallback cost) il prezzo per il peso di ogni prodotto e lo moltiplica per la quantità. Se un prodotto non ottiene un prezzo, il metodo viene nascosto. Le tariffe Mercado Envios in tempo reale riguardano sempre l'intero pacco.

Disponibilità

Min weight (kg): il peso minimo del carrello perché questo metodo compaia. 0 significa nessun limite (predefinito).

Max weight (kg): nasconde il metodo quando il carrello pesa di più. Predefinito: 25. Vuoto significa 25 kg, 0 significa nessun limite.

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

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

Ignore shipping zones: offre il metodo per i paesi indicati sotto, indipendentemente dalla zona geografica selezionata.

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

Spedizione gratuita

Free shipping from: il subtotale dei prodotti che richiedono spedizione (dopo il coupon, prima delle imposte) a partire dal quale questo metodo è gratuito. In quel caso non viene fatta alcuna richiesta all'API. Lascialo vuoto per disattivare.

Avanzate

Debug log: scrive le richieste API e il calcolo delle tariffe in storage/logs/vfd_mrcv_debug.log.php (su OpenCart 4 system/storage/logs/vfd_mrcv_debug.log.php). Il file non può essere letto dal web. Gli errori vengono sempre registrati, anche con questa opzione disattivata. Il token di accesso e gli indirizzi dei clienti non vengono mai registrati. Quando il file raggiunge 5 MB, viene spostato in vfd_mrcv_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: se attivo, disinstallando l'estensione vengono eliminate le impostazioni e il log. Se disattivo (predefinito), vengono conservate per una nuova installazione. Le tariffe in cache vengono sempre rimosse. I dati Mercado Envios degli ordini effettuati vengono sempre conservati come storico degli ordini.

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 in un altro negozio. I valori vengono verificati come in un normale salvataggio. Il token di accesso salvato viene conservato.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di Mercado Envios. Se è impostata una Geo zone e l'indirizzo è al di fuori di essa, Mercado Envios non viene proposto (a meno che Ignore shipping zones sia attivo; in tal caso decide Countries). 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 quindi il peso del carrello e il subtotale minimo. Il subtotale è 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 Mercado Envios.

Per una destinazione nel paese di Mercado Envios con un codice postale valido (4 cifre in Argentina, anche da un CPA come C1425ABC; 8 cifre in Brasile; 5 cifre in Messico), l'estensione descrive il carrello come un unico pacco: la larghezza e la lunghezza massime dei prodotti, la somma delle altezze di tutti i prodotti e il peso totale in grammi. Pesi e dimensioni dei prodotti vengono convertiti dalle loro classi di peso e lunghezza di OpenCart. Ogni lato e il peso vengono portati ai minimi Mercado Envios del paese, quindi anche i prodotti senza dimensioni o peso ottengono una tariffa. Il valore del carrello viene inviato come prezzo dell'articolo nella valuta di Mercado Envios. L'opzione più economica restituita da Mercado Envios viene convertita nella valuta predefinita del negozio, arrotondata ai suoi decimali e mostrata nella valuta del cliente con l'imposta della Tax class selezionata.

Ogni preventivo viene memorizzato in cache per un massimo di 1 ora (non oltre la durata della cache di OpenCart), così lo stesso carrello non genera una nuova richiesta. Un preventivo non riuscito non viene ripetuto per 5 minuti. Se Mercado Pago non è raggiungibile, rifiuta il token, limita le richieste o risponde in un'altra valuta, tutte le tariffe in tempo reale vengono sospese per 5 minuti, così il checkout non attende l'API a ogni aggiornamento. Il timeout dell'API è di 10 secondi.

I prezzi senza tariffe in tempo reale vengono usati al loro posto quando non c'è un token, la destinazione è fuori dal paese di Mercado Envios, il codice postale manca o non è valido, manca il tasso di cambio, il pacco è più pesante del limite Mercado Envios del paese (25 kg in Argentina, 15 kg in Brasile, 30 kg in Messico), oppure Mercado Envios restituisce un errore o nessuna opzione per l'indirizzo. Si usa la riga del paese (o la riga *), altrimenti il costo di riserva. Se non c'è alcun prezzo, il metodo viene nascosto. Il cliente non vede mai un errore dell'API.

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

L'estensione calcola solo tariffe. Non crea spedizioni, non stampa etichette e non traccia i pacchi. Crea la spedizione nel tuo account Mercado Libre o Mercado Pago. Mostra un solo prezzo, l'opzione Mercado Envios più economica, non una scelta tra tutte le opzioni, e non ha un selettore di punto di ritiro (agenzia).

Ordini

Quando un ordine viene effettuato con una tariffa Mercado Envios in tempo reale, l'estensione conserva il nome del servizio, il tempo di consegna stimato in giorni e la tariffa in tempo reale. In Sales > Orders la pagina dell'ordine mostra un blocco Mercado Envios con Mercado Envios service, Estimated delivery e Live rate (excl. tax). Il blocco viene mostrato anche se il metodo viene disattivato in seguito. Un cliente registrato vede Mercado Envios service e Estimated delivery sotto il metodo di spedizione nella pagina dell'ordine del proprio account, e le stesse righe vengono aggiunte all'e-mail di nuovo ordine. Gli ordini effettuati con un prezzo a tabella o con il costo di riserva non hanno un servizio. Gli ordini esistenti non sono interessati dalle modifiche successive alle tariffe.

Su OpenCart 4 il blocco Mercado Envios 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 a tabella o il costo di riserva.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza License — VibeFox Mercado Envios è il primo blocco di Extensions > Extensions > Shipping > VibeFox Mercado Envios > 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 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 ci sono la riga Product: opencart-shipping-mercado-envios e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo gli utenti amministratori con il permesso di modifica per l'estensione possono cambiare la chiave. I testi del blocco seguono la lingua del pannello di 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 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 nella 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, Mercado Envios 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

Mercado Envios non compare al checkout: verifica che la licenza sia attiva e che Enable Mercado Envios shipping sia attivo. Controlla Geo zone, oppure attiva Ignore shipping zones e controlla Countries. Controlla gli avvisi nella pagina dell'estensione, i limiti di peso e Minimum subtotal. Il metodo ha bisogno di un prezzo: un access token funzionante per gli indirizzi nel paese di Mercado Envios, oppure Country prices o Fallback cost. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.

Le tariffe in tempo reale non compaiono: attiva Debug log, ricarica il checkout e controlla il campo Log nella pagina dell'estensione. Motivi tipici: nessun token, una destinazione fuori dal paese di Mercado Envios, un codice postale mancante o non valido, un Exchange rate mancante, un pacco oltre il limite di peso, o nessuna opzione Mercado Envios per l'indirizzo.

HTTP 401 o 403 negli avvisi: l'access token non è valido o è scaduto. Copia di nuovo l'access token di produzione da Mercado Pago Developers.

Mercado Envios ha risposto in un'altra valuta: il paese dell'account non corrisponde a Mercado Envios country. Scegli il paese del tuo account Mercado Pago.

In quale valuta sono i prezzi: Country prices, Fallback cost e le soglie sono nella valuta predefinita del negozio. Le tariffe in tempo reale arrivano nella valuta del tuo account Mercado Pago e vengono convertite con Exchange rate quando il negozio usa un'altra valuta predefinita.

Le tariffe sembrano non aggiornate dopo una modifica: fai clic su Save nella pagina dell'estensione. Questo cancella le tariffe in cache.

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

Per sviluppatori: l'indirizzo dell'API Mercado Envios può essere sostituito con l'impostazione vfd_mrcv_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 Mercado Envios. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable Mercado Envios shipping, Sort order, Tax class e Geo zone. Le tariffe in cache e l'ultimo errore dell'API vengono sempre rimossi. Se Remove data on uninstall è attivo, vengono eliminate anche le altre impostazioni e il log di debug. Se è disattivo, vengono conservate e riutilizzate quando reinstalli l'estensione. I dati Mercado Envios degli ordini effettuati 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 Mercado Envios nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per eliminare il pacchetto caricato.

Mercado Envios e Mercado Pago sono marchi dei rispettivi titolari. Questa estensione non è affiliata né approvata da Mercado Envios o Mercado Pago.