VibeFox Frenet for OpenCart — Guida

Requisiti

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

PHP: 8.0 o successivo.

Account Frenet (solo per le quotazioni in tempo reale): crea un account gratuito nel pannello Frenet (painel.frenet.com.br), attiva i corrieri che usi e copia il tuo token API. Se usi solo prezzi fissi, non ti serve un account Frenet.

Prodotti: compila peso e dimensioni per prezzi accurati. I prodotti senza questi dati vengono quotati come 0,3 kg e 16 × 11 × 2 cm (la scatola Correios minima).

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un solo 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_frenet-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_frenet.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. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_frenet-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non serve aggiornare Extensions > Modifications. Invece dell'installer puoi anche copiare il contenuto della cartella upload di questo pacchetto nella cartella radice del tuo negozio.

2. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox Frenet e clicca su Install (il pulsante verde +).

3. Clicca su Edit (il pulsante a forma di matita) per aprire la pagina delle impostazioni.

4. Inserisci la tua chiave di licenza VibeFox in License key nel blocco di licenza in cima alla pagina Edit e clicca su Activate (vedi Chiave di licenza).

5. Incolla il token API e inserisci il CEP di origine. Se la valuta predefinita non è il BRL, inserisci il tasso di cambio BRL. Facoltativamente aggiungi prezzi fissi e un costo di riserva. Attiva Enable Frenet e clicca su Save.

OpenCart 4

1. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_frenet.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 ad esso.

3. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox Frenet, clicca su Install (il pulsante verde +), poi su Edit (il pulsante a forma di matita).

4. Inserisci la chiave di licenza e le impostazioni come ai 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 Frenet e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni Frenet che hai conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox Frenet > Edit. Le sezioni sono elencate a sinistra. Un unico pulsante Save in fondo salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella anche le quotazioni Frenet in cache. I campi dei prezzi accettano sia il punto sia la virgola come separatore decimale. Se un valore non è corretto, non viene salvato nulla e la pagina mostra il motivo, per esempio Enter a valid method title (64 characters max, without < > ; = # { })., "…" must be a number. o "…" must not be negative. Vengono rifiutati anche un BRL exchange rate pari a 0 o inferiore e un Minimum weight (kg) superiore a Maximum weight (kg). Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.

In cima alla pagina, e di nuovo dopo ogni salvataggio, l'estensione mostra degli avvisi: manca il token API (si usano solo prezzi fissi, oppure il metodo non viene mai mostrato se non ci sono nemmeno prezzi fissi), manca il CEP di origine, il CEP di origine non ha 8 cifre, oppure la valuta predefinita non è il BRL e manca il tasso di cambio. Avvisa anche se nel negozio non esiste una classe di peso con unità kg o una classe di lunghezza con unità cm. In tal caso pesi e dimensioni dei prodotti vengono convertiti in base al nome dell'unità della loro classe, e le unità sconosciute vengono lette come kg o cm. Controlla System > Localisation > Weight Classes e Length Classes.

Generale

Le impostazioni valgono per tutte le zone geografiche. Puoi limitare il metodo a una zona geografica in Conditions, oppure usare Ignore shipping zones. Il prezzo proviene sempre da questa estensione.

Enable Frenet: mostra o nasconde Frenet al checkout. Predefinito: disattivato.

Method title: il nome del metodo di spedizione mostrato al cliente nel carrello e al checkout. Predefinito: Frenet. Obbligatorio, massimo 64 caratteri, senza i caratteri < > ; = # { }.

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

Quotazioni Frenet in tempo reale

Frenet confronta i corrieri attivati nel tuo account Frenet (Correios, Jadlog, Loggi e altri) e restituisce i loro prezzi per il carrello. Le quotazioni in tempo reale vengono richieste solo per indirizzi in Brasile con un CEP completo di 8 cifre. La sezione contiene un link al pannello Frenet.

API token: il tuo token API Frenet, preso dal pannello Frenet. Lascia vuoto il campo per usare solo prezzi fissi. Dopo il salvataggio il campo resta vuoto e mostra A token is saved — leave empty to keep it. Inserisci un nuovo valore solo per cambiarlo. Per eliminare il token salvato, spunta Remove the saved token e salva.

Origin CEP: il codice postale (CEP) da cui vengono spediti i pacchi, per esempio 01001-000. OpenCart non ha un codice postale del negozio, quindi le quotazioni in tempo reale richiedono questo campo. Un CEP senza 8 cifre viene salvato così come lo digiti, e la pagina mostra Frenet: the origin CEP must have 8 digits.

Service to offer: Cheapest service (predefinito) oppure Fastest service. Frenet restituisce più servizi e il metodo mostra un solo prezzo. Il corriere, il servizio e il tempo di consegna scelti vengono salvati con l'ordine.

BRL exchange rate: Frenet quota in reais brasiliani. Se la valuta predefinita non è il BRL, inserisci quanto vale 1 BRL nella tua valuta predefinita, per esempio 0.16. La quotazione e il valore dichiarato dell'ordine vengono convertiti con questo tasso. Senza di esso le quotazioni in tempo reale non vengono usate. Quando la valuta predefinita è il BRL, il campo indica che i prezzi Frenet vengono usati così come sono.

Prezzi fissi

Si usano quando non c'è un token API, per i paesi che Frenet non serve e ogni volta che Frenet non restituisce un prezzo (API non disponibile, CEP non servito).

Price per country: una tabella con le colonne Country, Price, XS, S, M, L e XL, con prezzi nella valuta predefinita, IVA esclusa. Clicca su Add country per aggiungere una riga. Le colonne di taglia dipendono dal peso del carrello: XS fino a 1 kg, S fino a 2 kg, M fino a 3 kg, L fino a 5 kg, XL oltre 5 kg. Si usa Price quando la colonna di taglia è vuota. Un Price pari a 0 significa spedizione gratuita per quel paese. Usa * Default (all other countries) per tutti i paesi senza una riga propria. Le righe senza alcun prezzo vengono rimosse al salvataggio.

Fallback cost: usato quando né Frenet né la tabella forniscono un prezzo. Lascialo vuoto per nascondere il metodo.

Fixed price applies: Per order (predefinito) addebita il prezzo una sola volta. Per item (price × quantity) lo moltiplica per il numero di articoli. Questo vale solo per i prezzi fissi e per il costo di riserva. Le quotazioni Frenet coprono già l'intero carrello.

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: 30 (usato anche quando il campo è vuoto). 0 significa nessun limite. Non può essere inferiore a Minimum weight (kg).

Minimum order amount: mostra il metodo solo se il subtotale dei prodotti che richiedono spedizione (dopo il coupon, al netto delle tasse) raggiunge almeno questo importo. Lascialo vuoto per mostrarlo sempre.

Free shipping from: il subtotale (dopo il coupon, al netto delle tasse) da cui la spedizione è gratuita. Lascialo vuoto per non offrire mai la spedizione gratuita.

Tax class: la classe fiscale aggiunta al costo di spedizione, oppure No tax. I prezzi Frenet sono i prezzi finali del corriere. Scegli No tax se OpenCart non deve applicarvi alcuna imposta.

Geo zone: offri Frenet solo per indirizzi di questa zona geografica. All zones significa nessun limite. Non si usa con Ignore shipping zones. Le zone geografiche si gestiscono in System > Localisation > Geo Zones.

Disponibilità senza zone di spedizione

Di norma il metodo viene offerto nella zona geografica selezionata in Conditions (in tutte le zone se non ne è selezionata nessuna).

Ignore shipping zones: offri Frenet per i paesi indicati di seguito, qualunque sia la zona geografica corrispondente. La Geo zone in Conditions non viene quindi verificata.

Countries: i paesi di destinazione per questa modalità, scelti tra i paesi attivi del tuo negozio. Lascialo vuoto per usare tutti i paesi verso cui spedisci. Si usa solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: registra ogni richiesta e risposta di quotazione in storage/logs/vfd_frn_debug.log.php (su OpenCart 4 system/storage/logs/vfd_frn_debug.log.php). Il file non è leggibile dal web. Gli errori dell'API vengono sempre registrati. Il token non viene mai registrato e il CEP del cliente viene abbreviato. Disattivalo quando hai finito. Quando il file raggiunge 5 MB, viene spostato in vfd_frn_debug.old.log.php e si avvia un nuovo registro.

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

Remove data on uninstall: se attivo, disinstallando l'estensione vengono eliminate tutte le impostazioni Frenet e il registro. Se disattivo, tutto viene conservato per una reinstallazione. Le quotazioni in cache vengono sempre rimosse. I servizi Frenet salvati con gli ordini fanno parte dello storico degli ordini e vengono conservati.

Importa / Esporta

Export: clicca su Download JSON per salvare le impostazioni in un file JSON. Il token API non viene esportato.

Import: incolla un JSON esportato in precedenza e clicca su Import per ripristinare le impostazioni, per esempio su un altro negozio. I valori vengono verificati come in un normale salvataggio. Il token API salvato viene conservato.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di Frenet. Se è impostata una Geo zone (e Ignore shipping zones è disattivato) e l'indirizzo è al di fuori di essa, Frenet non viene offerto. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non sono inclusi nell'importo dell'ordine. L'estensione controlla poi l'elenco dei paesi (se Ignore shipping zones è attivo), il peso del carrello e l'importo minimo dell'ordine. L'importo dell'ordine è il prezzo dei prodotti che richiedono spedizione, dopo lo sconto del coupon e al netto delle tasse. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata alcuna richiesta a Frenet.

Per un indirizzo in Brasile con un CEP completo di 8 cifre, e quando il token API e il CEP di origine sono impostati, l'estensione invia a Frenet il CEP di origine e quello di destinazione, ogni articolo del carrello (peso in kg, dimensioni in cm, quantità, il Model del prodotto e le sue categorie), il valore dell'ordine in BRL e il codice coupon del carrello. Finché il CEP è incompleto non viene fatta alcuna richiesta. Frenet restituisce i servizi dei corrieri attivati. I servizi con errore o senza prezzo vengono saltati. L'estensione sceglie il servizio più economico o il più veloce e converte il prezzo nella valuta predefinita. Il prezzo viene arrotondato secondo i decimali della valuta predefinita e mostrato al cliente nella sua valuta con l'imposta della Tax class selezionata.

Ogni risposta viene memorizzata nella cache per 1 ora per lo stesso carrello e lo stesso indirizzo. Una richiesta non riuscita, o un CEP che nessun corriere attivato serve, viene ricordato per 10 minuti. Il timeout dell'API è di 10 secondi. In questi casi il cliente non vede alcun errore: si usa il prezzo fisso o il costo di riserva, oppure il metodo viene nascosto se non ce n'è nessuno. Il motivo viene scritto nel registro. Per gli indirizzi fuori dal Brasile si usano solo i prezzi fissi.

Su OpenCart 4 il cliente clicca su Choose nel blocco dei metodi di spedizione della pagina di checkout e sceglie Frenet nella finestra Shipping method options. Il metodo funziona allo stesso modo che su OpenCart 3.

L'estensione calcola solo le tariffe. Non crea spedizioni, non stampa etichette e non traccia i pacchi. Mostra un servizio Frenet per carrello, non più di uno, e non prevede punti di ritiro o armadietti. Frenet quota solo entro il Brasile; per gli altri paesi usa i prezzi fissi.

Ordini

Quando un ordine viene effettuato con Frenet, l'estensione salva come è stato calcolato il prezzo di spedizione: esattamente l'opzione che il cliente ha visto nel passaggio della spedizione, senza una nuova richiesta a Frenet. La pagina dell'ordine in Sales > Orders mostra quindi un blocco Frenet con queste righe:

Carrier: il corriere e il servizio Frenet, per esempio un servizio Correios o Jadlog. Mostrato per le quotazioni in tempo reale.

Delivery time: il tempo di consegna in giorni lavorativi restituito da Frenet. Mostrato per le quotazioni in tempo reale.

Price source: Live Frenet quote, Fixed price (price per country), Fallback cost o Free shipping.

Su OpenCart 4 il blocco viene mostrato sopra History. OpenCart 4 aggiorna lo stesso ordine quando il cliente lo conferma di nuovo: anche i dati Frenet salvati vengono aggiornati e, se il cliente ha scelto un altro metodo di spedizione, i dati Frenet dell'ordine vengono rimossi.

Il blocco viene mostrato anche quando l'estensione è disattivata. Questi dati vengono conservati alla disinstallazione dell'estensione, anche con Remove data on uninstall.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox Frenet è il primo blocco della pagina Extensions > Extensions > Shipping > VibeFox Frenet > 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 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 si trovano la riga Product: opencart-shipping-frenet e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo gli utenti amministratori con il permesso di modifica 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 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 solo 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, Frenet 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 provare l'estensione prima di acquistare una chiave. Su OpenCart 4 questa anteprima non è disponibile: il negozio non vede l'accesso all'amministrazione, 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 supporto richiedono un rinnovo. Lo stato viene controllato di nuovo 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 a settimana. Non serve alcun cron job. Disinstallando l'estensione vengono sempre rimossi la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Frenet non appare al checkout: verifica che la licenza sia attiva e che Enable Frenet sia attivo. Controlla la Geo zone, oppure Ignore shipping zones e Countries, i limiti di peso e Minimum order amount. Controlla gli avvisi in cima alla pagina dell'estensione. Motivi tipici: il cliente non ha ancora inserito un CEP completo di 8 cifre e non ci sono prezzi fissi, oppure Frenet non ha restituito alcun servizio per la tratta e non c'è un prezzo fisso. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.

Le quotazioni in tempo reale non appaiono: attiva Debug log, ricarica il checkout e controlla il campo Log nella pagina dell'estensione. Mostra il motivo: manca il CEP di origine, manca il tasso di cambio BRL, il CEP del cliente è incompleto, c'è un limite di peso o di importo, oppure compaiono i messaggi dei servizi saltati.

Il registro indica che il token API è stato rifiutato (HTTP 401 o 403): copia di nuovo il token dal pannello Frenet e incollalo in API token.

Il registro indica che Frenet non ha restituito servizi: attiva almeno un corriere nel pannello Frenet.

Il mio negozio vende in euro o dollari: Frenet risponde in BRL. Inserisci il BRL exchange rate (quanto vale 1 BRL nella tua valuta predefinita).

Sul prezzo Frenet viene applicata un'imposta: i prezzi Frenet sono i prezzi finali del corriere. Imposta Tax class su No tax.

Le tariffe sembrano obsolete dopo una modifica: clicca su Save nella pagina dell'estensione. Questo cancella le quotazioni Frenet in cache.

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

Per gli sviluppatori: l'indirizzo di richiesta delle quotazioni Frenet può essere sostituito con l'impostazione vfd_frn_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 Frenet. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable Frenet, Sort order, Tax class e Geo zone. Le quotazioni in cache vengono sempre rimosse. L'evento OpenCart dell'estensione viene rimosso anch'esso (su OpenCart 4 anche gli eventi che salvano i dati Frenet dei nuovi ordini), quindi il blocco Frenet non viene più mostrato nella pagina dell'ordine. I dati Frenet salvati con gli ordini vengono conservati e mostrati di nuovo dopo una reinstallazione. Se Remove data on uninstall è attivo, vengono eliminate anche le impostazioni Frenet e il registro di debug. Se è disattivo, le altre impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. Gli ordini esistenti conservano il loro metodo di spedizione e il 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 Frenet nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per eliminare il pacchetto caricato.

Frenet è un marchio registrato del rispettivo titolare. Questa estensione non è affiliata a Frenet né approvata da Frenet.