VibeFox Econt for OpenCart — Guida

Requisiti

OpenCart: 3.0.x (testato con 3.0.5.0) o 4.0.2 e successive (testato con 4.1.0.3).

PHP: 8.0 o successivo.

Paesi: Bulgaria e Romania devono essere attivati in System > Localisation > Countries.

Econt: non serve un contratto o una chiave API. L'elenco degli uffici è una nomenclatura pubblica di Econt. A Econt viene inviato solo il codice del paese, nessun dato dei clienti. Inserisci un nome utente e una password e-Econt solo se Econt chiede al tuo negozio un'autorizzazione. L'accesso e-Econt è descritto nella pagina per sviluppatori di Econt (econt.com/developers).

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. Estrailo sul tuo computer. Contiene README.txt, il pacchetto OpenCart 3 vfd_econt-oc3-(versione).ocmod.zip e il pacchetto OpenCart 4 vfd_econt.ocmod.zip. Installa solo il pacchetto della 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_econt-oc3-(versione).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 Econt 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 di licenza in alto nella pagina Edit e clicca su Activate (vedi License key).

5. Imposta le tariffe per paese e verifica le altre opzioni (vedi Configuration), attiva Enable/Disable e clicca su Save. Clicca su Load offices from Econt now per verificare la connessione.

OpenCart 4

1. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_econt.ocmod.zip. Non rinominare il file: OpenCart 4 prende 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 ad esso.

3. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox Econt, 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 passi 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/Disable e salvi. Se installi di nuovo l'estensione dopo una disinstallazione, vengono usate le impostazioni che hai conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox Econt > Edit. Le sezioni sono elencate a sinistra. Un pulsante Save salva l'intera pagina senza ricaricarla. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni, caricare gli uffici o svuotare il registro.

In alto nella pagina l'estensione mostra degli avvisi: l'API demo è attiva, per Bulgaria o Romania non è impostata alcuna tariffa (il metodo allora non viene mai mostrato), l'ultima richiesta di uffici per un paese non è riuscita, oppure il tuo negozio non ha una classe di peso con l'unità kg (i pesi dei prodotti vengono letti allora in base al nome della loro unità: kg, g, lb o oz). I campi numerici accettano la virgola decimale, per esempio 5,99. Se un campo numerico contiene qualcosa che non è un numero o un numero negativo, oppure se Minimum weight (kg) è maggiore di Maximum weight (kg), un errore indica il campo e non viene salvato nulla. Lo stesso accade con un Name vuoto o più lungo di 64 caratteri, un Sort order che non è un numero intero, oppure una classe d'imposta o una zona geografica sconosciute.

Generale

Enable/Disable: mostra o nasconde la consegna Econt al checkout. Predefinito: disattivato.

Name: il nome del metodo di spedizione mostrato nel carrello e al checkout. Predefinito: Econt Express. Obbligatorio, massimo 64 caratteri.

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

Tax class: la classe d'imposta della tariffa di spedizione, oppure --- None --- (predefinito). OpenCart aggiunge questa imposta alle tariffe sottostanti. Con --- None --- le tariffe sono definitive.

Elenco degli uffici Econt

Uffici ed Econtomat vengono caricati dall'API Econt e memorizzati nella cache per 24 ore.

Demo API: usa l'API demo di Econt con dati di test. Lasciala disattivata su un negozio attivo. Gli uffici demo hanno ID diversi da quelli reali. In modalità demo, se non è impostato un accesso, viene usato l'account di test pubblico di Econt.

Econt username: facoltativo. Il tuo accesso e-Econt per l'autorizzazione HTTP Basic.

Econt password: facoltativa. Viene salvata nel database del negozio e non viene mai 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 password: attivalo e clicca su Save per eliminare la password salvata.

Office list: mostra quanti uffici sono in cache per paese e quando sono stati caricati. Il pulsante Load offices from Econt now ricarica subito gli elenchi di Bulgaria e Romania e mostra il risultato per paese. Se un caricamento non riesce, restano gli uffici dell'ultimo caricamento riuscito. Senza questo pulsante l'elenco viene caricato automaticamente al primo checkout. Cambiare Demo API, il nome utente o la password svuota gli elenchi in cache.

Selettore dell'ufficio al checkout

Show: quali punti possono scegliere i clienti.

City order: mostra prima le città più grandi (Sofia, Plovdiv, Varna, Bucarest e altre). Se disattivato, le città sono in ordine alfabetico. Predefinito: attivo.

City list width: la larghezza CSS dell'elenco delle città, per esempio 100% o 300px. Predefinito: 100%.

Office list width: la larghezza CSS dell'elenco degli uffici, per esempio 100% o 400px. Predefinito: 100%.

Tariffe (il titolo della sezione mostra la valuta predefinita del tuo negozio)

Le tariffe sono nella valuta predefinita del tuo negozio, IVA esclusa. L'estensione non chiede a Econt tassi in tempo reale. La Bulgaria usa l'euro dal 1° gennaio 2026, quindi un negozio bulgaro di solito inserisce tariffe in EUR.

Price per country: un paese per riga (o separati da virgole): codice paese, due punti, tariffa, per esempio BG:5.99 e RO:8.99 (questi sono i valori predefiniti). Va bene anche la virgola decimale: BG:5,99. Una tariffa di 0 significa consegna gratuita. Se il campo è vuoto si usano le tariffe predefinite BG:5.99 e RO:8.99. Le voci in un altro formato vengono ignorate e segnalate in un avviso al salvataggio. Il resto viene salvato.

Calculation: Per order (predefinito) addebita la tariffa una sola volta. Per item (price x quantity) la moltiplica per il numero di articoli da spedire.

Price for other countries: usata per un paese Econt (Bulgaria o Romania) non elencato sopra. Vuoto o 0 nasconde il metodo lì.

Condizioni

Subtotale del carrello significa i prodotti da spedire, dopo il coupon e prima dell'imposta.

Free shipping from: il subtotale del carrello da cui la consegna è gratuita. Lascia vuoto per non offrire mai la consegna gratuita.

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

Minimum weight (kg): nasconde il metodo per carrelli più leggeri. I pesi dei prodotti vengono convertiti dalla loro classe di peso in kg. Lascia vuoto per nessun limite.

Maximum weight (kg): nasconde il metodo per carrelli più pesanti. Lascia vuoto per nessun limite.

Disponibilità

Econt consegna solo in Bulgaria e Romania. Di norma la zona geografica decide dove viene offerto il metodo; con Ignore geo zone decidono invece i paesi selezionati.

Geo zone: offre Econt solo agli indirizzi di questa zona geografica. All Zones (predefinito) significa in tutta la Bulgaria e la Romania. Le zone geografiche si gestiscono in System > Localisation > Geo Zones. La zona geografica non viene usata con Ignore geo zone.

Ignore geo zone: la zona geografica non viene controllata. Econt viene offerto nei paesi sotto indicati, che l'indirizzo sia o meno nella zona geografica.

Countries: Bulgaria e/o Romania. Usato solo con Ignore geo zone. Nessun paese selezionato significa tutti i paesi Econt.

Avanzate

Debug log: scrive i messaggi di debug in storage/logs/vfd_ecn_debug.log.php (in OpenCart 4 system/storage/logs/vfd_ecn_debug.log.php). Il file non si può leggere dal web. Quando raggiunge 5 MB, viene avviato un nuovo registro. Errori e avvisi dell'API (Econt non raggiungibile, nessun ufficio, un ordine senza ufficio) vengono sempre registrati. Non vengono scritte password o dati dei clienti.

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

Remove data on uninstall: se attivo, la disinstallazione dell'estensione elimina le impostazioni Econt, il registro e le scelte dei checkout non completati. Se disattivo, le impostazioni vengono conservate per una reinstallazione. Gli uffici salvati negli ordini vengono sempre conservati.

Importazione / Esportazione

Export: clicca su Download JSON per salvare le impostazioni in un file JSON. La password 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 password salvata viene conservata.

Come funziona al checkout

Il metodo viene offerto solo per Bulgaria e Romania. Quando OpenCart mostra i metodi di spedizione, chiede all'estensione la tariffa Econt. Con Ignore geo zone la zona geografica non viene controllata e il metodo viene offerto solo per i Countries selezionati (nessuno selezionato = Bulgaria e Romania). Altrimenti, se è impostata una Geo zone, l'indirizzo deve trovarsi al suo interno. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri prodotti non aggiungono peso e non sono inclusi nel subtotale. L'estensione controlla i limiti di peso e il subtotale minimo, poi prende la tariffa per il paese. Se il subtotale del carrello raggiunge Free shipping from, la tariffa è 0. Se per il paese non è disponibile alcun elenco di uffici, il metodo viene nascosto, perché la consegna avviene sempre in un ufficio. La tariffa viene calcolata nella valuta predefinita del negozio e mostrata al cliente nella sua valuta con l'imposta della Tax class selezionata.

Quando il cliente seleziona Econt, sotto il metodo compaiono due elenchi: City e Office / Econtomat. L'elenco degli uffici viene caricato una volta per pagina, solo quando è selezionato Econt. Gli Econtomat sono contrassegnati nell'elenco. La scelta viene salvata subito. Se l'elenco degli uffici non può essere caricato, il cliente vede il messaggio Econt offices cannot be loaded right now. Please try again in a few minutes or choose another shipping method.

Quando il cliente clicca su Continue nel passo del metodo di spedizione, l'estensione verifica sul server che sia stato scelto un ufficio e che esista nell'elenco Econt per il paese di consegna (filtrato da Show). Senza ufficio il cliente vede Please select an Econt office or Econtomat. Un ufficio non presente nell'elenco viene rifiutato con The selected Econt office is not available for the shipping country. Please select it again. Il nome dell'ufficio viene sempre preso dall'elenco Econt, non dal browser.

Su OpenCart 4 il cliente clicca su Choose nel blocco del metodo di spedizione della pagina di checkout e sceglie Econt nella finestra Shipping method options. Gli elenchi City e Office / Econtomat compaiono in quella finestra sotto il metodo e funzionano come descritto sopra. Il pulsante Continue della finestra non va avanti senza un ufficio valido, con gli stessi messaggi.

L'elenco degli uffici è memorizzato nella cache per 24 ore, separatamente per l'API live e quella demo e per ogni paese. Se Econt non risponde, viene usato l'ultimo elenco valido e Econt non viene interrogato di nuovo per 10 minuti. Il timeout dell'API è di 15 secondi. L'elenco degli uffici proviene da https://ee.econt.com/services/ (live) oppure da https://demo.econt.com/ee/services/ (demo).

L'estensione usa solo tariffe fisse. Non chiede a Econt tariffe in tempo reale, non crea lettere di vettura o etichette, non prenota corrieri, non traccia i pacchi, non gestisce il contrassegno e non consegna a un indirizzo. Solo Bulgaria e Romania hanno un elenco di uffici.

Punti di ritiro

Quando l'ordine viene effettuato, l'ufficio scelto al checkout viene salvato con l'ordine: la città, il nome e l'indirizzo dell'ufficio e il codice dell'ufficio Econt. Usa il codice dell'ufficio quando crei la spedizione in e-Econt.

Cliente: l'ufficio viene aggiunto al metodo di spedizione dell'ordine, per esempio Econt Express - Econt office / Econtomat: city, office (address) (massimo 128 caratteri; in OpenCart 4 il testo non viene accorciato). Così compare nella cronologia ordini del cliente, nelle e-mail dell'ordine, nella fattura e nell'ordine nell'amministrazione. OpenCart 4 mantiene un solo ordine per il checkout e lo aggiorna ogni volta che il cliente conferma di nuovo, e l'ufficio dell'ordine viene aggiornato con esso.

Pagina dell'ordine nell'amministrazione: in Sales > Orders, il pannello Econt office / Econtomat sopra la cronologia mostra l'ufficio e il suo codice, anche se il metodo viene disattivato in seguito. Sotto Change scegli un'altra città e un altro ufficio del paese dell'ordine e clicca su Save. Il pannello mostra Saved., il testo del metodo di spedizione dell'ordine viene aggiornato e una nota nella cronologia dell'ordine (non inviata al cliente) registra l'ufficio precedente e quello nuovo. Se clicchi su Save senza scegliere un ufficio, il pannello dice Select a city and an office first - nothing was changed. Un ufficio non presente nell'elenco del paese dell'ordine viene rifiutato con The selected Econt office is not available for the shipping country - nothing was changed. Qualsiasi utente amministratore con il permesso di modifica degli ordini può cambiare l'ufficio; non serve l'accesso alle impostazioni dell'estensione. Se l'elenco degli uffici non può essere caricato, il pannello mostra Econt offices cannot be loaded right now. Un ordine effettuato senza ufficio mostra No Econt office is saved for this order., e il registro contiene un errore per esso.

I nomi degli uffici vengono mostrati nella lingua locale (cirillico per la Bulgaria) quando la lingua del negozio è il bulgaro o il rumeno, altrimenti in inglese.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox Econt è il primo blocco della pagina Extensions > Extensions > Shipping > VibeFox Econt > Edit, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (per esempio la data fino a cui 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-econt 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 indica il motivo, per esempio Key not found, This key belongs to another product, Domain limit reached o License expired on e 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. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, il metodo di spedizione Econt 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 ancora il metodo nel negozio, contrassegnato come (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 viene 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 supporto richiedono un rinnovo. Lo stato viene ricontrollato automaticamente quando apri la Dashboard dell'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 un cron job. La disinstallazione dell'estensione rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Econt non compare al checkout: verifica che la licenza sia attiva e che Enable/Disable sia attivo, e che il paese di consegna sia Bulgaria o Romania (attivato in System > Localisation > Countries). Controlla Geo zone (oppure Ignore geo zone e Countries), che per il paese sia impostata una tariffa, i limiti di peso e Minimum subtotal. Controlla la riga Office list nelle impostazioni: il metodo è nascosto finché per il paese non c'è un elenco di uffici. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.

L'elenco degli uffici non si carica: clicca su Load offices from Econt now e leggi il risultato, oppure l'avviso in alto nella pagina delle impostazioni. Gli errori vengono sempre scritti nel registro; attiva Debug log per più dettagli e guarda il campo Log. Se Econt richiede un'autorizzazione per il tuo negozio, compila Econt username ed Econt password.

I clienti vedono uffici di prova: Demo API è attiva. Disattivala su un negozio attivo.

In quale valuta sono le tariffe? Nella valuta predefinita del tuo negozio, IVA esclusa. I clienti le vedono nella loro valuta.

L'imposta viene addebitata sopra la tariffa: è selezionata una classe d'imposta. Imposta Tax class su --- None --- se le tue tariffe includono già l'IVA.

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

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox Econt. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre eliminati. OpenCart ripristina sempre Enable/Disable, Sort order, Tax class e Geo zone. L'estensione rimuove sempre i propri eventi e gli elenchi degli uffici in cache. Se Remove data on uninstall è attivo, vengono eliminate anche le altre impostazioni, il registro e le scelte dei checkout non completati. Se è disattivo, le impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. Gli uffici salvati negli ordini 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, vai su Extensions > Installer dopo la disinstallazione e clicca su Uninstall (il pulsante arancione −) accanto a VibeFox Econt nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso del cestino) per rimuovere il pacchetto caricato.

Econt è un marchio del rispettivo proprietario. Questa estensione non è affiliata a Econt né approvata da Econt.