VibeFox Aramex 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).

PHP: 8.0 o successivo.

Account Aramex (solo per le tariffe in tempo reale): le tariffe in tempo reale usano l'API Aramex Rate Calculator. Aramex concede l'accesso API ai titolari di account. Chiedi al tuo account manager Aramex oppure consulta l'Aramex Developers Solution Center sul sito di Aramex. Servono sei valori: nome utente API (di solito un indirizzo e-mail), password, numero di account, PIN dell'account, codice dell'entità dell'account (per esempio DXB) e codice paese dell'account (per esempio AE). Se usi solo prezzi fissi per paese, non ti serve un account Aramex.

Chiave di licenza VibeFox: acquistata 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_aramex-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_aramex.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_aramex-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non devi aggiornare Extensions > Modifications. Invece dell'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 Aramex 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, poi clicca su Activate (vedi Chiave di licenza).

5. Scegli come viene calcolato il costo di spedizione, compila le sezioni corrispondenti (vedi Configurazione), attiva Enable Aramex e clicca su Save.

OpenCart 4

1. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_aramex.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 Aramex, 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 il metodo resta disattivato finché non attivi Enable Aramex e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni Aramex che hai conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox Aramex > Edit. Le sezioni sono elencate a sinistra. Un unico pulsante Save in fondo salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella anche le tariffe Aramex in cache. Se un valore non è corretto, non viene salvato nulla e la pagina mostra il motivo, per esempio Enter a method title (1 to 64 characters)., un messaggio che indica che un campo deve essere un numero, oppure The account country code must have 2 letters, e.g. AE. Possono salvare le impostazioni solo gli utenti amministratori con il permesso di modifica per questa estensione.

Generale

Le impostazioni valgono per tutte le zone geografiche. Puoi limitare il metodo a una zona geografica e a determinati paesi in Conditions.

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

Method title: il nome del metodo di spedizione che il cliente vede nel carrello e al checkout. Predefinito: Aramex. Obbligatorio.

Shipping cost: come viene calcolato il prezzo.

Il motivo per cui manca una tariffa in tempo reale viene scritto nel registro di debug. Non viene mai mostrato al cliente.

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

Account API Aramex (necessario solo per le tariffe in tempo reale; tutti e sei i campi sono obbligatori)

Username: il tuo nome utente API Aramex, di solito un indirizzo e-mail. Svuotarlo cancella anche la password salvata.

Password: la tua password API Aramex. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per cambiarlo.

Account number: il numero cliente del tuo account Aramex. Svuotarlo cancella anche il PIN salvato.

Account PIN: il PIN del tuo account Aramex. Come la password, non viene più mostrato dopo il salvataggio.

Account entity: il codice dell'entità (ufficio) Aramex del tuo account, per esempio DXB, AMM o RUH.

Account country code: il codice paese a 2 lettere del tuo account Aramex, per esempio AE.

Servizio Aramex (usato per le tariffe in tempo reale)

Se l'indirizzo di consegna si trova nel paese di origine, la spedizione viene quotata come Domestic. Tutte le altre spedizioni vengono quotate come International express.

International service: il prodotto Aramex per le spedizioni all'estero: PPX Priority Parcel Express (predefinito), PDX Priority Document Express, PLX Priority Letter Express (documenti sotto 0,5 kg), DPX Value Express Parcels, EPX Economy Parcel Express, EDX Economy Document Express, GPX Ground Parcel Express o GDX Ground Document Express.

Domestic service: il prodotto Aramex per le spedizioni all'interno del paese di origine: ONP Overnight (Parcel) (predefinito), OND Overnight (Document), SMP Same Day (Parcel), SMD Same Day (Document), SDD Same Day Delivery, EMD Early Morning Delivery, PEC Economy Delivery, PEX Road Express oppure HVY Heavy (20 kg e oltre).

Payment type: chi paga Aramex per la spedizione: Prepaid (shipper pays) (predefinito), Collect (receiver pays) oppure Third party. Di solito Prepaid.

API weight unit: l'unità inviata ad Aramex: Kilograms (KG) (predefinito) oppure Pounds (LB). I pesi dei prodotti vengono convertiti dalla loro classe di peso, le dimensioni dalla loro classe di lunghezza. Il peso fatturabile è il maggiore tra il peso reale e il peso volumetrico (lunghezza × larghezza × altezza in cm / 5000). Il minimo è 0,5 kg, che vale anche per i prodotti senza peso.

Currency conversion rate: Aramex viene invitato a quotare nella valuta predefinita del tuo negozio. Se risponde comunque in un'altra valuta, la tariffa viene moltiplicata per questo numero (1 unità della valuta di Aramex = X unità della valuta predefinita del tuo negozio). Lascia il campo vuoto per rifiutare queste quotazioni, così un cliente non viene mai addebitato in una valuta sbagliata.

Spedizione da (usato per le tariffe in tempo reale)

Origin country: il paese da cui spedisci. La prima opzione, Store country, usa il paese del tuo negozio.

Origin city: la città da cui spedisci. Aramex la richiede. L'indirizzo del negozio in OpenCart è un testo libero, quindi la città non viene mai ricavata da lì: inseriscila qui.

Origin state / emirate: facoltativo.

Origin postcode: facoltativo.

Se il paese di origine è il paese del tuo negozio, uno stato vuoto viene ricavato dalla regione del negozio in System > Settings > Store > Local.

Prezzi fissi (usati quando Shipping cost è Fixed prices, e come riserva per le tariffe in tempo reale)

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. I paesi senza prezzo (quando non c'è una riga *) non hanno una tariffa fissa, quindi il metodo viene nascosto per loro.

Fixed price applies: Per order (predefinito) addebita il prezzo una volta. Per item (price × quantity) lo moltiplica per il numero di articoli nel carrello. Le tariffe Aramex in tempo reale sono sempre calcolate 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: 100. 0 significa nessun limite. Se lasci vuoto il campo, si usano 100 kg.

Minimum order amount: mostra il metodo solo quando il subtotale dei prodotti da spedire (dopo il coupon, prima delle imposte) raggiunge questo importo. Lascia vuoto il campo per mostrarlo sempre.

Free shipping: attiva la spedizione Aramex gratuita dall'importo sotto indicato.

Free shipping from: il subtotale dei prodotti da spedire (dopo il coupon, prima delle imposte) da cui la spedizione è gratuita. Usato solo quando Free shipping è attivo.

Tax class: la classe d'imposta del costo di spedizione, oppure No tax (predefinito). Le tariffe Aramex in tempo reale possono già includere l'IVA. In tal caso scegli No tax, così l'imposta non viene applicata due volte sulla spedizione.

Geo zone: offri Aramex solo per gli indirizzi in questa zona geografica. All zones (predefinito) significa nessun limite. Le zone geografiche si gestiscono in System > Localisation > Geo Zones.

Countries: offri Aramex solo per questi paesi di destinazione. Lascia vuoto il campo per consentire tutti i paesi. Questo limite si applica insieme a Geo zone.

Avanzate

Debug log: scrive i calcoli delle tariffe e gli errori dell'API in storage/logs/vfd_armx_debug.log.php. Il file non può essere letto dal web. Password, PIN e indirizzi dei clienti non vengono mai registrati. Disattiva il registro quando hai finito. Quando il file raggiunge 5 MB, viene spostato in vfd_armx_debug.old.log.php e si avvia un nuovo registro.

Log: mostra la dimensione e le voci più recenti del registro di debug. Clicca su Clear log per svuotarlo.

Remove data on uninstall: se attivo, disinstallando l'estensione vengono eliminate le impostazioni Aramex, le tariffe in cache e il registro. Se disattivo (predefinito), vengono conservati per una reinstallazione.

Importa / esporta

Esporta: clicca su Download JSON per salvare le impostazioni in un file JSON. Password e PIN non vengono esportati.

Importa: incolla il 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 e il PIN salvati vengono mantenuti.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo Aramex. Se è impostata una Geo zone e l'indirizzo è al di fuori di essa, Aramex 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. L'estensione controlla poi le condizioni: paesi consentiti, peso del carrello e importo minimo dell'ordine. L'importo dell'ordine è il prezzo dei prodotti da spedire, dopo lo sconto del coupon e prima delle imposte. 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 ad Aramex.

In modalità prezzi fissi il prezzo viene preso dalla tabella. Nelle modalità in tempo reale l'estensione invia ad Aramex gli indirizzi di partenza e di consegna, il peso fatturabile, il servizio e la valuta predefinita del negozio, e usa il totale restituito. Una tariffa in tempo reale viene richiesta solo se l'indirizzo di consegna ha una città o un codice postale. Il prezzo viene calcolato nella valuta predefinita del negozio, arrotondato alle sue decimali e mostrato al cliente nella sua valuta con l'imposta della Tax class selezionata.

Ogni risposta viene memorizzata nella cache per 1 ora, così lo stesso carrello non genera una nuova richiesta. Una richiesta non riuscita viene memorizzata nella cache per 10 minuti, così il checkout non attende Aramex a ogni aggiornamento. Il timeout dell'API è di 10 secondi.

Se Aramex restituisce un errore, un importo pari a zero o una quotazione in un'altra valuta senza tasso di conversione, il cliente non vede alcun errore. Il metodo viene nascosto, oppure in modalità di riserva viene usato il prezzo fisso. Il motivo viene scritto nel registro di debug.

L'estensione calcola solo le tariffe. Non crea spedizioni Aramex, non stampa etichette, non prenota ritiri, non traccia i pacchi e non permette ai clienti di scegliere un ufficio Aramex. Non aggiunge nulla agli ordini: l'ordine mostra il nome del metodo e il costo di spedizione come qualsiasi altro metodo di spedizione di OpenCart. Il pacco viene sempre inviato ad Aramex come un unico collo.

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

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox Aramex è il primo blocco nella pagina Extensions > Extensions > Shipping > VibeFox Aramex > 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-aramex e il collegamento 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 nella 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, il metodo di spedizione Aramex 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 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 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

Aramex non compare al checkout: verifica che la licenza sia attiva e che Enable Aramex sia attivo. Controlla Geo zone, Countries, i limiti di peso e Minimum order amount. In modalità prezzi fissi, verifica che il paese o * All other countries abbia un prezzo. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.

Le tariffe in tempo reale non compaiono: attiva il Debug log, ricarica il checkout e controlla il campo Log nella pagina dell'estensione. Mostra il motivo: credenziali API mancanti, codice di errore Aramex, nessuna città di partenza, nessuna città o codice postale di consegna, un limite di peso o di importo, oppure una quotazione in un'altra valuta. Con Aramex live rates, fixed prices if the API fails i clienti ricevono comunque il prezzo fisso mentre risolvi il problema.

Errore ERR75 nel registro: Aramex ha rifiutato l'accesso. Controlla nome utente, password, numero di account, PIN, entità e codice paese con il tuo account manager Aramex.

Quotazione in un'altra valuta rifiutata: Aramex ha risposto in una valuta diversa da quella predefinita del negozio. Inserisci Currency conversion rate, oppure chiedi ad Aramex di quotare nella tua valuta.

L'imposta viene applicata due volte sulla spedizione: i totali Aramex possono già includere l'IVA. Imposta Tax class su No tax.

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

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

Per gli sviluppatori: l'indirizzo dell'API Aramex può essere sostituito con l'impostazione vfd_armx_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 Aramex. OpenCart ripristina sempre Enable Aramex, Sort order, Tax class e Geo zone. Le tariffe in cache vengono sempre rimosse. Se Remove data on uninstall è attivo, vengono eliminate anche le impostazioni Aramex e il registro di debug. Se è disattivo, le altre impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. Gli ordini esistenti mantengono il loro metodo di spedizione e il loro 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 Aramex nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso a forma di cestino) per eliminare il pacchetto caricato.

Aramex è un marchio del suo rispettivo titolare. Questa estensione non è affiliata ad Aramex né approvata da Aramex.