VibeFox SMSA Express for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni di PHP più vecchie.

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

passKey SMSA (solo per le tariffe in tempo reale): le tariffe in tempo reale usano il servizio web SMSA (SECOM, operazione getShipCharges). SMSA rilascia la passKey su richiesta: chiedila al tuo account manager SMSA oppure scrivi a info@smsaexpress.com e chiedi l'accesso al servizio web SMSA indicando il tuo numero di account. La passKey può essere diversa dalla chiave API del portale e-commerce SMSA. SMSA non ha un server di test (sandbox) per questo servizio.

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 fai clic su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, fai clic su Configure, oppure trova più tardi VibeFox SMSA Express nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la chiave di licenza VibeFox in License key nel blocco licenza in cima alla pagina di configurazione e fai clic su Activate (vedi Chiave di licenza).

4. Inserisci i prezzi SMSA Express nella tabella prezzi e fai clic su Save.

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

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

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox SMSA Express > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella anche le tariffe SMSA in cache. Un valore che non è un numero, un numero negativo, un tasso di cambio pari a 0, un codice valuta che non sia di 3 lettere o un Minimum weight superiore al Maximum weight vengono rifiutati con un errore, e non si salva nulla finché non correggi il valore.

Quando le tariffe in tempo reale sono attive, gli avvisi sopra le impostazioni ti segnalano una passKey, una città di partenza o un tasso di cambio mancanti, oppure una tabella prezzi vuota. Compare un avviso anche se il modulo non riconosce l'unità di peso del negozio (in tal caso i pesi dei prodotti vengono letti come kg). Imposta kg, g, lb o oz in International > Localization (Local units).

Generale

Enable SMSA Express: attiva o disattiva il corriere in tutte le zone contemporaneamente. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.

Method title: il nome del corriere mostrato nel carrello e al checkout. Predefinito: SMSA Express. Obbligatorio, fino a 64 caratteri.

Tax: la regola fiscale del corriere, oppure No tax. Scegli No tax se i tuoi prezzi (la tabella e le tariffe SMSA) includono già le imposte, per esempio l'IVA saudita.

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

Live charges: ottiene il costo di spedizione da SMSA Express. 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 cambiarlo. Spunta Remove the saved passKey per eliminarla. Se nel registro compare "Invalid Passkey", il servizio non accetta la chiave. Chiedi a SMSA una 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. Lasciala vuota per usare la città del negozio indicata in Shop Parameters > Contact > Stores.

Ship-from country: il paese da cui partono i tuoi pacchi. Per impostazione predefinita è il paese del tuo negozio.

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

Currency of SMSA charges: SMSA restituisce ogni tariffa con il suo codice valuta, di solito SAR (predefinito). Una tariffa in una valuta diversa da questa o dalla valuta predefinita del negozio non viene usata.

Exchange rate: il prezzo di 1 unità della valuta SMSA nella valuta predefinita del negozio, per esempio 0.27. Non serve quando le due valute coincidono. Senza di esso, le tariffe in un'altra valuta non vengono usate e si applica la tabella prezzi. Sono accettati sia il punto sia la virgola come separatore decimale.

Prezzi (la tua tariffa SMSA Express nella valuta predefinita del negozio; usata quando le tariffe in tempo reale sono disattivate e come riserva quando SMSA non restituisce una tariffa)

Price table: una riga per paese di destinazione. Fai clic su Add country per aggiungere una riga e sull'icona del cestino per rimuoverne una. La riga * Default (all other countries) si applica ai paesi senza una riga propria. Ogni riga ha un prezzo base e colonne di peso: XS fino a 1 kg, S fino a 2 kg, M fino a 3 kg, L fino a 5 kg e XL oltre 5 kg. Una colonna di peso vuota o pari 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, si usa la prima. Sono accettati sia "9.99" sia "9,99".

Price for countries not in the table: si usa quando la tabella non ha una riga per il paese di destinazione (né una riga *) oppure la riga non ha un prezzo per quel peso. Lascialo vuoto per nascondere il corriere in quel caso.

Price applies: come viene calcolato il prezzo.

I pesi dei prodotti vengono convertiti dall'unità di peso del negozio in chilogrammi.

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: 30. 0 o un campo vuoto significa nessun limite.

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

Free shipping from: il subtotale del carrello (dopo sconti, prima delle imposte) a partire dal quale la spedizione con SMSA Express è gratuita. Quando il carrello lo raggiunge, il prezzo è 0 e non viene inviata alcuna richiesta a SMSA. Lascialo vuoto per non offrire mai la spedizione gratuita.

Disponibilità senza zone di spedizione

Normalmente il corriere viene offerto nelle zone a cui è assegnato in Shipping > Carriers.

Ignore shipping zones: offre SMSA Express per i paesi indicati di seguito, qualunque zona corrisponda. Finché è attivo, il corriere viene aggiunto a tutte le zone, anche a quelle create in seguito. Disattivandolo, le zone aggiunte in questo modo vengono rimosse.

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

Avanzate

Debug log: registra i calcoli delle tariffe in logs/vfd_smsa_debug.log.php, nella cartella del modulo. Il file non si può aprire dal web. Non vengono registrati indirizzi dei clienti né chiavi. Gli errori delle tariffe in tempo reale vengono sempre registrati, anche quando questa opzione è disattivata. Disattiva il registro quando hai finito.

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

Remove data on uninstall: se attivo, la disinstallazione del modulo elimina le impostazioni di SMSA Express, il corriere e il registro. Se disattivo, tutto viene conservato per una reinstallazione. Le tariffe in cache vengono sempre eliminate.

Come funziona al checkout

Nel passaggio di spedizione PrestaShop chiede al modulo il prezzo di SMSA Express. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non rientrano nell'importo dell'ordine. Il modulo verifica prima le condizioni: i paesi di Ignore shipping zones (se attivo), il peso del carrello e l'importo minimo dell'ordine. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata alcuna richiesta a SMSA.

Con le tariffe in tempo reale attive, il modulo invia a SMSA la tua città e il tuo 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 pari a 0. SMSA risponde con la tariffa e la sua valuta. Il modulo la converte nella valuta predefinita del negozio, poi il prezzo viene mostrato nella valuta del carrello del cliente. Una tariffa in tempo reale viene richiesta solo dopo che il cliente ha inserito un indirizzo di consegna con una città.

Ogni tariffa viene memorizzata nella cache per un'ora, così lo stesso carrello non genera una nuova richiesta. Una richiesta non riuscita viene memorizzata nella cache per 5 minuti. Dopo un timeout o un errore del server, SMSA non viene interpellato per altri 2 minuti. Dopo una chiave rifiutata, non viene interpellato per 5 minuti. Così il checkout non attende mai un servizio che non funziona a ogni aggiornamento. Il timeout della richiesta è di 12 secondi.

Quando SMSA non restituisce una tariffa utilizzabile (nessuna passKey, nessuna città ancora inserita, pesi dei prodotti mancanti, 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 corriere viene nascosto. Il cliente non vede mai un errore. Il motivo viene scritto nel registro.

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

Il modulo calcola solo il costo di spedizione. Non crea spedizioni SMSA, non stampa etichette AWB, non gestisce resi e non traccia i pacchi. Il contrassegno e la sua commissione non sono inclusi nella tariffa in tempo reale. Non esiste un selettore di punti vendita SMSA: il corriere è una consegna a domicilio.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox SMSA Express è il primo blocco di Modules > Module Manager > VibeFox SMSA Express > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic 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 verificare 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: presta-shipping-smsa-express 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 cambiare 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 un cambio dell'indirizzo del negozio, o dopo aver liberato uno slot di dominio nel tuo account, fai clic 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: il dominio del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, il corriere SMSA Express non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Il negozio online 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 il rinnovo. Lo stato viene verificato di nuovo automaticamente mentre lavori nel back office: 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 o reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

SMSA Express non compare al checkout: verifica che la licenza sia attiva e che Enable SMSA Express sia attivo. In Shipping > Carriers controlla che il corriere copra la zona del paese del cliente e il gruppo del cliente (oppure che Ignore shipping zones sia attivo e il paese sia consentito). Controlla i limiti di peso e Minimum order amount. Verifica che il paese o * abbia un prezzo, oppure che sia impostato Price for countries not in the table. Inoltre, i prodotti possono essere limitati a determinati corrieri nella scheda prodotto.

I clienti vedono il prezzo della tabella invece della tariffa 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 la tariffa in una valuta senza tasso di cambio. Guarda il campo Log nella pagina del modulo per il motivo.

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

La città del cliente non viene accettata: SMSA usa la propria grafia delle 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 è di 3 lettere, oppure Minimum weight è superiore a Maximum weight. Correggi il valore indicato nel messaggio e fai di nuovo clic su Save.

Le imposte sulla spedizione vengono applicate due volte: la tua tariffa o le tariffe SMSA potrebbero già includere l'IVA. Imposta Tax su No tax.

Le tariffe sembrano obsolete dopo una modifica: fai clic su Save nella pagina del modulo. Questo cancella le tariffe SMSA in cache.

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

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox SMSA Express e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre eliminati. Le tariffe in cache vengono sempre eliminate. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini conservano la cronologia) e vengono rimosse impostazioni e registro. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni vengono conservate. Reinstallare il modulo o un Reset riporta il corriere allo stato che aveva prima.

SMSA Express è un marchio di proprietà del rispettivo titolare. Questo modulo non è affiliato né approvato da SMSA Express.