VibeFox Mercado Envios 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 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-): 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. 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. 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_mercado_envios in /wp-content/plugins/ tramite FTP.

2. Clicca su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox Mercado Envios, oppure clicca su Settings sotto il nome del plugin nella pagina Plugins.

4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e clicca su Activate.

5. Per le tariffe in tempo reale, incolla l'Access Token, scegli il paese di Mercado Envios e, se la valuta del negozio non è ARS, BRL o MXN, il tasso di cambio. Facoltativamente compila Country prices e Fallback cost (usati senza tariffe in tempo reale).

6. Aggiungi VibeFox Mercado Envios a una zona di spedizione in WooCommerce > Settings > Shipping > Shipping zones, oppure attiva Ignore shipping zones e scegli i paesi.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox Mercado Envios. 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 generale.

Gli avvisi in cima alla pagina segnalano problemi di configurazione: tasso di cambio mancante, nessun access token e nessun prezzo, e l'ultimo errore dell'API Mercado Envios con la sua data. Ogni volta che salvi le impostazioni, le tariffe in cache vengono cancellate.

Generale

Enable/Disable: attiva o disattiva la spedizione Mercado Envios in tutte le zone contemporaneamente.

Name: il nome del metodo di spedizione mostrato ai clienti al checkout. Predefinito: Mercado Envios.

Tax status: Mercado Envios fornisce prezzi finali. None li mostra così come sono, Taxable aggiunge sopra l'imposta sulla spedizione di WooCommerce.

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

Access token: il tuo Access Token di produzione di Mercado Pago (APP_USR-...). Viene inviato solo a Mercado Pago e non viene mai registrato nel log.

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: necessario solo se la valuta del negozio è diversa da quella di Mercado Envios: il prezzo di 1 ARS, BRL o MXN nella valuta del negozio, per esempio 0.001. Senza di esso le tariffe in tempo reale non vengono usate. Sono accettati sia il punto sia la virgola come separatore decimale.

Prezzi senza tariffe in tempo reale

Questi prezzi vengono usati quando manca l'access token, per destinazioni fuori dal paese di Mercado Envios e quando l'API non restituisce alcuna tariffa.

Country prices: prezzi nella valuta del negozio. Clicca su + Add country per aggiungere una riga e sulla croce per rimuoverne 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. 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 questo 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 ciascun articolo e lo moltiplica per la quantità. 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.

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

Minimum subtotal: mostra il metodo solo quando il subtotale del carrello è almeno questo importo. Lascialo vuoto per mostrarlo sempre.

Excluded shipping classes: nasconde il metodo quando un articolo del carrello appartiene a una di queste classi di spedizione di WooCommerce.

Ignore shipping zones: offre il metodo per i paesi indicati sotto, anche senza averlo aggiunto a una zona di spedizione.

Countries: i paesi di destinazione per quella modalità. Lascia vuoto per tutti i paesi. Questo campo è usato solo quando Ignore shipping zones è attivo.

Spedizione gratuita

Free shipping from: il subtotale del carrello da cui questo metodo è gratuito. In questo caso non viene inviata alcuna richiesta a Mercado Envios. Lascialo vuoto per disattivarlo.

Avanzate

Debug log: registra le richieste all'API e il calcolo delle tariffe in WooCommerce > Status > Logs (origine vfd-mercado-envios). Gli errori vengono sempre registrati, anche con questa opzione disattivata. L'access token e gli indirizzi dei clienti non vengono mai registrati.

Remove data on uninstall: se attiva, eliminare il plugin rimuove tutte le sue impostazioni e i metodi nelle zone. Disattivare il plugin non elimina mai le impostazioni.

Come funziona al checkout

Quando il cliente inserisce un indirizzo di consegna, WooCommerce chiede al plugin una tariffa. Il plugin verifica prima le condizioni: peso del carrello, subtotale minimo e classi di spedizione escluse. Se si applica la spedizione gratuita, il metodo costa 0 e non viene inviata alcuna richiesta a Mercado Envios.

Per una destinazione nel paese di Mercado Envios con un codice postale valido, il plugin descrive il carrello come un unico pacco: la larghezza e la lunghezza maggiori tra gli articoli, la somma delle altezze di tutti gli articoli e il peso totale in grammi. Ogni lato e il peso vengono portati ai minimi Mercado Envios del paese, così anche i prodotti senza dimensioni o peso ricevono 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 del negozio e mostrata con il nome del tuo metodo.

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 o rifiuta il token, tutti i preventivi in tempo reale vengono sospesi 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 manca il token, la destinazione è fuori dal paese di Mercado Envios, il codice postale manca o non è valido, manca il tasso di cambio, il pacco supera il limite di peso 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 metodo viene nascosto. Il cliente non vede mai un errore dell'API.

Il metodo funziona con il checkout classico e con i blocchi Carrello e Checkout. È compatibile con WooCommerce High-Performance Order Storage (HPOS).

Il plugin 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 una tariffa per metodo, 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 l'ordine viene effettuato con una tariffa in tempo reale, il nome del servizio e il tempo di consegna stimato in giorni vengono salvati nella riga di spedizione dell'ordine come Mercado Envios service ed Estimated delivery. 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 Mercado Envios. Incolla la chiave in License key e clicca su Activate. Il blocco mostra lo stato, per esempio la data fino a cui la licenza è attiva, e il tuo dominio. Usa Check now per controllare 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 il suo posto per il dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, Mercado Envios non viene mostrato ai clienti al checkout. I gestori del negozio che hanno effettuato l'accesso lo vedono ancora, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Sulla pagina Plugins e sulle pagine di WooCommerce compare un promemoria. 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 controllato di nuovo automaticamente in background.

Risoluzione dei problemi

Mercado Envios 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 consentito). Controlla gli avvisi in cima alla pagina delle impostazioni, i limiti di peso, Minimum subtotal ed Excluded shipping classes. Il metodo richiede un prezzo: un access token funzionante per indirizzi nel paese di Mercado Envios, oppure Country prices o Fallback cost.

Le tariffe in tempo reale non compaiono: attiva Debug log, ricarica il checkout e apri WooCommerce > Status > Logs, origine vfd-mercado-envios. Cause tipiche: 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 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 e Fallback cost sono nella valuta 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.

Le tariffe sembrano obsolete dopo una modifica: salva la pagina delle impostazioni. Così vengono cancellate 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 un posto 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 conserva tutte le impostazioni. Viene cancellata solo la cache delle tariffe. Per rimuoverlo, disattivalo e poi eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin, le tariffe in cache e l'ultimo errore dell'API vengono sempre rimossi. Le impostazioni e i metodi delle zone vengono rimossi solo se era attiva l'opzione Remove data on uninstall. Altrimenti restano disponibili per una reinstallazione futura. Gli ordini esistenti mantengono le loro righe di spedizione.

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