VibeFox Andreani for OpenCart — Guida

Requisiti

OpenCart: 3.0.x (testato su 3.0.5.0) o 4.0.2 e successivo (testato su 4.1.0.3), con il tema predefinito.

PHP: 8.0 o successivo.

Account Andreani (solo per le tariffe in tempo reale): le tariffe in tempo reale usano l'API di preventivo di Andreani. Andreani assegna ai clienti business credenziali API, un codice cliente e numeri di contratto, di norma a partire da circa 300 spedizioni al mese. Vedi developers.andreani.com oppure scrivi a ventapyme@andreani.com. Ti servono il nome utente e la password dell'API, il codice cliente (código de cliente) e il numero di contratto. Andreani rilascia un contratto separato per ogni servizio (consegna a domicilio, ritiro in filiale). Senza accesso all'API, usa prezzi fissi. Il selettore della filiale funziona senza credenziali.

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_andreani-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_andreani.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. In amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_andreani-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non serve aggiornare Extensions > Modifications. In alternativa all'Installer, puoi 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 Andreani 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 nel campo License key del blocco di licenza in cima alla pagina Edit e clicca su Activate (vedi Chiave di licenza).

5. Imposta il nome, la fonte delle tariffe, i prezzi per paese (per esempio AR=5000) e, per le tariffe in tempo reale, le credenziali API, il codice cliente e il numero di contratto (vedi Configurazione). Clicca su Save.

OpenCart 4

1. In amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_andreani.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 Andreani, 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 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, Enable/Disable e Enable second option sono disattivati, e Andreani non viene offerto al checkout finché non attivi un'opzione e clicchi su Save. Se reinstalli l'estensione dopo una disinstallazione, vengono usate di nuovo le impostazioni Andreani conservate, ma entrambe le opzioni sono disattivate: attivale e clicca su Save.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox Andreani > Edit. Le sezioni sono elencate a sinistra. Un unico pulsante Save salva l'intera pagina senza ricaricarla. Dopo il salvataggio vedi Settings saved. Cached token, branches and rates were cleared. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.

In cima alla pagina compaiono avvisi su impostazioni mancanti: tariffe API selezionate senza nome utente e password API o senza numero di contratto, nessun ARS exchange rate quando la valuta del negozio non è ARS, o nessun prezzo per l'Argentina in Country prices. Un avviso compare anche se l'unità di peso o di lunghezza del negozio non è riconosciuta dall'estensione (i pesi vengono allora letti in kg e le dimensioni in cm).

Al salvataggio vengono rifiutati, senza salvare nulla, un nome vuoto, un nome più lungo di 64 caratteri o contenente uno dei caratteri < > ; = # { }, un Min weight (kg) maggiore di Max weight (kg), o un Sort order che non è un numero intero. Un valore che non è un numero, un numero negativo o un ARS exchange rate pari o inferiore a 0 non viene salvato, e un avviso indica il campo.

Generali

Andreani ha due opzioni al checkout: l'opzione principale, impostata qui e in Andreani API e Delivery and rates, e la Second option. Entrambe compaiono sotto l'intestazione Andreani nel passaggio del metodo di spedizione.

Enable/Disable: attiva o disattiva l'opzione principale di Andreani. Predefinito: disattivato. La seconda opzione ha un proprio interruttore.

Name: il nome dell'opzione principale mostrato al cliente al checkout. Predefinito: Andreani. Obbligatorio.

Tax status: None (the API rate is taken with IVA) (predefinito), oppure una delle tue classi fiscali. Con una classe fiscale, OpenCart aggiunge l'imposta al costo di spedizione, quindi la tariffa dell'API viene presa senza IVA. Con None, la tariffa dell'API viene presa con IVA inclusa. Vale per entrambe le opzioni.

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

Andreani API (necessaria per le tariffe in tempo reale)

Environment: Sandbox / QA (apisqa.andreani.com) (predefinito) oppure Production (apis.andreani.com). Usa l'ambiente a cui appartengono le tue credenziali.

API username: il tuo nome utente per l'API di Andreani.

API password: la tua password per l'API di Andreani. Dopo il salvataggio il campo resta vuoto e mostra Saved - leave empty to keep it. Clearing the API username removes it too. Inserisci un nuovo valore solo se vuoi cambiarlo.

Client code: il codice cliente (código de cliente) fornito da Andreani, per esempio CL0000000.

Contract number: il contratto del servizio usato per le tariffe, per esempio la consegna a domicilio. La seconda opzione può usare un altro contratto, per esempio per il ritiro in filiale.

Origin branch code: filiale di origine facoltativa (sucursalOrigen) per i preventivi. Lascialo vuoto per usare la filiale configurata nel tuo contratto.

Consegna e tariffe

Delivery modality: la modalità dell'opzione principale. La prima parte indica dove Andreani ritira il pacco (il tuo indirizzo o una filiale dove lo consegni). La seconda parte indica dove lo riceve il cliente.

Rate source: come viene calcolato il prezzo.

Country prices: un prezzo fisso per paese di destinazione nella valuta predefinita del negozio, al netto delle imposte, una riga per paese nel formato CC=PREZZO, per esempio AR=5000. Viene usato in modalità fissa e come alternativa in caso di errore dell'API. I paesi senza riga non hanno un prezzo fisso. Le righe in un altro formato vengono ignorate, e un avviso le elenca al salvataggio.

ARS exchange rate: Andreani fattura in pesos argentini. Serve solo se la valuta predefinita del negozio non è ARS: il prezzo di 1 ARS nella valuta del negozio, per esempio 0.001. Senza questo valore, le tariffe dell'API non vengono usate.

Default product weight (kg): usato per i prodotti senza peso quando si richiedono tariffe all'API e si verificano i limiti di peso. Vuoto significa 0,5 kg.

Calculation type: Per order (predefinito) applica il prezzo una volta sola. Per item (price x number of items) moltiplica il prezzo fisso di Country prices per il numero di articoli nel carrello. Una tariffa Andreani in tempo reale riguarda già l'intero carrello e non viene moltiplicata.

Disponibilità

Min weight (kg): il peso minimo del carrello perché l'opzione compaia. 0 significa nessun limite (predefinito).

Max weight (kg): il peso massimo del carrello. Se viene superato, l'opzione viene nascosta. Predefinito: 100. Vuoto significa 100 kg, 0 significa nessun limite.

Minimum subtotal: mostra l'opzione solo quando il subtotale del carrello (prodotti da spedire, dopo il coupon, al netto delle imposte, nella valuta predefinita del negozio) è almeno pari a questo importo. Lascialo vuoto per mostrarla sempre.

Geo zone: offre Andreani 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 usata quando Ignore shipping zones è attivo.

Ignore shipping zones: offre Andreani per i paesi indicati qui sotto, qualunque sia la zona geografica. Predefinito: disattivato.

Countries: i paesi di destinazione per quella modalità. Lascialo vuoto per consentire tutti i paesi. Viene usato solo quando Ignore shipping zones è attivo.

Spedizione gratuita

Free shipping: attiva la soglia per la spedizione gratuita. Predefinito: disattivato.

Free shipping from: il subtotale del carrello (nella valuta predefinita del negozio) da cui la spedizione è gratuita. Richiede che Free shipping sia attivo.

Seconda opzione

Una seconda opzione Andreani con un proprio nome, modalità di consegna e contratto, per esempio "a domicilio" nell'opzione principale e "retiro en sucursal" qui, per offrirle entrambe. Tutte le altre impostazioni sono condivise.

Enable second option: offre la seconda opzione al checkout. Predefinito: disattivato.

Second option name: il nome di questa opzione al checkout. Predefinito: Andreani - branch pickup. Obbligatorio.

Delivery modality: Use global setting oppure una delle quattro modalità. Predefinito: Door to branch (Puerta a Sucursal).

Contract number: Andreani rilascia un contratto separato per ogni servizio (consegna a domicilio, ritiro in filiale). Lascialo vuoto per usare il contratto globale.

Selettore della filiale (mostrato per Door to branch e Branch to branch)

Province select width: la larghezza CSS dell'elenco delle province, per esempio 100% o 300px. Predefinito: 100%.

Branch select width: la larghezza CSS dell'elenco delle filiali, per esempio 100% o 400px. Predefinito: 100%.

Avanzate

Debug log: registra le richieste all'API e i calcoli delle tariffe in storage/logs/vfd_andr_debug.log.php. Il file non può essere letto dal web. Gli errori vengono sempre registrati. Credenziali e token non vengono mai registrati. Quando il file raggiunge 5 MB, viene spostato in vfd_andr_debug.old.log.php e si avvia un nuovo log.

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

Remove data on uninstall: se attivo, disinstallando l'estensione vengono eliminate tutte le impostazioni Andreani e il log. Se disattivo (predefinito), vengono conservate per una reinstallazione. I dati della filiale salvati negli ordini vengono sempre conservati.

Importa / Esporta

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

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di ogni opzione Andreani attiva. Se è impostata una Geo zone e Ignore shipping zones è disattivato, Andreani non viene offerto per indirizzi fuori dalla zona geografica. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non sono inclusi nel subtotale. L'estensione verifica poi i paesi (quando Ignore shipping zones è attivo), il peso del carrello (i pesi dei prodotti vengono convertiti in kg, e i prodotti senza peso usano Default product weight (kg)) e il Minimum subtotal. Il subtotale è il prezzo dei prodotti da spedire, dopo lo sconto del coupon e al netto delle imposte.

In modalità fissa il prezzo viene preso da Country prices. Nelle modalità con tariffe in tempo reale, l'estensione accede all'API di Andreani e richiede un preventivo con il CAP di destinazione, il contratto, il codice cliente, il peso in kg, il volume ricavato dalle dimensioni dei prodotti e il valore dichiarato (il subtotale del carrello in ARS). Una tariffa in tempo reale viene richiesta solo per un CAP argentino valido (4 cifre, oppure un CPA come C1425ABC). L'importo in ARS viene convertito con ARS exchange rate quando la valuta del negozio non è ARS. Il prezzo viene calcolato nella valuta predefinita del negozio, arrotondato alle sue cifre decimali e mostrato al cliente nella sua valuta con l'imposta della Tax status selezionata.

Il token di accesso viene conservato per un massimo di 23 ore e rinnovato automaticamente quando Andreani lo rifiuta. I preventivi vengono memorizzati in cache per 1 ora. Una chiamata API fallita non viene ripetuta per 5 minuti. Tutto questo è salvato nella cache di OpenCart, quindi una voce non viene mai conservata più a lungo della durata della cache di OpenCart (1 ora per impostazione predefinita) e viene semplicemente richiesta di nuovo. Gli errori dell'API non vengono mai mostrati al cliente: l'opzione viene nascosta, oppure nella modalità di ripiego si usa il prezzo fisso. Il motivo viene scritto nel log.

Se Free shipping è attivo e il subtotale del carrello raggiunge Free shipping from, il prezzo è 0. La spedizione gratuita si applica solo dove l'opzione ha un prezzo: se l'API di Andreani non restituisce una tariffa e non c'è un prezzo fisso di ripiego, l'opzione non viene mostrata.

L'estensione non crea spedizioni Andreani, non stampa etichette e non traccia i pacchi. Per queste operazioni usa il portale web di Andreani.

Su OpenCart 4 il cliente clicca su Choose nel blocco del metodo di spedizione della pagina di checkout e sceglie un'opzione Andreani nella finestra Shipping method options. Le opzioni funzionano allo stesso modo che su OpenCart 3; la selezione della filiale è descritta in Punti di ritiro.

Punti di ritiro

Quando viene offerta un'opzione con Door to branch o Branch to branch, subito sotto di essa, nel passaggio del metodo di spedizione, compaiono un elenco di province e un elenco di filiali. La provincia viene preselezionata in base alla regione dell'indirizzo di consegna. L'elenco delle filiali proviene dall'API pubblica delle filiali di Andreani ed è memorizzato in cache per un massimo di 12 ore (entro la durata della cache di OpenCart). Non vengono elencate le filiali che non consegnano pacchi. Il passaggio della consegna non attende mai Andreani: se l'elenco non è ancora in cache, viene caricato in background e il cliente vede per un attimo Loading Andreani branches.... Se non ci sono filiali disponibili, il cliente vede No Andreani branches available right now. Please try again later or choose another shipping method.

La scelta viene salvata appena il cliente la seleziona. Viene accettata solo una filiale dell'elenco Andreani attuale. Senza una filiale, Continue nel passaggio della consegna non prosegue, e il cliente vede Please select an Andreani pickup branch. Il server ricontrolla la filiale quando il cliente prosegue. Se la filiale non è più nell'elenco, il cliente vede The selected Andreani branch is not available. Please choose another one.

Su OpenCart 4 l'elenco delle province e l'elenco delle filiali compaiono nella finestra Shipping method options, subito sotto l'opzione Andreani con filiale, con gli stessi testi e gli stessi controlli. Continue nella finestra senza filiale viene bloccato con il messaggio Please select an Andreani pickup branch. sotto l'opzione. Se il negozio rifiuta la filiale quando il cliente prosegue, il messaggio viene mostrato in cima alla pagina di checkout e la finestra resta aperta. OpenCart 4 conserva un unico ordine per il checkout e lo aggiorna a ogni conferma; la filiale dell'ordine viene aggiornata insieme ad esso, ed è rimossa quando il cliente cambia l'ordine con un altro metodo di spedizione.

Una filiale scelta con un'opzione Andreani non appartiene a un ordine effettuato con un'altra opzione o un altro metodo di spedizione.

Il selettore è pensato per il checkout in una pagina del tema predefinito di OpenCart 3 e per il checkout del tema predefinito di OpenCart 4. Un tema con una struttura diversa del passaggio della consegna potrebbe richiedere modifiche allo script del selettore.

Ordini

L'ordine conserva la modalità di consegna e, per le modalità con filiale, la filiale scelta.

Shipping method of the order: la filiale viene aggiunta al testo del metodo di spedizione, per esempio Andreani - branch pickup: e il nome della filiale. Se il nome dell'opzione non menziona una filiale, prima del nome della filiale viene aggiunto il testo Pickup branch: (oppure Andreani pickup branch: quando il nome non contiene Andreani), per esempio Andreani - Pickup branch: e il nome della filiale. Questo testo compare nelle email d'ordine al cliente e al negozio, nello storico ordini del cliente, sulla fattura e nella pagina dell'ordine in amministrazione. OpenCart limita il testo a 128 caratteri; i dati completi della filiale sono conservati dall'estensione. La pagina di conferma dell'ordine di OpenCart non mostra il metodo di spedizione.

Admin order page: in Sales > Orders, apri un ordine. Un pannello Andreani mostra Andreani modality e, per le modalità con filiale, Andreani branch (nome, ID e provincia). Clicca su Edit, scegli un'altra provincia e un'altra filiale e clicca su Save per cambiarla. Vedi Branch updated., e anche la filiale nel testo del metodo di spedizione dell'ordine viene sostituita. Si possono salvare solo filiali dell'elenco Andreani. Se l'elenco non è disponibile, vedi The Andreani branch list is not available right now - the branch cannot be changed. Cambiare la filiale richiede il permesso di modifica per sale/order e l'accesso a extension/shipping/vfd_andreani (OpenCart 3) o extension/vfd_andreani/shipping/vfd_andreani (OpenCart 4). Il pannello viene mostrato anche per gli ordini già effettuati con Andreani mentre l'estensione è disattivata.

Mentre l'estensione è disattivata, il pannello Andreani non viene mostrato. I dati della filiale restano salvati e il testo del metodo di spedizione dell'ordine non cambia. Gli ordini esistenti conservano i propri dati di filiale.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox Andreani è il primo blocco in Extensions > Extensions > Shipping > VibeFox Andreani > 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-andreani 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 oppure License expired on con una data. Dopo il cambio dell'indirizzo del negozio, o dopo aver liberato un posto per il 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 posto per il dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, le opzioni di spedizione Andreani non vengono mostrate 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 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 il rinnovo. Lo stato viene ricontrollato 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

Andreani non compare al checkout: verifica che la licenza sia attiva e che Enable/Disable sia attivo (per la seconda opzione anche Enable second option), e che tu abbia cliccato su Save dopo l'installazione. Controlla Geo zone, oppure Ignore shipping zones e Countries. Verifica che Country prices abbia una riga per il paese (per i prezzi fissi o come ripiego), i limiti di peso e il Minimum subtotal. Leggi gli avvisi in cima alla pagina Edit. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.

Le tariffe in tempo reale non compaiono: attiva Debug log, ricarica il checkout e controlla il campo Log nella pagina dell'estensione. Mostra il motivo: credenziali o numero di contratto mancanti, accesso fallito (nome utente, password o ambiente errati), nessun CAP argentino valido ancora, nessun tasso di cambio, oppure un errore HTTP di Andreani. Con Andreani API, fixed price if the API fails i clienti ricevono comunque il prezzo fisso mentre risolvi il problema.

Il mio negozio non è in pesos argentini: imposta ARS exchange rate con il valore di 1 ARS nella valuta predefinita del tuo negozio.

L'imposta sulla spedizione sembra sbagliata: con una classe fiscale in Tax status, si usa la tariffa Andreani senza IVA e OpenCart aggiunge la propria imposta. Con None si usa la tariffa con IVA e non viene aggiunta alcuna imposta. Verifica che le imposte siano attive nelle impostazioni del negozio e che la classe fiscale abbia aliquote per l'Argentina.

Nessuna filiale nell'elenco: l'API delle filiali Andreani non ha risposto. Una richiesta fallita viene ripetuta dopo 5 minuti. Controlla il log.

Viene preselezionata la provincia sbagliata: la provincia viene letta dalla regione dell'indirizzo di consegna. Il cliente può sempre scegliere un'altra provincia.

Le tariffe sembrano superate dopo una modifica: clicca su Save nella pagina dell'estensione. Questo svuota il token, l'elenco delle filiali e le tariffe in cache.

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

Per gli sviluppatori: gli host dell'API di Andreani possono essere sostituiti con l'impostazione vfd_andr_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 Andreani. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre lo stato, Sort order, Tax status e Geo zone. L'estensione rimuove sempre i propri gestori della pagina di checkout e dell'ordine, insieme al token, all'elenco delle filiali e alle tariffe in cache. Se Remove data on uninstall è attivo, vengono eliminate anche tutte le impostazioni Andreani e il log di debug. Se è disattivo, le altre impostazioni vengono conservate e riutilizzate alla successiva installazione dell'estensione. I dati di filiale salvati negli ordini non vengono mai eliminati, e gli ordini esistenti conservano il proprio metodo di spedizione e il proprio costo.

Su OpenCart 4, per rimuovere anche i file dell'estensione, dopo la disinstallazione vai su Extensions > Installer e clicca su Uninstall (il pulsante arancione −) accanto a VibeFox Andreani nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso a forma di cestino) per eliminare il pacchetto caricato.

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