VibeFox Envioclick for WooCommerce — Guida

Requisiti

WordPress: 5.8 o successivo.

WooCommerce: 5.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.

PHP: 8.0 o successivo.

Account Envioclick (solo per le tariffe in tempo reale): un account Envioclick in Messico o Colombia con accesso API. La chiave API si trova nel tuo account Envioclick, in Mi cuenta (in alto a destra) > Información del API. Se usi solo prezzi fissi, non ti serve un account Envioclick.

User-Agent (solo Messico): Envioclick Messico richiede un valore User-Agent in ogni richiesta API. Chiedilo al supporto Envioclick (soporte.tecnico@envioclick.com).

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 fai clic su Install Now. Puoi anche caricare la cartella vfd_envioclick in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox Envioclick, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugins.

4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in alto nella pagina e fai clic su Activate.

5. Inserisci la chiave API, scegli il paese API, inserisci lo User-Agent (Messico), il codice postale o il codice DANE di partenza e l'indirizzo di partenza. Se la valuta del negozio non è MXN o COP, inserisci il tasso di cambio.

6. Facoltativo: aggiungi prezzi fissi per paese e un costo di riserva.

7. Aggiungi VibeFox Envioclick 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 Envioclick. Si applicano a tutte le zone di spedizione. Quando aggiungi il metodo a una zona, la finestra della zona ha un solo campo:

Title (zone): il nome che i clienti vedono per questa zona. Lascialo vuoto per usare il Method title generale.

Quando è impostata una chiave API, il plugin mostra avvisi in cima alla pagina se le tariffe in tempo reale non possono funzionare: nessun tasso di cambio per una valuta del negozio diversa da MXN o COP, nessuno User-Agent per il Messico, nessun codice postale o codice DANE di partenza, oppure nessun indirizzo di partenza per la Colombia. Ogni volta che salvi le impostazioni, le tariffe in cache vengono cancellate. I campi numerici accettano sia il punto sia la virgola come separatore decimale.

Generali

Enable/Disable: attiva o disattiva il metodo in tutte le zone contemporaneamente. Predefinito: attivo.

Method title: il nome del metodo di spedizione mostrato nel carrello e al checkout. Una zona può sostituirlo. Predefinito: Envioclick Shipping.

Carrier in the title: mostra il corriere e il tempo di consegna stimato accanto al titolo per le tariffe in tempo reale, per esempio «Envioclick Shipping (Estafeta Express, 1 day)». Il corriere viene comunque salvato nell'ordine e mostrato nelle email d'ordine. Predefinito: attivo.

API Envioclick (tariffe in tempo reale)

Facoltativo. Senza chiave API vengono usati solo i prezzi fissi. Le tariffe in tempo reale vengono richieste solo per destinazioni nel paese API. Le spedizioni verso altri paesi usano i prezzi fissi.

API key: la tua chiave API Envioclick, da Mi cuenta > Información del API.

API country: il paese del tuo account Envioclick.

User-Agent (Messico): il valore emesso dal supporto Envioclick (soporte.tecnico@envioclick.com). Obbligatorio per il Messico; senza di esso non vengono richieste tariffe in tempo reale per il Messico. Facoltativo per la Colombia.

Scelta del corriere: Cheapest (predefinito) oppure Fastest (then cheapest). Envioclick restituisce tariffe di diversi corrieri e il cliente riceve un'unica tariffa.

Branch pickup rates: considera anche le tariffe «Ocurre», con cui il cliente ritira il pacco presso la filiale del corriere. Se disattivato, vengono usate solo le tariffe per la consegna a domicilio. I servizi di pagamento alla consegna (COD) non vengono mai usati. Predefinito: disattivato.

Currency conversion rate: Envioclick calcola in MXN (Messico) o COP (Colombia). Se la valuta del negozio è diversa, inserisci il valore di 1 MXN o 1 COP nella valuta del negozio, per esempio 0.05. Il valore dichiarato del pacco viene convertito allo stesso modo. Lascialo vuoto se la valuta del negozio è MXN o COP. Senza di esso, le tariffe in tempo reale non vengono usate in un'altra valuta.

Spedizione da

Usato per le tariffe in tempo reale. I campi vuoti vengono ripresi dall'indirizzo del negozio in WooCommerce > Settings > General se il negozio si trova nel paese API.

Origin postcode / DANE code: Messico: il codice postale a 5 cifre. Colombia: il codice DANE a 8 cifre del comune, per esempio 11001000 per Bogotá.

Origin address: via e numero dell'indirizzo di ritiro. Obbligatorio per la Colombia, facoltativo per il Messico.

Prezzi fissi

Usati quando non c'è una tariffa in tempo reale: nessuna chiave API, destinazione fuori dal paese API, errore dell'API o nessun corriere per la tratta.

Price per country: una tabella di paesi e prezzi nella valuta del negozio. Fai clic su + Add country per aggiungere una riga e sulla crocetta per rimuoverla. La riga * Default si applica a tutti i paesi senza una riga propria.

Fallback cost: usato quando non c'è una tariffa in tempo reale e nessuna riga della tabella corrisponde. Lascialo vuoto per nascondere il metodo in questo caso.

Fixed price applies: Per order addebita il prezzo una sola volta. Per item (price × quantity) lo moltiplica per il numero di articoli nel carrello. Le tariffe Envioclick in tempo reale sono sempre per spedizione.

Condizioni

Minimum weight (kg): nasconde il metodo sotto questo peso del carrello. 0 significa nessun limite.

Maximum weight (kg): nasconde il metodo sopra questo peso del carrello. Predefinito: 25. 0 significa nessun limite.

Minimum order amount: mostra il metodo solo se il subtotale del carrello (dopo sconti, prima delle tasse) è almeno questo importo. Lascialo vuoto per mostrarlo sempre.

Free shipping from: spedizione gratuita quando il subtotale del carrello (dopo sconti, prima delle tasse) raggiunge questo importo. In questo caso non viene inviata alcuna richiesta all'API. Lascialo vuoto per non offrire mai la spedizione gratuita.

Excluded shipping classes: nasconde il metodo se il carrello contiene un prodotto di una di queste classi di spedizione di WooCommerce.

Tax status: Taxable aggiunge l'imposta di WooCommerce al costo di spedizione, None no. Le tariffe Envioclick includono già le imposte dei corrieri, quindi scegli None per non far pagare l'imposta sulla spedizione due volte.

Disponibilità senza zone di spedizione

Ignore shipping zones: offre Envioclick per i paesi indicati di seguito anche se non è aggiunto a una zona di spedizione.

Countries: i paesi di destinazione per questa modalità. Lascialo vuoto per usare tutti i paesi in cui spedisci. Viene usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: registra i calcoli delle tariffe e gli errori dell'API in WooCommerce > Status > Logs, origine vfd_envioclick. La chiave API e gli indirizzi dei clienti non vengono registrati. Disattivalo quando hai finito.

Remove data on uninstall: se attivo, eliminando il plugin vengono rimosse tutte le impostazioni Envioclick, i metodi di zona e le tariffe in cache. La disattivazione del 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 controlla prima il peso del carrello, l'importo minimo dell'ordine e le classi di spedizione escluse. Se si applica la spedizione gratuita, il metodo viene mostrato con prezzo zero e non parte alcuna richiesta verso Envioclick.

Se è impostata una chiave API e la destinazione si trova nel paese API, il plugin chiede a Envioclick le tariffe. In Messico la richiesta viene fatta quando il cliente ha inserito un codice postale a 5 cifre. In Colombia viene fatta quando dipartimento e comune sono riconosciuti (accenti e maiuscole non contano, «Bogotá D.C.» funziona). Il plugin sceglie la tariffa di consegna a domicilio più economica o più veloce che non sia contrassegno, e la converte nella valuta del negozio.

Il pacco è sempre un unico collo: il peso totale convertito in kg, e la lunghezza e la larghezza dell'articolo più grande con un'altezza che mantiene il volume totale di tutti gli articoli. I prodotti senza dimensioni contano come 10 × 10 × 10 cm. Un carrello senza peso viene inviato come 0,5 kg. Il valore dichiarato è il subtotale del carrello.

Ogni tariffa viene memorizzata nella cache per 1 ora per la stessa tratta e lo stesso pacco. Una richiesta non riuscita viene memorizzata nella cache per 10 minuti, così un'API non disponibile non rallenta ogni aggiornamento del checkout. Il timeout dell'API è di 10 secondi. Se Envioclick restituisce un errore o non c'è corriere per la tratta, il cliente non vede alcun errore: viene usato il prezzo fisso oppure il metodo viene nascosto. Il motivo viene scritto nel registro di debug.

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

Il plugin calcola solo tariffe. Non crea guide di spedizione né etichette, non richiede ritiri e non traccia né annulla spedizioni. Offre una sola tariffa, non una scelta tra corrieri, e non usa servizi di pagamento alla consegna, assicurazioni extra né tariffe per più colli. Le tariffe in tempo reale valgono solo a livello nazionale.

Ordini

Quando un ordine viene effettuato con una tariffa Envioclick in tempo reale, il corriere e il servizio vengono salvati nell'ordine. La schermata degli ordini dell'amministrazione mostra Envioclick carrier con il tempo di consegna stimato sotto l'indirizzo di spedizione. La pagina dell'ordine del cliente e le email d'ordine (HTML e testo semplice) mostrano Shipping carrier. L'ID della tariffa Envioclick della quotazione viene salvato con la riga di spedizione dell'ordine come dato nascosto; non compare nella schermata dell'ordine. Crea la guida di spedizione nel tuo account Envioclick.

Gli ordini effettuati con un prezzo fisso non hanno corriere.

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 Envioclick. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, per esempio la data fino alla quale 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 lo slot del dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, Envioclick non viene mostrato ai clienti al checkout. I gestori del negozio che hanno effettuato l'accesso lo vedono ancora, contrassegnato come (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 ricontrollato automaticamente in background.

Risoluzione dei problemi

Envioclick 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 sia consentito). Controlla i limiti di peso, Minimum order amount e Excluded shipping classes. Senza una tariffa in tempo reale, il metodo richiede un prezzo fisso per il paese, una riga * Default oppure un Fallback cost.

Le tariffe in tempo reale non compaiono: leggi gli avvisi in cima alla pagina delle impostazioni, poi attiva il Debug log, ricarica il checkout e apri WooCommerce > Status > Logs, origine vfd_envioclick. Cause comuni: nessun tasso di cambio (la valuta del negozio non è MXN o COP), nessuno User-Agent (Messico), nessun codice postale o codice DANE di partenza, codice postale (Messico) o città (Colombia) del cliente non ancora inserito, destinazione fuori dal paese API oppure nessun corriere per la tratta.

Perché serve un tasso di cambio? Envioclick restituisce prezzi solo in pesos messicani o colombiani. Il plugin non mostra mai un importo in pesos come se fosse un'altra valuta.

Colombia: la città non viene riconosciuta: il cliente deve scegliere il dipartimento e digitare il nome del comune. Funziona anche un codice DANE a 8 cifre digitato come codice postale. Gli sviluppatori possono fornire un codice DANE con il filtro vfd_evc_dane_code.

L'imposta sulla spedizione viene addebitata due volte: le tariffe Envioclick includono già le imposte dei corrieri. Imposta Tax status su None.

Le tariffe sembrano non aggiornate dopo una modifica: salva la pagina delle impostazioni. Così vengono cancellate le tariffe in cache.

Filtri per sviluppatori: vfd_evc_quotation_request (corpo della richiesta), vfd_evc_api_url, vfd_evc_dane_code, vfd_evc_default_dimensions e vfd_evc_package_description.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera uno slot nel tuo account vibefox.net e fai clic su Check now. Se l'indirizzo del sito è cambiato, fai clic 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

La disattivazione del plugin mantiene tutte le impostazioni e i metodi di zona; vengono cancellate solo le tariffe in cache. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato di licenza di questo plugin vengono sempre rimossi. Impostazioni, metodi di zona e tariffe in cache vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano per una futura reinstallazione. Il corriere salvato negli ordini passati viene conservato, e gli ordini esistenti mantengono le proprie righe di spedizione.

Envioclick è un marchio del rispettivo titolare. Questo plugin non è affiliato a Envioclick né approvato da Envioclick.