VibeFox SMSA Express 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.

Tariffa SMSA Express: i prezzi per la tabella arrivano dal tuo account SMSA o dal team commerciale di SMSA. Inseriscili nella valuta predefinita del tuo negozio. Se la tua tariffa è in SAR, AED o un'altra valuta, convertila prima.

passKey SMSA (solo per i costi in tempo reale): i costi in tempo reale usano il servizio web SMSA (SECOM, operazione getShipCharges). SMSA rilascia il passKey su richiesta: chiedilo al tuo account manager SMSA o scrivi a info@smsaexpress.com. Il passKey può essere diverso dalla API key del portale e-commerce SMSA. SMSA non ha un server di test (sandbox) per questo servizio.

Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un dominio.

Installazione

Il download è un file zip con i pacchetti per entrambe le versioni di OpenCart. Decomprimilo sul tuo computer. Contiene README.txt, il pacchetto per OpenCart 3 vfd_smsa_express-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_smsa_express.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. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_smsa_express-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non devi 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 SMSA Express e clicca su Install (il pulsante verde +).

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

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

5. Inserisci i tuoi prezzi SMSA Express nella tabella prezzi.

6. Facoltativo: in Live rates (API) attiva Live charges, inserisci il tuo passKey SMSA, la città e il paese di partenza e, se la valuta predefinita del tuo negozio non è SAR, il tasso di cambio.

7. Attiva Enable SMSA Express e clicca su Save.

OpenCart 4

1. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_smsa_express.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 SMSA Express, clicca su Install (il pulsante verde +), poi su Edit (il pulsante con la matita).

4. Inserisci la chiave di licenza e le impostazioni come nei passaggi da 4 a 7 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 SMSA Express e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni SMSA Express che avevi conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox SMSA Express > Edit. Le sezioni sono elencate a sinistra. Un solo pulsante Save salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella anche i costi SMSA in cache. Un titolo del metodo non valido, un valore che non è un numero, un numero negativo, un tasso di cambio pari a 0, un codice valuta che non ha 3 lettere, un prezzo errato in tabella, un Minimum weight (kg) superiore al Maximum weight (kg) o un ordinamento che non è un numero intero vengono rifiutati con un errore, e non viene salvato nulla finché non correggi. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.

Quando i costi in tempo reale sono attivi, gli avvisi sopra le impostazioni ti segnalano un passKey, una città di partenza o un tasso di cambio mancanti, oppure una tabella prezzi vuota. Un avviso compare anche se il negozio non ha una classe di peso in kg e la sua unità di peso predefinita non è riconosciuta dall'estensione (i pesi dei prodotti vengono allora letti come kg). Aggiungi una classe di peso in kg in System > Localisation > Weight Classes.

Generali

Le impostazioni valgono per ogni zona geografica. Puoi limitare il metodo a una zona geografica in Conditions, oppure a un elenco di paesi con Ignore shipping zones.

Enable SMSA Express: mostra o nasconde SMSA Express al checkout. Predefinito: disattivato.

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

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

Tariffe in tempo reale (API) (facoltativo; se SMSA non restituisce alcun costo, si usa la tabella prezzi)

Live charges: ottiene il costo di spedizione da SMSA Express. Quando è disattivato, al checkout non viene inviato nulla a SMSA. Predefinito: disattivato.

SMSA passKey: la chiave del servizio web SMSA (SECOM). Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per modificarla. Seleziona Remove the saved passKey per eliminarla. Se il log mostra "Invalid Passkey", questa chiave non è accettata dal servizio. Chiedi a SMSA un passKey per il servizio web.

Ship-from city: la città da cui partono i tuoi pacchi, scritta come la scrive SMSA, per esempio Riyadh, Jeddah o Dammam. Obbligatoria per i costi in tempo reale: OpenCart non ha una città del negozio, quindi non viene mai presa dall'indirizzo del negozio.

Ship-from country: il paese da cui partono i tuoi pacchi. La prima opzione, Store country, usa il paese del tuo negozio da System > Settings > Store > Local. È l'impostazione predefinita.

Shipment type: inviato a SMSA come tipo di spedizione. DLV (il valore predefinito) è la consegna standard. Cambialo solo se SMSA ti ha dato un altro codice.

Currency of SMSA charges: il codice a 3 lettere della valuta in cui SMSA restituisce i costi, di solito SAR (il predefinito). Un costo in una valuta diversa da questa o dalla valuta predefinita del negozio non viene usato.

Exchange rate: il prezzo di 1 unità della valuta SMSA nella valuta predefinita del tuo negozio, per esempio 0.27. Non serve quando le due valute coincidono. Senza di esso, i costi in un'altra valuta non vengono usati e si applica la tabella prezzi.

Prezzi (la tua tariffa SMSA Express nella valuta predefinita del tuo negozio; usata quando i costi in tempo reale sono disattivati e come riserva quando SMSA non restituisce un costo)

Price table: una riga per paese di destinazione. Clicca su Add country per aggiungere una riga. La riga * All other countries si applica ai paesi senza una riga propria. Ogni riga ha un prezzo Base e colonne di peso: XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg e XL >5 kg. Una colonna di peso vuota o a 0 usa il prezzo base. Un prezzo base di 0 significa spedizione gratuita. Le righe senza alcun prezzo non vengono salvate. Se un paese ha due righe, viene usata la prima. Sono accettati sia "9.99" sia "9,99".

Price for countries not in the table: usato quando la tabella non ha una riga per il paese di destinazione (e non c'è una riga *) oppure la riga non ha un prezzo per quel peso. Lascialo vuoto per nascondere il metodo in questo caso.

Price applies: come viene calcolato il prezzo.

I pesi dei prodotti vengono convertiti dalla loro classe di peso di OpenCart in chilogrammi.

Condizioni

Minimum weight (kg): nascondi il metodo quando il carrello pesa meno. 0 significa nessun limite (predefinito).

Maximum weight (kg): nascondi il metodo quando il carrello pesa di più. Predefinito: 30. 0 o un campo vuoto significa nessun limite.

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

Free shipping from: il subtotale dei prodotti che richiedono spedizione (dopo il coupon, prima delle tasse) a partire dal quale la spedizione SMSA Express è gratuita. Quando il carrello lo raggiunge, il prezzo è 0 e non viene inviata nessuna richiesta a SMSA. Lascialo vuoto per non offrire mai la spedizione gratuita.

Tax class: la classe fiscale del costo di spedizione, oppure No tax (predefinito). Scegli No tax se i tuoi prezzi (la tabella e i costi SMSA) includono già le tasse, per esempio l'IVA saudita.

Geo zone: offri SMSA Express solo per gli indirizzi di questa zona geografica. All zones (predefinito) significa nessun limite. Non viene verificata finché Ignore shipping zones è attivo. Le zone geografiche si gestiscono in System > Localisation > Geo Zones.

Disponibilità senza zone di spedizione

Normalmente il metodo viene offerto per gli indirizzi della zona geografica scelta in Conditions.

Ignore shipping zones: offri SMSA Express per i paesi indicati sotto, indipendentemente dalla zona geografica. Quando è disattivato, decide la zona geografica e l'elenco dei paesi non viene usato.

Countries: i paesi di destinazione per quella modalità. Lascialo vuoto per usare tutti i paesi attivi nel negozio. Questo campo viene usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: registra i calcoli delle tariffe in storage/logs/vfd_smsa_debug.log.php. Il file non può essere letto dal web. Non vengono registrati indirizzi di clienti né chiavi. Gli errori dei costi in tempo reale vengono sempre registrati, anche con questa opzione disattivata. Disattiva il log quando hai finito. Quando il file raggiunge 5 MB, viene spostato in vfd_smsa_debug.old.log.php e viene avviato un nuovo log.

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

Remove data on uninstall: se attivo, disinstallando l'estensione vengono eliminate le impostazioni SMSA Express e il log di debug. Se disattivo (predefinito), le impostazioni vengono conservate per una reinstallazione. I costi in cache vengono sempre rimossi.

Importazione / Esportazione

Export: clicca su Download JSON per salvare le impostazioni in un file JSON. Il passKey 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 controllati come in un normale salvataggio. Il passKey salvato viene mantenuto.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di SMSA Express. Se è impostata una Geo zone (e Ignore shipping zones è disattivato) e l'indirizzo è fuori da essa, SMSA Express 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 le condizioni: i paesi di Ignore shipping zones (se attivo), il peso del carrello e l'importo minimo dell'ordine. Buoni regalo, punti fedeltà e credito del negozio non vengono considerati. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata nessuna richiesta a SMSA.

Con i costi in tempo reale attivi, l'estensione invia a SMSA la città e il paese di partenza, la città e il paese del cliente, il tipo di spedizione, il peso del pacco in kg e un importo di contrassegno alla consegna pari a 0. SMSA risponde con il costo e la sua valuta. L'estensione lo converte nella valuta predefinita del tuo negozio e lo arrotonda alle sue cifre decimali. Il prezzo viene poi mostrato nella valuta del cliente con l'imposta della Tax class selezionata. Un costo in tempo reale viene richiesto solo dopo che il cliente ha inserito un indirizzo di consegna con una città.

Ogni costo viene memorizzato nella cache per un'ora, così lo stesso carrello non genera una nuova richiesta. Una richiesta fallita viene memorizzata nella cache per 5 minuti. Dopo un timeout o un errore del server, SMSA non viene interrogato per 2 minuti. Dopo una chiave rifiutata, non viene interrogato per 5 minuti. Così il checkout non aspetta mai un servizio che non funziona a ogni aggiornamento. Il timeout delle richieste è di 12 secondi.

Ogni volta che SMSA non restituisce un costo utilizzabile (nessun passKey, città non ancora inserita, chiave non valida, timeout, errore, nessun servizio verso la città o valuta sconosciuta), si usa la tabella prezzi. Se la tabella e Price for countries not in the table non danno alcun prezzo, il metodo viene nascosto. Il cliente non vede mai un errore. Il motivo viene scritto nel log.

L'estensione calcola solo il prezzo della spedizione. Non crea spedizioni SMSA, non stampa etichette AWB, non gestisce resi e non traccia i pacchi. Il contrassegno alla consegna e la sua commissione non sono inclusi nel costo in tempo reale. Non c'è un selettore di punti vendita SMSA: il metodo è una consegna a domicilio. Non aggiunge nulla agli ordini: l'ordine mostra il titolo del metodo e il costo di spedizione come qualsiasi altro metodo di spedizione di OpenCart.

In OpenCart 4 il cliente clicca su Choose nel blocco dei metodi di spedizione della pagina di checkout e sceglie SMSA Express nella finestra Shipping method options. Il metodo funziona come su OpenCart 3.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza License — VibeFox SMSA Express è il primo blocco di Extensions > Extensions > Shipping > VibeFox SMSA Express > Edit, sopra le impostazioni. Incolla 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-smsa-express 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 o License expired on seguito da una data. Dopo aver cambiato l'indirizzo del negozio, o dopo aver liberato un posto 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 dominio: l'indirizzo del negozio dalla configurazione di OpenCart. Rimuovere la chiave dal negozio non libera il suo posto dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, SMSA Express non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Un amministratore che ha effettuato l'accesso all'amministrazione nello stesso browser vede comunque il metodo nel negozio, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e testare l'estensione prima di acquistare una chiave. Su OpenCart 4 questa anteprima non è disponibile: il negozio non vede l'accesso dell'amministratore, quindi senza una chiave attiva il metodo viene nascosto a tutti. Dopo aver aperto una volta la pagina Edit, compare un promemoria nella Dashboard dell'amministrazione. Chiudilo con × per nasconderlo per 7 giorni. Gli ordini esistenti non sono interessati.

Quando una licenza scade, l'estensione continua a funzionare, ma gli aggiornamenti e il supporto richiedono un rinnovo. Lo stato viene ricontrollato 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 alla settimana. Non serve alcun cron job. Disinstallare l'estensione elimina sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

SMSA Express non compare al checkout: controlla che la licenza sia attiva e che Enable SMSA Express sia attivo. Controlla Geo zone (o, con Ignore shipping zones attivo, Countries), i limiti di peso e il Minimum order amount. Verifica che il paese o * abbia un prezzo, oppure che Price for countries not in the table sia impostato. Controlla che i prodotti abbiano Requires Shipping impostato su Yes.

I clienti vedono il prezzo della tabella invece del costo SMSA: SMSA ha bisogno della città del cliente, quindi finché non viene inserita si mostra il prezzo della tabella. La tabella viene usata anche quando SMSA non risponde, rifiuta la chiave o la città, oppure restituisce il costo in una valuta senza tasso di cambio. Guarda il campo Log nella pagina dell'estensione per il motivo.

"Invalid Passkey" nel log: la chiave non è accettata dal servizio web SMSA. Chiedi a SMSA un passKey per il servizio web.

La città del cliente non viene accettata: SMSA si aspetta la propria grafia dei nomi di città. Controlla la città nell'indirizzo di consegna e la Ship-from city.

Le impostazioni non vengono salvate e compare un errore: un campo numerico contiene testo o un valore negativo, il tasso di cambio è 0, il codice valuta non ha 3 lettere o Minimum weight (kg) è superiore a Maximum weight (kg). Correggi il valore indicato nel messaggio e clicca di nuovo su Save.

L'imposta sulla spedizione viene addebitata due volte: la tua tariffa o i costi SMSA potrebbero 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 i costi SMSA in cache.

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

Per sviluppatori: l'indirizzo del servizio web SMSA può essere sostituito con l'impostazione vfd_smsa_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 SMSA Express. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable SMSA Express, Sort order, Tax class e Geo zone. I costi in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, vengono eliminati anche le impostazioni SMSA Express e il log 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 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 SMSA Express nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per eliminare il pacchetto caricato.

SMSA Express è un marchio del suo rispettivo proprietario. Questa estensione non è affiliata né approvata da SMSA Express.