VibeFox SMSA Express 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.
Tariffa SMSA Express: i prezzi della tabella prezzi provengono dal tuo account SMSA o dal team commerciale SMSA. Inseriscili nella valuta del tuo negozio. Se la tua 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 il passKey su richiesta: chiedilo al tuo account manager SMSA oppure scrivi a info@smsaexpress.com e richiedi l'accesso al servizio web SMSA indicando il tuo numero di account. Il passKey può essere diverso dalla chiave API del portale e-commerce SMSA. SMSA non ha un server di test (sandbox) per questo servizio.
Licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un solo 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_smsa_express in /wp-content/plugins/ via FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox SMSA Express, 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. Inserisci le tue tariffe 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 del tuo negozio non è SAR, il tasso di cambio.
7. Aggiungi VibeFox SMSA Express a una zona di spedizione in WooCommerce > Settings > Shipping > Shipping zones (ad esempio "Arabia Saudita"), oppure attiva Ignore shipping zones e scegli i paesi.
Configurazione
Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox SMSA Express. 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 SMSA in cache vengono cancellate. Quando le tariffe in tempo reale sono attive, gli avvisi sopra le impostazioni segnalano un passKey, una città di partenza o un tasso di cambio mancanti, oppure una tabella prezzi vuota.
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. Una zona può sostituirlo. Predefinito: SMSA Express.
Tariffe in tempo reale (API) (facoltativo; se SMSA non restituisce una tariffa, viene usata la tabella prezzi)
Live charges: ottiene la tariffa di spedizione da SMSA Express. Predefinito: disattivato.
SMSA passKey: la chiave del servizio web SMSA (SECOM). Se il log mostra "Invalid Passkey", questo servizio non accetta la chiave. 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, ad esempio Riyadh, Jeddah o Dammam. Lasciala vuota per usare la città del negozio da WooCommerce > Settings > General.
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 (il valore predefinito) è la consegna standard. Modificalo 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 da quella del tuo negozio non viene usata.
Exchange rate: il prezzo di 1 unità della valuta SMSA nella valuta del tuo negozio, ad esempio 0.24. Non serve se 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 del negozio; usata quando le tariffe in tempo reale sono disattivate e come alternativa quando SMSA non restituisce una tariffa)
Price table: una riga per paese di destinazione. Fai clic su + Add country per aggiungere una riga e sulla croce per rimuoverne una. La riga * 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 vengono eliminate al salvataggio. 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 questo peso. Lascialo vuoto per nascondere il metodo in questo caso.
Price applies: come viene calcolato il prezzo.
I pesi dei prodotti vengono convertiti dall'unità di peso del tuo negozio in chilogrammi.
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: 30. 0 significa nessun limite.
Minimum order amount: mostra il metodo solo quando il subtotale del carrello (dopo sconti, prima delle tasse) raggiunge questo importo. Lascialo vuoto per mostrarlo sempre.
Free shipping from: il subtotale del carrello (dopo sconti, prima delle tasse) da cui la spedizione SMSA Express è gratuita. La spedizione gratuita viene offerta solo dove il metodo ha un prezzo per la destinazione: una tariffa SMSA, una riga della tabella o il prezzo per i paesi non in tabella. Se la tabella ha un prezzo, non viene inviata alcuna richiesta a SMSA. Lascialo vuoto per non offrire mai la spedizione gratuita.
Excluded shipping classes: nasconde il metodo quando il carrello contiene un prodotto di una di queste classi di spedizione WooCommerce.
Tax status: Taxable aggiunge l'imposta WooCommerce al costo della spedizione, None no. Scegli None se i tuoi prezzi (la tabella e le tariffe SMSA) includono già le tasse, ad esempio l'IVA saudita.
Disponibilità senza zone di spedizione
Ignore shipping zones: offri SMSA Express per i paesi indicati sotto, anche se il metodo non è aggiunto a nessuna zona di spedizione.
Countries: i paesi di destinazione per questa modalità. Lascialo vuoto per usare tutti i paesi in cui spedisci. Questo campo viene usato solo quando Ignore shipping zones è attivo. Un metodo aggiunto a una zona di spedizione funziona sempre per i paesi della sua zona.
Avanzate
Debug log: registra ogni calcolo di tariffa in WooCommerce > Status > Logs, origine vfd_smsa_express. 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 log quando hai finito.
Remove data on uninstall: se attivo, eliminando il plugin vengono rimosse tutte le impostazioni di SMSA Express e i metodi delle zone. Disattivare il plugin non elimina mai nulla.
Come funziona al checkout
Quando il cliente inserisce un indirizzo di consegna, WooCommerce chiede al plugin un prezzo. 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 e la destinazione ha un prezzo, il metodo viene mostrato con un prezzo di 0.
Con le tariffe in tempo reale attive, il plugin 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 di 0. SMSA risponde con la tariffa e la sua valuta. Il plugin la converte nella valuta del tuo negozio e la mostra. Una tariffa in tempo reale viene richiesta solo dopo che il cliente ha inserito una città.
Ogni tariffa viene memorizzata nella cache per un'ora, così lo stesso carrello non genera una nuova richiesta. Una richiesta fallita viene memorizzata per 5 minuti. Dopo un timeout o un errore del server, SMSA non viene interrogata per 2 minuti. Dopo una chiave rifiutata, non viene interrogata per 5 minuti. Così il checkout non attende mai un servizio che non funziona a ogni aggiornamento. Il timeout della richiesta è di 12 secondi.
Ogni volta che SMSA non restituisce una tariffa utilizzabile (nessun passKey, nessuna città ancora inserita, pesi dei prodotti mancanti, chiave non valida, timeout, errore, nessun servizio verso la città o valuta sconosciuta), viene usata 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.
Il metodo funziona con il checkout classico e con i blocchi Carrello e Checkout. È compatibile con l'archiviazione ad alte prestazioni degli ordini di WooCommerce (HPOS). È inclusa una traduzione in arabo.
Il plugin calcola solo il prezzo della spedizione. Non crea spedizioni SMSA, non stampa etichette AWB, non gestisce resi né 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 metodo è una consegna a domicilio.
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 SMSA Express. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, ad 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 solo dominio. Rimuovere la chiave da un sito non libera il suo posto per il dominio. Liberalo dal tuo account vibefox.net.
Senza una chiave attiva, SMSA Express non viene mostrato ai clienti al checkout. Gli amministratori del negozio connessi lo vedono ancora, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Sulla pagina Plugin e nelle pagine di WooCommerce compare un promemoria. Gli ordini esistenti non sono interessati.
Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e assistenza richiedono il rinnovo. Lo stato viene verificato di nuovo automaticamente in background.
Risoluzione dei problemi
SMSA Express non compare 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. Verifica che il paese o * abbia un prezzo, oppure che sia impostato Price for countries not in the table.
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. Apri WooCommerce > Status > Logs, origine vfd_smsa_express, 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 delle città. Gli sviluppatori possono modificare la richiesta, ad esempio il nome della città, con il filtro vfd_smsa_express_live_request_fields.
L'imposta sulla spedizione viene applicata due volte: la tua tariffa o le tariffe SMSA potrebbero già includere l'IVA. Imposta Tax status su None.
Dopo una modifica le tariffe sembrano obsolete: salva la pagina delle impostazioni. Questo cancella le tariffe SMSA in cache.
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 conserva 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 e tariffe in cache vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano per una successiva reinstallazione. Gli ordini esistenti conservano le loro righe di spedizione.
SMSA Express è un marchio registrato del rispettivo titolare. Questo plugin non è affiliato né approvato da SMSA Express.