VibeFox Mercado Envios for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni di PHP precedenti.

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 a partire dall'indirizzo di spedizione configurato in quell'account. Ti serve l'Access Token di produzione (inizia con APP_USR-): nel pannello sviluppatori di Mercado Pago apri la tua applicazione e le sue credenziali di produzione. Non c'è un pulsante di accesso: incolli il token nelle impostazioni del modulo. Se usi solo prezzi per paese, non ti serve un account Mercado Pago.

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 cerca più tardi VibeFox Mercado Envios nell'elenco dei moduli e clicca su Configure.

3. Inserisci la tua chiave di licenza VibeFox in License key nel blocco licenza in alto nella pagina Configure e clicca su Activate (vedi Chiave di licenza).

4. 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). Clicca su Save.

All'installazione il modulo crea il corriere Mercado Envios con il testo dei tempi di consegna Mercado Envios delivery. Il corriere viene assegnato a tutte le zone e a tutti i gruppi di clienti, senza regola fiscale. Puoi modificare zone, gruppi di clienti, tempi di consegna, logo e limiti di dimensione in Shipping > Carriers. Non impostare i prezzi lì: il prezzo arriva sempre dal modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Mercado Envios > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella anche le tariffe di Mercado Envios in cache e l'ultimo errore dell'API.

Gli avvisi in alto nella pagina segnalano problemi di configurazione: un tasso di cambio mancante, nessun access token e nessun prezzo, l'ultimo errore dell'API di Mercado Envios con la sua data, e un'unità di peso o di dimensione del negozio che il modulo non riconosce (viene quindi letta come kg o cm). Se il corriere è stato eliminato, la sezione General riporta: The Mercado Envios carrier was not found — reset the module to create it again.

General

Aggiungi le zone dei tuoi clienti al corriere Mercado Envios in Shipping > Carriers, oppure usa Ignore shipping zones più sotto. Queste impostazioni valgono per ogni zona.

Enable Mercado Envios 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: Mercado Envios. Obbligatorio, massimo 64 caratteri.

Tax: la regola fiscale del corriere, oppure No tax (predefinito). Mercado Envios fornisce prezzi finali. No tax li mostra così come sono; una regola fiscale aggiunge sopra la tua imposta sulla spedizione.

API Mercado Envios (tariffe in tempo reale) (senza token si usano solo i prezzi 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 nei log. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per cambiarlo. Per smettere di usare le tariffe in tempo reale, spunta Remove the saved access token (only the prices below are used then) e salva.

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 di questo paese e sono quotate nella sua valuta.

Exchange rate: serve solo se 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, 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 vengono usati quando non c'è un access token, per destinazioni fuori dal paese di Mercado Envios e quando l'API non fornisce alcuna tariffa. Sono nella valuta predefinita del negozio, IVA esclusa.

Country prices: una tabella di paesi di destinazione e prezzi. Clicca su Add country per aggiungere una riga e sull'icona del cestino per rimuoverla. Scegli * All other countries per tutti i paesi che non hanno 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 corriere in quel caso.

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

Disponibilità

Min weight: il peso minimo del carrello in kg perché questo corriere compaia. 0 significa nessun limite.

Max weight: nasconde il corriere quando il carrello pesa di più, in kg. Vuoto significa 25 kg, 0 significa nessun limite. Un Min weight maggiore di Max weight viene rifiutato al salvataggio.

Minimum subtotal: mostra il corriere solo quando il subtotale del carrello (dopo sconti, prima delle imposte) raggiunge almeno questo importo. Lascia vuoto per mostrarlo sempre.

Ignore shipping zones: offre il corriere per i paesi indicati più sotto senza configurare le sue zone. Al salvataggio il corriere viene aggiunto a tutte le zone, comprese quelle create in seguito. Disattivando l'opzione vengono rimosse le zone che ha aggiunto, e il corriere mantiene le proprie zone.

Countries: i paesi di destinazione per questa modalità. Lascia 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 del carrello (dopo sconti, prima delle imposte) da cui questo corriere è gratuito. In quel caso non viene inviata alcuna richiesta all'API. Lascia vuoto per disattivare.

Avanzate

Debug log: scrive le richieste all'API e il calcolo delle tariffe in logs/vfd_mrcv_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Gli errori vengono sempre registrati, anche con questa opzione disattivata. L'access token e gli indirizzi dei clienti non vengono mai registrati.

Log: mostra la dimensione e le ultime voci del log. Clicca su Clear log per svuotarlo.

Remove data on uninstall: se attiva, la disinstallazione del modulo elimina le impostazioni, il corriere, le tariffe in cache e i log. Se disattiva, tutto viene conservato per una reinstallazione.

Come funziona al checkout

Nel passaggio della spedizione PrestaShop chiede al modulo il prezzo di Mercado Envios. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nel subtotale. Il modulo verifica prima le condizioni: paesi consentiti (con Ignore shipping zones), peso del carrello e subtotale minimo. 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 CAP valido, il modulo descrive il carrello come un unico pacco: la larghezza e la lunghezza maggiori tra i prodotti, la somma delle altezze di tutti i prodotti e il peso totale in grammi. Ogni lato e il peso vengono portati ai minimi di 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 e poi mostrata nella valuta del carrello del cliente.

Ogni preventivo viene memorizzato nella cache per 1 ora, così lo stesso carrello non genera una nuova richiesta. Un preventivo fallito non viene ripetuto per 5 minuti. Se Mercado Pago non è raggiungibile, rifiuta il token o limita le richieste, 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 posto di quelle quando non c'è il token, la destinazione è fuori dal paese di Mercado Envios, il CAP manca o non è valido, manca il tasso di cambio, il pacco è più pesante del limite di 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 corriere viene nascosto. Il cliente non vede mai un errore dell'API.

Se modifichi il corriere in Shipping > Carriers dopo che ha ricevuto ordini, PrestaShop lo salva come nuova versione del corriere. Il modulo segue automaticamente la nuova versione.

Il modulo calcola solo le 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 in tempo reale di Mercado Envios, il modulo conserva il nome del servizio, il tempo di consegna stimato in giorni e la tariffa in tempo reale. Nel back office la pagina dell'ordine mostra un blocco Mercado Envios con Mercado Envios service, Estimated delivery e Live rate (excl. tax). Il cliente vede Mercado Envios service e Estimated delivery nella pagina dei dettagli dell'ordine del proprio account. Gli ordini esistenti non sono influenzati dalle successive variazioni di tariffa.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Mercado Envios è il primo blocco di Modules > Module Manager > VibeFox Mercado Envios > Configure, sopra le impostazioni. Incolla la chiave in License key e clicca su Activate. Dopo di che 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: presta-shipping-mercado-envios 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 cambiare 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 indica 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 Mercado Envios non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. La vetrina di PrestaShop non sa che sei connesso al back office, quindi il corriere viene nascosto anche a te: puoi configurare il modulo prima di acquistare una chiave, ma non testarlo al checkout. Un promemoria compare in Modules > Module Manager nella scheda Alerts. Gli ordini esistenti non sono influenzati.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto 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 ripristinare il modulo 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. 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 alto nella pagina del modulo, i limiti di peso e Minimum subtotal. Il corriere deve avere un prezzo: un access token funzionante per indirizzi nel paese di Mercado Envios, oppure Country prices o Fallback cost. Inoltre, i prodotti possono essere limitati a determinati corrieri nella pagina del prodotto.

Le tariffe in tempo reale non compaiono: attiva Debug log, ricarica il checkout e guarda il campo Log nella pagina del modulo. Motivi comuni: nessun token, una destinazione fuori dal paese di Mercado Envios, un CAP mancante o non valido, un Exchange rate mancante, un pacco oltre il limite di peso, o nessuna opzione di 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 dal pannello sviluppatori di Mercado Pago.

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: clicca su Save nella pagina del modulo. Questo cancella le tariffe in cache.

La pagina dice che il corriere Mercado Envios non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Ripristina il modulo in Modules > Module Manager per crearlo di nuovo.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Mercado Envios e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. Le tariffe in cache vengono sempre rimosse. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini mantengono la cronologia), e vengono rimosse le impostazioni, il log e i dati di servizio salvati degli ordini. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni e i dati di servizio degli ordini vengono conservati. Reinstallando il modulo, il corriere riprende lo stato che aveva prima della disinstallazione.

Mercado Envios e Mercado Pago sono marchi dei rispettivi proprietari. Questo modulo non è affiliato né approvato da Mercado Envios o Mercado Pago.