VibeFox Aramex for WooCommerce — Guida
Requisiti
WordPress: 5.8 o successivo.
WooCommerce: 5.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.
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 all'API ai propri titolari di account. Chiedi al tuo account manager Aramex oppure consulta l'Aramex Developers Solution Center sul sito di Aramex. Ti 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: acquistata su vibefox.net. Una chiave funziona su un dominio.
Installazione
1. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e fai clic su Install Now. Puoi anche caricare la cartella vfd_aramex in /wp-content/plugins/ via FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox Aramex, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugin.
4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.
5. Scegli come viene calcolato il costo di spedizione e compila le sezioni corrispondenti (vedi Configurazione).
6. Aggiungi VibeFox Aramex a una zona di spedizione in WooCommerce > Settings > Shipping > Shipping zones, oppure attiva Ignore shipping zones e scegli i paesi.
Configurazione
Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox Aramex. Valgono per tutte le zone di spedizione. Quando aggiungi il metodo a una zona, la finestra della zona ha un solo campo:
Title (zone): il nome che i clienti vedono per questa zona. Lascialo vuoto per usare il Method title globale.
Ogni volta che salvi le impostazioni, le tariffe Aramex memorizzate nella cache vengono cancellate.
Generale
Enable/Disable: attiva o disattiva il metodo in tutte le zone contemporaneamente.
Method title: il nome del metodo di spedizione mostrato nel carrello e al checkout. Predefinito: Aramex.
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 nome utente API Aramex, di solito un indirizzo e-mail.
Password: la password API Aramex.
Account number: il numero del tuo account cliente Aramex.
Account PIN: il PIN del tuo account Aramex.
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 spedizione nazionale (Domestic). Tutte le altre spedizioni vengono quotate come spedizione internazionale express (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 ad Aramex la spedizione: Prepaid (paga il mittente), Collect (paga il destinatario) o Third party. Di solito Prepaid.
API weight unit: l'unità inviata ad Aramex, KG o LB. I pesi dei prodotti vengono convertiti dall'unità di peso del negozio. Il peso fatturabile è il maggiore tra peso effettivo e peso volumetrico (lunghezza × larghezza × altezza in cm / 5000). Il minimo è 0,5 kg, che copre anche i prodotti senza peso.
Currency conversion rate: ad Aramex viene chiesto di quotare nella valuta del negozio. Se risponde comunque in un'altra valuta, la tariffa viene moltiplicata per questo numero (1 unità della valuta Aramex = X unità della valuta del negozio). Lascialo vuoto per rifiutare tali preventivi, così al cliente non viene mai addebitato un importo nella valuta sbagliata. Sono accettati sia il punto sia la virgola come separatore decimale.
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 negozio.
Origin city: la città da cui spedisci. Aramex la richiede.
Origin state / emirate: facoltativo.
Origin postcode: facoltativo.
Se il paese di origine è il paese del negozio, i campi vuoti vengono compilati con l'indirizzo del negozio in WooCommerce > Settings > General.
Prezzi fissi (usati nella 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 del negozio. Fai clic su Add row per aggiungere un paese e sulla croce per rimuoverlo. Usa * come codice paese per tutti gli altri paesi. I paesi senza prezzo (quando non c'è una riga con *) non ricevono una tariffa fissa, quindi il metodo 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 (kg): nasconde il metodo quando il carrello pesa meno. 0 significa nessun limite.
Maximum weight (kg): nasconde il metodo quando il carrello pesa di più. Predefinito: 100. 0 significa nessun limite.
Minimum order amount: mostra il metodo solo quando il subtotale del carrello (dopo gli sconti, al netto delle imposte) raggiunge questo importo. Lascialo vuoto per mostrarlo sempre.
Excluded shipping classes: nasconde il metodo quando il carrello contiene un prodotto appartenente a una di queste classi di spedizione di WooCommerce.
Free shipping: attiva la consegna Aramex gratuita a partire dall'importo indicato sotto.
Free shipping from: il subtotale del carrello (dopo gli sconti, al netto delle imposte) a partire dal quale la consegna è gratuita. Usato solo quando Free shipping è attivo.
Tax status: Taxable aggiunge l'imposta di WooCommerce al costo di spedizione, None non la aggiunge. Le tariffe Aramex in tempo reale possono già includere l'IVA. In tal caso scegli None per non addebitarla due volte.
Disponibilità senza zone di spedizione
Ignore shipping zones: offre Aramex per i paesi indicati sotto anche se il metodo non è aggiunto a nessuna zona di spedizione.
Countries: i paesi di destinazione per quella modalità. Lascialo vuoto per usare tutti i paesi verso cui spedisci. Questo campo viene usato solo quando Ignore shipping zones è attivo.
Avanzate
Debug log: scrive i calcoli delle tariffe e gli errori API in logs/vfd_armx_debug.log.php nella cartella del plugin. Il file non può essere aperto dal web. Password, PIN, numero di account e indirizzi dei clienti vengono mascherati. Disattiva il registro quando hai finito.
Remove data on uninstall: se attivo, eliminando il plugin vengono rimosse tutte le sue impostazioni, i metodi delle zone, le tariffe in cache e i registri. Disattivare il plugin non elimina mai nulla.
Come funziona al checkout
Quando il cliente inserisce un indirizzo di consegna, WooCommerce chiede al plugin una tariffa. Il plugin controlla prima le condizioni: paese di consegna, peso del carrello, importo minimo dell'ordine e classi di spedizione escluse. Se si applica la spedizione gratuita, il cliente vede il metodo come Aramex (free) e nessuna richiesta viene inviata ad Aramex.
In modalità fissa il prezzo viene preso dalla tabella. Nelle modalità in tempo reale il plugin invia ad Aramex gli indirizzi di origine e di consegna, il peso fatturabile, il servizio e la valuta del negozio, e mostra il totale restituito. Una tariffa in tempo reale viene richiesta solo dopo che il cliente ha inserito una città o un CAP. Ogni risposta viene memorizzata nella cache per 1 ora, quindi 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 un preventivo in un'altra valuta senza tasso di conversione, il cliente non vede alcun errore. Il metodo viene nascosto oppure, in modalità di ripiego, viene usato il prezzo fisso. Il motivo viene scritto nel registro di debug.
Il metodo funziona con il checkout classico e con i blocchi Carrello e Checkout. È compatibile con WooCommerce High-Performance Order Storage (HPOS).
Il plugin 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. Il pacco viene sempre inviato ad Aramex come un unico collo.
Chiave di licenza
Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Shipping > VibeFox Aramex. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, per esempio la data fino alla quale la licenza è attiva e il tuo dominio. Usa Check now per verificare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuoverla da questo sito. Il link Manage licenses and domains in your account apre il tuo account vibefox.net.
Una chiave funziona su un dominio. Rimuovere la chiave da un sito non libera il posto del dominio. Liberalo nel tuo account vibefox.net.
Senza una chiave attiva, Aramex non viene mostrata ai clienti al checkout. I gestori del negozio che hanno effettuato l'accesso la vedono ancora, contrassegnata da (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugin e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati.
Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene verificato di nuovo automaticamente in background.
Risoluzione dei problemi
Aramex non appare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che il metodo sia aggiunto alla zona del paese del cliente (oppure che Ignore shipping zones sia attivo e il paese sia consentito). Controlla i limiti di peso, Minimum order amount e Excluded shipping classes. In modalità fissa, verifica che il paese o * abbia un prezzo.
Le tariffe in tempo reale non appaiono: attiva il Debug log, ricarica il checkout e apri logs/vfd_armx_debug.log.php nella cartella del plugin. Mostra il motivo: credenziali API mancanti, codice di errore Aramex, nessuna città di origine, nessuna città o CAP di consegna ancora, 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 rifiutato l'accesso. Verifica nome utente, password, numero di account, PIN, entità e codice paese con il tuo account manager Aramex.
Il preventivo in un'altra valuta viene rifiutato: Aramex ha risposto in una valuta diversa da quella del negozio. Inserisci Currency conversion rate, oppure chiedi ad Aramex di quotare nella tua valuta.
L'imposta sulla spedizione viene addebitata due volte: i totali Aramex possono già includere l'IVA. Imposta Tax status su None.
Le tariffe sembrano obsolete dopo una modifica: salva la pagina delle impostazioni. Questo cancella le tariffe Aramex memorizzate nella cache.
Sandbox Aramex: il plugin usa l'Aramex Rate Calculator di produzione. Gli sviluppatori possono cambiare l'endpoint con il filtro vfd_armx_api_url. I filtri vfd_armx_rate_request, vfd_armx_number_of_pieces e vfd_armx_volumetric_divisor modificano la richiesta, il numero di colli e il divisore volumetrico.
Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera un posto nel tuo account vibefox.net e fai clic su Check now. Se l'indirizzo del sito è cambiato, fai clic su Check now per attivare la chiave per il nuovo dominio. Se il server delle licenze non è raggiungibile, il plugin continua a funzionare con l'ultimo stato noto.
Disinstallazione
Disattivare il plugin mantiene tutti i dati. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi. Impostazioni, metodi delle zone, tariffe in cache e registri vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano per una successiva reinstallazione. Gli ordini esistenti mantengono le righe di spedizione.
Aramex è un marchio del rispettivo titolare. Questo plugin non è affiliato né approvato da Aramex.