VibeFox Envioclick for OpenCart — Guida
Requisiti
OpenCart: 3.0.x (testato con 3.0.5.0) o 4.0.2 e successivi (testato con 4.1.0.3).
PHP: 8.0 o successivo.
Account Envioclick (solo per le tariffe in tempo reale): un account Envioclick in Messico o in Colombia con accesso all'API. La chiave API si trova nel tuo account Envioclick in Mi cuenta (in alto a destra) > Información del API. Se usi solo tariffe fisse, non ti serve un account Envioclick.
User-Agent (solo Messico): Envioclick Messico richiede un valore User-Agent per ogni richiesta API. Chiediglielo all'assistenza Envioclick (soporte.tecnico@envioclick.com).
Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un 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_envioclick-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_envioclick.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. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_envioclick-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non devi aggiornare Extensions > Modifications. Invece dell'installer puoi anche 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 Envioclick e clicca su Install (il pulsante verde +).
3. Clicca 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 alto nella pagina Edit, e clicca su Activate (vedi Chiave di licenza).
5. Inserisci la chiave API, scegli il paese dell'API, inserisci lo User-Agent (Messico), il codice postale di partenza o il codice DANE e l'indirizzo di partenza. Se la valuta predefinita del tuo negozio non è MXN o COP, inserisci il tasso di conversione. Facoltativamente aggiungi tariffe fisse per paese e un costo di riserva. Attiva Enable Envioclick e clicca su Save.
OpenCart 4
1. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_envioclick.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. Clicca su Install (il pulsante verde +) accanto a esso.
3. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox Envioclick, clicca 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 in entrambe le versioni.
Dopo l'installazione il metodo resta disattivato finché non attivi Enable Envioclick e salvi. Se installi di nuovo l'estensione dopo una disinstallazione, vengono usate le impostazioni Envioclick che hai conservato.
Configurazione
Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox Envioclick > Edit. Le sezioni sono elencate a sinistra. Un pulsante Save in fondo salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella anche i preventivi Envioclick in cache. I campi numerici accettano sia il punto sia la virgola come separatore decimale. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.
La sezione General mostra avvisi quando le tariffe in tempo reale non possono funzionare con le impostazioni salvate: nessun tasso di conversione per una valuta del negozio diversa da MXN o COP, nessuno User-Agent per il Messico, nessun codice postale o codice DANE di partenza, o nessun indirizzo di partenza per la Colombia. Avvisa anche se l'unità di peso o di lunghezza del negozio non viene riconosciuta; in tal caso aggiungi una classe di peso con l'unità kg in System > Localisation > Weight Classes o una classe di lunghezza con l'unità cm in System > Localisation > Length Classes. Al salvataggio l'estensione verifica che Method title abbia da 1 a 64 caratteri, che i campi numerici contengano numeri non negativi, che Currency conversion rate sia maggiore di 0, che Minimum weight (kg) non sia maggiore di Maximum weight (kg), che il codice di partenza abbia 5 cifre per il Messico o 8 cifre (o il codice comunale a 5 cifre) per la Colombia, che ogni riga di Price per country abbia un paese valido e un prezzo, e che Sort order sia un numero intero. Se una verifica non riesce, non viene salvato nulla e la pagina elenca gli errori.
Generale
Il cliente vede una sola tariffa Envioclick, quella del corriere più economico o più veloce. Puoi limitare il metodo a una zona geografica o a paesi in Availability.
Enable Envioclick: mostra o nasconde Envioclick al checkout. Predefinito: disattivato.
Method title: il nome del metodo di spedizione mostrato al cliente nel carrello e al checkout, massimo 64 caratteri. Predefinito: Envioclick Shipping. Obbligatorio.
Carrier in the title: aggiunge al titolo il corriere Envioclick e il tempo di consegna stimato di una tariffa in tempo reale, per esempio «Envioclick Shipping (Estafeta Express, 1 day)». OpenCart salva questo titolo con l'ordine, quindi compare anche nelle e-mail dell'ordine e nelle pagine degli ordini. Il corriere viene comunque salvato nell'ordine. Predefinito: attivo.
Sort order: la posizione di Envioclick tra i metodi di spedizione al checkout. Un numero intero.
API Envioclick (tariffe in tempo reale)
Facoltativo. Senza chiave API vengono usate solo le tariffe fisse. La sezione rimanda alla documentazione dell'API Envioclick per il Messico e la Colombia. Le tariffe in tempo reale vengono richieste solo per destinazioni nel paese dell'API. La spedizione verso altri paesi usa le tariffe fisse.
API key: la tua chiave API Envioclick, presa da Mi cuenta > Información del API. Viene inviata nell'intestazione «Authorization» e non viene mai mostrata ai clienti né scritta nel registro. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per cambiarlo.
Remove the saved API key: attivalo e salva per eliminare la chiave salvata; da quel momento vengono usate solo le tariffe fisse. Una chiave inserita in API key sostituisce quella salvata. L'interruttore si disattiva da solo dopo il salvataggio.
API country: il paese del tuo account Envioclick.
User-Agent (Mexico): il valore rilasciato dall'assistenza Envioclick (soporte.tecnico@envioclick.com), per esempio EcUserAgent-2/123456. Obbligatorio per il Messico; senza di esso non vengono richieste tariffe in tempo reale per il Messico. Facoltativo per la Colombia.
Carrier choice: Cheapest (predefinito) oppure Fastest (then cheapest). Envioclick restituisce preventivi di più corrieri e il cliente riceve una sola tariffa.
Branch pickup rates: tiene conto anche delle tariffe «Ocurre», in cui il cliente ritira il pacco presso la filiale del corriere. Quando è disattivato, vengono usate solo le tariffe di consegna a domicilio. I servizi con contrassegno (COD) non vengono mai usati. Predefinito: disattivato.
Currency conversion rate: Envioclick calcola in MXN (Messico) o COP (Colombia). Se la valuta predefinita del tuo negozio è diversa, inserisci il valore di 1 MXN o 1 COP nella valuta del tuo negozio, per esempio 0,05. Anche il valore dichiarato del pacco viene convertito allo stesso modo. Lascia vuoto il campo se la valuta del negozio è MXN o COP. Senza di esso non vengono usate tariffe in tempo reale con un'altra valuta.
Spedizione da
Usato per le tariffe in tempo reale. OpenCart non ha un codice postale, una città o una via per il negozio, quindi inseriscili qui.
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á; un codice comunale a 5 cifre (11001) viene completato con 000.
Origin address: via e numero dell'indirizzo di ritiro. Obbligatorio per la Colombia, facoltativo per il Messico.
Tariffe fisse
Usate quando non c'è una tariffa in tempo reale: nessuna chiave API, una destinazione fuori dal paese dell'API, un errore dell'API o nessun corriere per la tratta.
Price per country: un elenco di paesi e prezzi nella valuta predefinita del tuo negozio, IVA esclusa. Clicca su Add country per aggiungere una riga e sul pulsante × per rimuoverne una. Scegli * All other countries per un prezzo usato per ogni paese senza una riga propria.
Fallback cost: usato quando non c'è una tariffa in tempo reale e nessuna riga della tabella corrisponde. Lascia vuoto per nascondere il metodo in questo caso.
Fixed price applies: Per order (predefinito) 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 (predefinito).
Maximum weight (kg): nasconde il metodo sopra questo peso del carrello. Predefinito: 25. 0 significa nessun limite.
Minimum order amount: mostra il metodo solo quando il subtotale dei prodotti da spedire (dopo il coupon, prima dell'imposta) è almeno questo importo. Lascia vuoto per mostrarlo sempre.
Free shipping from: spedizione gratuita quando il subtotale dei prodotti da spedire (dopo il coupon, prima dell'imposta) raggiunge questo importo. In quel caso non viene inviata alcuna richiesta all'API. Lascia vuoto per non offrire mai la spedizione gratuita.
Tax class: la classe d'imposta del costo di spedizione, oppure No tax (predefinito). I preventivi Envioclick includono già le imposte dei corrieri, quindi scegli No tax per non addebitare l'imposta due volte sulla spedizione.
Disponibilità
Di norma il metodo viene offerto per gli indirizzi nella zona geografica selezionata, oppure ovunque.
Geo zone: offre Envioclick solo per gli indirizzi in questa zona geografica. All zones (predefinito) significa nessun limite. Le zone geografiche si gestiscono in System > Localisation > Geo Zones. Non viene verificata quando Ignore shipping zones è attivo.
Ignore shipping zones: non verifica la zona geografica; decide l'elenco di paesi sottostante. Predefinito: disattivato.
Countries: i paesi di destinazione per questa modalità. Lascia vuoto per consentire tutti i paesi. Usato solo quando Ignore shipping zones è attivo.
Avanzate
Debug log: scrive i calcoli delle tariffe e gli errori dell'API in storage/logs/vfd_evc_debug.log.php (su OpenCart 4 system/storage/logs/vfd_evc_debug.log.php). Il file non si può leggere dal web. La chiave API e gli indirizzi dei clienti non vengono registrati. Finché il registro è disattivato non viene scritto nulla, nemmeno gli errori dell'API. Disattivalo quando hai finito. Quando il file raggiunge 5 MB viene spostato in vfd_evc_debug.old.log.php e viene avviato un nuovo registro.
Log: mostra la dimensione e le ultime voci del registro di debug. Clicca su Clear log per svuotarlo.
Remove data on uninstall: se attivo, la disinstallazione dell'estensione elimina le impostazioni Envioclick, i preventivi in cache e il registro. Se disattivo (predefinito), vengono conservati per una reinstallazione. I dati Envioclick degli ordini effettuati vengono sempre conservati.
Importazione / Esportazione
Export: clicca su Download JSON per salvare le impostazioni in un file JSON. La chiave API non viene esportata.
Import: incolla un JSON esportato in precedenza e clicca su Import per ripristinare le impostazioni, per esempio su un altro negozio. I valori vengono controllati come in un normale salvataggio. La chiave API salvata viene conservata.
Come funziona al checkout
Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di Envioclick. Se è impostata una Geo zone (e Ignore shipping zones è disattivato) e l'indirizzo si trova al di fuori di essa, Envioclick non viene offerto. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri prodotti non aggiungono peso e non sono inclusi nell'importo dell'ordine. Poi l'estensione verifica le condizioni: i paesi di Ignore shipping zones, il peso del carrello e l'importo minimo dell'ordine. L'importo dell'ordine è il prezzo dei prodotti da spedire, dopo lo sconto del coupon e prima dell'imposta. 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 Envioclick.
Se è impostata una chiave API e la destinazione si trova nel paese dell'API, l'estensione chiede a Envioclick i preventivi. In Messico la richiesta viene fatta quando il cliente ha inserito un codice postale a 5 cifre. In Colombia viene fatta quando il comune viene riconosciuto da un codice DANE a 8 cifre nel campo del codice postale, oppure dal dipartimento (la regione dell'indirizzo OpenCart) e dalla città; un nome di città unico in Colombia viene riconosciuto anche senza il dipartimento. Accenti e maiuscole non contano. L'estensione sceglie il preventivo più economico o più veloce che non sia contrassegno e lo converte nella valuta predefinita del negozio. Il prezzo viene arrotondato ai decimali di quella valuta e mostrato al cliente nella sua valuta con l'imposta della Tax class selezionata.
Il pacco è sempre un unico collo: il peso totale convertito in kg dalle classi di peso dei prodotti, e una misura della scatola ricavata dalle dimensioni dei prodotti convertite in cm. I prodotti senza dimensioni contano come 10 × 10 × 10 cm. Un carrello senza alcun peso viene spedito come 0,5 kg. Il valore dichiarato è l'importo dell'ordine.
Ogni preventivo viene memorizzato nella cache per 1 ora per la stessa tratta e lo stesso pacco. Una richiesta non riuscita viene memorizzata per 10 minuti, così un'API non disponibile non rallenta ogni aggiornamento del checkout. Se Envioclick restituisce un errore o nessun corriere per la tratta, il cliente non vede alcun errore: viene usato il prezzo fisso o il costo di riserva, oppure il metodo viene nascosto. Il motivo viene scritto nel registro di debug, quando è attivo.
L'estensione calcola solo tariffe. Non crea lettere di vettura o etichette, non richiede ritiri, non traccia né annulla spedizioni. Offre una sola tariffa, non una scelta tra corrieri, e non usa servizi con contrassegno né preventivi multi-pacco. I preventivi in tempo reale riguardano solo le spedizioni nazionali.
Su OpenCart 4 il cliente clicca su Choose nel blocco del metodo di spedizione della pagina di checkout e sceglie Envioclick nella finestra Shipping method options. Il metodo funziona come su OpenCart 3.
Ordini
Quando un ordine viene effettuato con Envioclick, la tariffa calcolata al checkout viene salvata con l'ordine e non cambia più. In Sales > Orders la pagina dell'ordine mostra il pannello Envioclick shipping con Envioclick carrier, Estimated delivery e Envioclick rate ID (per una tariffa in tempo reale), Price source (Envioclick live rate, Fixed price per country, Fallback cost oppure Free shipping threshold) e Calculated price (excl. tax). Il pannello viene mostrato anche dopo che il metodo è stato disattivato.
Su OpenCart 4 il checkout mantiene un solo ordine e lo aggiorna ogni volta che il cliente conferma di nuovo. La tariffa salvata viene quindi sostituita con l'ultima tariffa del checkout. Se il cliente passa a un altro metodo di spedizione, il pannello non viene più mostrato per quell'ordine. Le modifiche all'ordine nell'amministrazione non cambiano la tariffa salvata.
Se Carrier in the title è attivo, il corriere fa parte del nome del metodo di spedizione dell'ordine. Se è disattivo, nell'e-mail di nuovo ordine e nella pagina dell'ordine nell'account del cliente viene aggiunta una riga Shipping carrier: con il corriere di una tariffa in tempo reale, finché l'estensione è attiva. Crea la lettera di vettura nel tuo account Envioclick. Gli ordini effettuati con un prezzo fisso non hanno un corriere Envioclick.
Chiave di licenza
L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox Envioclick è il primo blocco di Extensions > Extensions > Shipping > VibeFox Envioclick > Edit, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Poi il blocco mostra la chiave mascherata, lo stato (per esempio la data fino alla quale la licenza è valida 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-envioclick 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 cambiare la chiave. I testi del blocco seguono la lingua dell'amministrazione (sono inclusi inglese e russo).
Se la chiave non viene accettata, il blocco spiega 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, l'estensione continua a funzionare con l'ultimo stato noto.
Una chiave funziona su un 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, Envioclick non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Un utente amministratore che ha effettuato l'accesso all'amministrazione nello stesso browser vede comunque il metodo nel negozio, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e testare 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 dell'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 dell'amministrazione o la pagina Edit: una volta al giorno nei primi 14 giorni dopo l'inserimento della chiave, poi una volta a settimana. Non serve alcun cron job. La disinstallazione dell'estensione rimuove sempre la chiave di licenza e lo stato della licenza.
Risoluzione dei problemi
Envioclick non compare al checkout: verifica che la licenza sia attiva e che Enable Envioclick sia attivo. Controlla Geo zone, oppure Ignore shipping zones e Countries, i limiti di peso e Minimum order amount. Senza una tariffa in tempo reale, il metodo richiede un prezzo fisso per il paese, una riga * All other countries oppure un Fallback cost. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.
Le tariffe in tempo reale non compaiono: leggi gli avvisi nella sezione General, poi attiva Debug log, ricarica il checkout e controlla il campo Log nella pagina dell'estensione. Cause comuni: nessun tasso di conversione (la valuta del negozio non è MXN né COP), nessuno User-Agent (Messico), nessun codice postale o codice DANE di partenza, il codice postale del cliente (Messico) o la città (Colombia) non è ancora inserito, la destinazione è fuori dal paese dell'API, oppure nessun corriere per la tratta.
Perché serve un tasso di conversione? Envioclick restituisce prezzi solo in pesos messicani o colombiani. L'estensione non mostra mai un importo in pesos come se fosse in un'altra valuta.
Colombia: la città non viene riconosciuta: verifica che il cliente selezioni il dipartimento come regione dell'indirizzo e digiti correttamente il nome del comune. Funziona anche un codice DANE a 8 cifre digitato come codice postale.
L'imposta sulla spedizione viene addebitata due volte: i preventivi Envioclick includono già le imposte dei corrieri. Imposta Tax class su No tax.
Dopo una modifica le tariffe sembrano obsolete: clicca su Save nella pagina dell'estensione. Questo cancella i preventivi in cache.
La pagina dice "Warning: You do not have permission to modify VibeFox Envioclick!": il tuo gruppo di utenti amministratori può solo visualizzare le impostazioni. Concedi al gruppo il permesso di modifica per extension/shipping/vfd_envioclick (OpenCart 3) o extension/vfd_envioclick/shipping/vfd_envioclick (OpenCart 4) in System > Users > User Groups.
Per gli sviluppatori: l'indirizzo dell'API di preventivo Envioclick può essere sostituito con l'impostazione vfd_evc_api_url (per i test); non ha un campo nella pagina delle impostazioni.
Disinstallazione
Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox Envioclick. OpenCart ripristina sempre Enable Envioclick, Sort order, Tax class e Geo zone. I preventivi in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, vengono eliminate anche le impostazioni Envioclick e il registro di debug. Se è disattivo, le altre impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. I dati Envioclick degli ordini effettuati vengono conservati in entrambi i casi, e gli ordini mantengono il loro metodo di spedizione e il loro costo.
Per rimuovere anche i file dell'estensione su OpenCart 4, vai su Extensions > Installer dopo la disinstallazione e clicca su Uninstall (il pulsante arancione −) accanto a VibeFox Envioclick nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per eliminare il pacchetto caricato.
Envioclick è un marchio del rispettivo proprietario. Questa estensione non è affiliata a Envioclick né approvata da Envioclick.