VibeFox Aramex for PrestaShop — Guida

Requisiti

PrestaShop: 8.0 – 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni precedenti di PHP.

Account Aramex (solo per le tariffe in tempo reale): le tariffe in tempo reale usano l'API Aramex Rate Calculator. Aramex dà accesso all'API ai propri 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, 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: si acquista su vibefox.net. Una chiave funziona su un solo dominio.

Installazione

1. Nel back office vai su Modules > Module Manager e clicca su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento clicca su Configure, oppure cerca più tardi VibeFox Aramex nell'elenco dei moduli e clicca su Configure.

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

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

All'installazione il modulo crea il corriere Aramex con il testo dei tempi di consegna Courier delivery. Il corriere viene assegnato a tutte le zone e a tutti i gruppi di clienti. Puoi modificare zone, gruppi di clienti, tempi di consegna, logo e limiti di dimensione in Shipping > Carriers. Non impostare lì i prezzi: il prezzo arriva sempre dal modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Aramex > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella anche le tariffe Aramex in cache.

Generale

Enable Aramex: attiva o disattiva il corriere. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.

Method title: il nome del corriere mostrato nel carrello e al checkout. Predefinito: Aramex. Obbligatorio.

Shipping cost: come viene calcolato il prezzo.

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

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

Username: il tuo nome utente API di Aramex, di solito un indirizzo e-mail.

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

Account number: il tuo numero cliente Aramex.

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

Account entity: il codice di entità (ufficio) del tuo account Aramex, 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, 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 o HVY Heavy (20 kg e oltre).

Payment type: chi paga Aramex per la spedizione: Prepaid (paga il mittente), Collect (paga il destinatario) o Third party (terzi). Di solito Prepaid.

API weight unit: l'unità inviata ad Aramex, KG o LB. Pesi e dimensioni dei prodotti vengono convertiti dalle unità del tuo negozio. Il peso tariffabile è il maggiore tra peso effettivo e peso volumetrico (lunghezza × larghezza × altezza in cm / 5000). Il minimo è 0,5 kg, che vale anche per i prodotti senza peso.

Currency conversion rate: ad Aramex viene chiesto di 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 Aramex = X unità della valuta predefinita del tuo negozio). Lascialo vuoto per rifiutare questi preventivi, così un cliente non paga mai nella valuta sbagliata.

Spedizione da (indirizzo di origine) (usato per le tariffe in tempo reale)

Origin country: il paese da cui spedisci. Per impostazione predefinita è il paese del tuo negozio.

Origin city: la città da cui spedisci. Aramex la richiede.

Origin state / emirate: facoltativo.

Origin postcode: facoltativo.

Se il paese di origine è quello del tuo negozio, i campi vuoti vengono riempiti con l'indirizzo del negozio in Shop Parameters > Contact > Stores.

Prezzi fissi (usati in modalità fissa e come alternativa per le tariffe in tempo reale)

Price per country: una tabella di codici paese a 2 lettere e prezzi nella valuta predefinita del tuo negozio, IVA esclusa. Clicca su Add row per aggiungere un paese e sull'icona del cestino per rimuoverlo. Usa * come codice paese per tutti gli altri paesi. I paesi senza prezzo (se non c'è una riga *) non ricevono una tariffa fissa, quindi il corriere viene nascosto per loro.

Fixed price applies: Per order addebita il prezzo una sola volta. Per item lo moltiplica per il numero di articoli nel carrello. Le tariffe Aramex in tempo reale sono sempre per spedizione.

Condizioni

Minimum weight: nasconde il corriere quando il carrello pesa meno, in kg. 0 significa nessun limite.

Maximum weight: nasconde il corriere quando il carrello pesa di più, in kg. Predefinito: 100. 0 significa nessun limite.

Minimum order amount: mostra il corriere solo quando il subtotale del carrello (dopo gli sconti, prima delle tasse) raggiunge questo importo. Lascia vuoto per mostrarlo sempre.

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

Free shipping from: il subtotale del carrello (dopo gli sconti, prima delle tasse) da cui la spedizione è gratuita. Si usa solo quando Free shipping è attivo.

Tax: la regola fiscale del corriere, oppure No tax. Le tariffe Aramex in tempo reale possono già includere l'IVA. In quel caso scegli No tax per non far pagare l'imposta due volte.

Countries: offri Aramex solo per questi paesi di destinazione. Lascia vuoto per consentire tutti i paesi delle zone del corriere.

Avanzate

Debug log: scrive i calcoli delle tariffe e gli errori dell'API in logs/vfd_armx_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Password, PIN, numero di account e indirizzi dei clienti sono mascherati. Disattiva il registro quando hai finito.

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 il modulo vengono eliminate le impostazioni Aramex, il corriere, le tariffe in cache e i registri. Se disattivo, tutto viene conservato per una nuova installazione.

Come funziona al checkout

Nel passo della spedizione PrestaShop chiede al modulo il prezzo Aramex. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nell'importo dell'ordine. Il modulo controlla prima le condizioni: paesi consentiti, peso del carrello e importo minimo dell'ordine. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata nessuna richiesta ad Aramex.

In modalità fissa il prezzo viene preso dalla tabella. Nelle modalità in tempo reale il modulo invia ad Aramex gli indirizzi di origine e di consegna, il peso tariffabile, il servizio e la valuta predefinita del negozio, e usa il totale restituito. Una tariffa in tempo reale viene richiesta solo quando l'indirizzo di consegna ha una città o un CAP. Il prezzo viene calcolato nella valuta predefinita e poi mostrato nella valuta del carrello del cliente.

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

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

Se modifichi il corriere in Shipping > Carriers dopo che ha ricevuto ordini, PrestaShop lo salva come nuova versione del corriere. Il modulo segue automaticamente la nuova versione.

Il modulo calcola solo le tariffe. Non crea spedizioni Aramex, non stampa etichette, non prenota ritiri, non traccia i pacchi e non permette al cliente di scegliere un ufficio Aramex. Il pacco viene sempre inviato ad Aramex come un unico collo.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Aramex è il primo blocco di Modules > Module Manager > VibeFox Aramex > Configure, 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 compaiono la riga Product: presta-shipping-aramex e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo i dipendenti con il permesso Configure per il modulo possono modificare la chiave. I testi del blocco seguono la lingua del back office (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 una modifica dell'indirizzo del negozio, o dopo aver liberato un posto dominio nel tuo account, clicca su Check now. Se il server delle licenze non è raggiungibile, il modulo continua a funzionare con l'ultimo stato noto.

Una chiave funziona su un solo dominio: quello del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo posto dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, il corriere Aramex non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Lo storefront di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il corriere è nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non testarlo al checkout. Un promemoria compare in Modules > Module Manager, nella scheda Alerts. Gli ordini esistenti non sono interessati.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene ricontrollato automaticamente mentre lavori nel back office: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta a settimana. Non serve alcun cron job. Disinstallare o reimpostare il modulo rimuove sempre 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. In Shipping > Carriers verifica che il corriere copra la zona del paese del cliente e il suo gruppo. Controlla Countries, i limiti di peso e Minimum order amount. In modalità fissa verifica che il paese o * abbia un prezzo. I prodotti possono anche essere limitati a determinati corrieri nella pagina del prodotto.

Le tariffe in tempo reale non compaiono: attiva Debug log, ricarica il checkout e controlla il campo Log nella pagina del modulo. Mostra il motivo: credenziali API mancanti, codice di errore Aramex, città di origine mancante, città o CAP di consegna mancanti, un limite di peso o di importo, oppure un preventivo 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 respinto il login. Verifica nome utente, password, numero di account, PIN, entità e codice paese con il tuo account manager Aramex.

Preventivo in un'altra valuta rifiutato: 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'IVA sulla spedizione viene addebitata due volte: i totali Aramex possono già includere l'IVA. Imposta Tax su No tax.

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

La pagina indica che il corriere Aramex non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Reimposta il modulo in Modules > Module Manager per ricrearlo.

Disinstallazione

Vai in Modules > Module Manager, apri il menu accanto a VibeFox Aramex e scegli Uninstall. La chiave di licenza, lo stato della licenza e le tariffe in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini conservano la cronologia) e vengono rimossi impostazioni e registro. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni restano. Reinstallare il modulo riattiva il corriere salvato.

Aramex è un marchio del suo legittimo proprietario. Questo modulo non è affiliato ad Aramex né approvato da Aramex.