VibeFox ShipStation for OpenCart — Guida

Requisiti

OpenCart: 3.0.x (testato su 3.0.5.0) o 4.0.2 e successivi (testato su 4.1.0.3).

PHP: 8.0 o successivo.

Account ShipStation: collega i tuoi corrieri in ShipStation (Settings > Shipping > Carriers), poi copia la API Key e la API Secret da ShipStation > Settings > Account > API Settings. L'accesso alle API dipende dal tuo piano ShipStation. L'estensione usa la API V1 di ShipStation (API Key e API Secret). Senza chiavi vengono usate solo le tariffe di riserva.

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

Installazione

Il download è un unico file zip con i pacchetti per entrambe le versioni di OpenCart. Decomprimilo sul tuo computer. Contiene README.txt, il pacchetto per OpenCart 3 vfd_shipstation-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_shipstation.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_shipstation-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 ShipStation 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. Incolla la API Key e la API Secret, inserisci il codice postale di partenza e clicca su Save. La pagina ora elenca i codici corriere del tuo account. Inserisci quello o quelli che ti interessano in Carrier codes e salva di nuovo.

6. Se la valuta predefinita del tuo negozio non è la valuta del tuo account ShipStation, imposta Exchange rate. Facoltativamente, compila le tariffe di riserva.

7. Attiva Enable ShipStation shipping e clicca su Save.

OpenCart 4

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

4. Inserisci la chiave di licenza e le impostazioni come ai passi 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 lo attivi e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni ShipStation che avevi conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox ShipStation > Edit. Le sezioni sono elencate a sinistra. Un solo pulsante Save salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella le tariffe ShipStation in cache e verifica la API Key e la API Secret. La pagina mostra poi i corrieri collegati al tuo account con i loro codici, per esempio "stamps_com (Stamps.com), ups_walleted (UPS by ShipStation)". Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.

Gli avvisi in cima alla pagina ti segnalano quando le tariffe in tempo reale non possono funzionare: nessuna chiave, nessun codice corriere, nessun codice postale di partenza, nessun tasso di cambio, verifica di connessione non riuscita o codici corriere non collegati al tuo account. Un avviso compare anche se l'unità di peso o di lunghezza del negozio non è una che l'estensione sa convertire. Usa kg, g, lb o oz e cm, mm, m o in (System > Settings > Option). Un nome non valido, un campo numerico o una cella di prezzo con un valore negativo o con testo al posto di un numero, un Minimum weight superiore al Maximum weight o un ordinamento che non è un numero intero vengono segnalati come errore, e non viene salvato nulla.

Generali

Enable ShipStation shipping: mostra o nasconde il metodo al checkout. Questo è lo stato dell'estensione in Extensions > Extensions > Shipping.

Name: il nome del metodo di spedizione mostrato al cliente al checkout. Predefinito: ShipStation Shipping. Obbligatorio, massimo 64 caratteri, senza i caratteri < > ; = # { }.

Tax class: la classe fiscale del costo di spedizione, oppure No tax. Le tariffe ShipStation non includono l'imposta sulle vendite. No tax le mostra come quotate; una classe fiscale aggiunge l'imposta sulla spedizione secondo le tue regole fiscali.

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

Account ShipStation

API Key: la API Key di ShipStation > Settings > Account > API Settings. Viene inviata solo a ShipStation e non viene mai registrata nei log. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per modificarla.

API Secret: la API Secret della stessa pagina. Viene trattata come la chiave.

Remove the saved API key and secret: compare quando le chiavi sono salvate. Selezionala e salva per rimuovere entrambe.

Carrier codes: uno o più codici corriere ShipStation, separati da virgole, per esempio stamps_com, ups_walleted. Vengono usati fino a 5 codici, con una richiesta API per corriere. Se ne inserisci di più, vengono mantenuti solo i primi 5 e la pagina te lo segnala. Viene mostrata la tariffa più economica di questi corrieri. Prendi i codici dall'elenco mostrato dopo il salvataggio.

Allowed services: facoltativo, codici servizio ShipStation separati da virgole, per esempio usps_priority_mail, ups_ground. Lascialo vuoto per mostrare il servizio più economico dei corrieri indicati sopra.

Package code: "package" (il valore predefinito) calcola le tariffe per la tua scatola ed esclude le buste e le scatole a tariffa fissa dei corrieri. Lascialo vuoto per calcolare le tariffe di tutti i tipi di pacco offerti dal corriere.

Spedizione da

Ship-from postal code: obbligatorio per le tariffe in tempo reale, per esempio 78703. ShipStation calcola le tariffe solo in base al codice postale, che deve trovarsi nel paese del tuo account ShipStation. OpenCart non ha un codice postale del negozio, quindi non viene mai preso dall'indirizzo del negozio.

Tariffe

Parcels: come il carrello viene inviato a ShipStation.

ShipStation account currency: la valuta in cui ShipStation restituisce le tariffe: USD, CAD, GBP, AUD, NZD o EUR. Predefinito: USD (account statunitensi).

Exchange rate: il prezzo di 1 unità della valuta dell'account nella valuta predefinita del tuo negozio, per esempio 0.92. Serve solo quando la valuta predefinita è diversa da quella dell'account. Senza di esso le tariffe in tempo reale non vengono usate e si applicano le tariffe di riserva. I tassi di cambio non vengono aggiornati automaticamente.

Tariffe di riserva (usate quando non c'è una tariffa in tempo reale: nessuna chiave API, ShipStation non raggiungibile, nessuna tariffa dei corrieri per l'indirizzo; prezzi nella valuta predefinita del negozio; lascia vuoti la tabella e Other countries per nascondere il metodo in questo caso)

Prices by country: una tabella con un prezzo Base per paese e colonne di taglia in base al peso del pacco: 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. Clicca su Add country per aggiungere una riga. Una taglia vuota usa il prezzo base. Un prezzo base di 0 significa spedizione gratuita. La riga * Default (all other countries) si applica ai paesi senza una riga propria. Una riga senza alcun prezzo non viene salvata.

Other countries: il prezzo quando la tabella non ha un prezzo per il paese. Lascialo vuoto per nascondere il metodo in questo caso.

Condizioni

Free shipping from: il subtotale dei prodotti che richiedono spedizione (dopo il coupon, prima delle tasse) a partire dal quale la spedizione è gratuita. In questo caso non viene inviata nessuna richiesta a ShipStation. Lascialo vuoto per disattivarla.

Minimum subtotal: mostra il metodo solo se il subtotale dei prodotti che richiedono spedizione (dopo il coupon, prima delle tasse) è almeno questo importo. Lascialo vuoto per mostrarlo sempre.

Minimum weight: il peso minimo del carrello, nell'unità di peso del tuo negozio (indicata nel nome del campo), per mostrare il metodo. 0 significa nessun limite (predefinito).

Maximum weight: il metodo viene nascosto sopra questo peso del carrello, nell'unità di peso del tuo negozio. 0 significa nessun limite (predefinito).

Disponibilità

Geo zone: offri il metodo 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.

Ignore shipping zones: offri il metodo per i paesi indicati sotto, indipendentemente dalla zona geografica.

Countries: i paesi di destinazione per quella 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 le richieste a ShipStation in storage/logs/vfd_shst_debug.log.php (su OpenCart 4 system/storage/logs/vfd_shst_debug.log.php). Il file non può essere letto dal web. Gli errori API vengono sempre registrati, anche con questa opzione disattivata. La API Key, la API Secret e gli indirizzi dei clienti non vengono mai registrati. Il codice postale viene mascherato. Quando il file raggiunge 5 MB, viene spostato in vfd_shst_debug.old.log.php e viene avviato un nuovo log.

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

Remove data on uninstall: se attivo, disinstallando l'estensione vengono eliminate le impostazioni ShipStation e il log. Se disattivo (predefinito), vengono conservate per una reinstallazione. Le tariffe in cache vengono sempre rimosse. Il servizio ShipStation degli ordini già effettuati viene sempre conservato.

Importazione / Esportazione

Export: clicca su Download JSON per salvare le impostazioni in un file JSON. La API Key e la API Secret non vengono esportate.

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. La API Key e la API Secret salvate vengono mantenute.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di ShipStation. Se è impostata una Geo zone (e Ignore shipping zones è disattivato) e l'indirizzo è fuori da essa, il metodo non viene offerto. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non sono inclusi nel subtotale. L'estensione controlla poi le condizioni: paesi consentiti (con Ignore shipping zones), peso del carrello e subtotale minimo. Buoni regalo, punti fedeltà e credito del negozio non vengono considerati. Se si applica la spedizione gratuita, il metodo viene mostrato con prezzo 0 e non parte nessuna richiesta a ShipStation.

L'estensione invia poi a ShipStation il codice postale di partenza, il paese di destinazione, il codice di stato, la città e il codice postale, il peso del pacco e la dimensione della scatola. Nessuna richiesta viene fatta prima che il cliente inserisca un codice postale. I paesi senza codici postali ricevono le tariffe di riserva. Gli articoli vengono impilati in una scatola. Se un prodotto non ha dimensioni, il pacco viene tariffato solo in base al peso.

ShipStation viene interrogato una volta per ogni codice corriere. L'estensione usa la tariffa consentita più economica, convertita nella valuta predefinita del negozio e arrotondata alle sue cifre decimali. Il prezzo viene poi mostrato nella valuta del cliente con l'imposta della Tax class selezionata.

Ogni risposta viene memorizzata nella cache per 1 ora. Quando ShipStation risponde senza una tariffa utilizzabile, la risposta viene ricordata per 10 minuti. Quando ShipStation rifiuta le chiavi o non è raggiungibile, le richieste vengono sospese per 5 minuti. Dopo un limite di richieste, la pausa segue l'orario di reset comunicato da ShipStation. Il timeout delle richieste è di 12 secondi.

Se non c'è una tariffa in tempo reale, il prezzo proviene dalla tabella di riserva e poi da Other countries. Se nessuna delle due si applica, il metodo viene nascosto. Il cliente non vede mai i testi di errore di ShipStation. I dettagli finiscono nel log di debug.

L'estensione calcola solo le tariffe. Non acquista etichette, non crea ordini o spedizioni in ShipStation, non traccia i pacchi e non gestisce resi. Non ci sono punti di ritiro, né scelta tra più servizi al checkout, né validazione dell'indirizzo, assicurazione, conferma della firma, imballaggio in più pacchi né maggiorazione delle tariffe.

Su OpenCart 4 il cliente clicca su Choose nel blocco del metodo di spedizione della pagina di checkout e sceglie ShipStation nella finestra Shipping method options. Il metodo funziona come su OpenCart 3.

Ordini

Quando un ordine viene effettuato con una tariffa ShipStation in tempo reale, il servizio scelto viene salvato con l'ordine. Apri l'ordine in Sales > Orders: il pannello ShipStation sopra la cronologia dell'ordine lo mostra come Service, per esempio "USPS Ground Advantage - Package", così puoi creare l'etichetta corrispondente in ShipStation. In modalità per articolo, i servizi sono elencati separati da virgole. Le modifiche successive al carrello non lo cambiano, e il pannello viene mostrato anche dopo che hai disattivato il metodo. Gli ordini con tariffa di riserva o spedizione gratuita non hanno il pannello ShipStation.

OpenCart 4 mantiene un solo ordine per il checkout e lo aggiorna ogni volta che il cliente conferma di nuovo. Il servizio ShipStation salvato viene aggiornato insieme ad esso. Se il cliente passa a un altro metodo di spedizione, o se ora si applica la tariffa di riserva, il servizio salvato viene rimosso dall'ordine.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza License — VibeFox ShipStation è il primo blocco della pagina Extensions > Extensions > Shipping > VibeFox ShipStation > Edit, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopo di che 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: opencart-shipping-shipstation 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 che l'indirizzo del negozio cambia, o dopo che hai liberato uno slot di 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 slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, ShipStation non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Un utente amministratore che ha effettuato l'accesso all'amministrazione nello stesso browser vede comunque il metodo nel negozio, contrassegnato con (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 è nascosto a tutti. Dopo aver aperto una volta la pagina Edit, nella Dashboard dell'amministrazione compare un promemoria. Chiudilo con × per nasconderlo per 7 giorni. Gli ordini esistenti non vengono modificati.

Quando una licenza scade, l'estensione continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene verificato di nuovo 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 rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

ShipStation non compare al checkout: controlla che la licenza sia attiva e che Enable ShipStation shipping sia attivo. Controlla Geo zone (o, con Ignore shipping zones attivo, Countries), i limiti di peso e il Minimum subtotal. Senza una tariffa in tempo reale, verifica che il paese, * Default o Other countries abbia un prezzo. Controlla che i prodotti abbiano Requires Shipping impostato su Yes.

Il checkout mostra la tariffa di riserva invece della tariffa ShipStation: controlla gli avvisi in cima alla pagina dell'estensione (chiavi, codice corriere, codice postale di partenza, tasso di cambio). Attiva Debug log, ricarica il checkout e controlla il campo Log. Il codice postale del cliente è obbligatorio. Nessuna richiesta viene fatta finché non viene inserito.

Quale codice corriere inserire: salva le impostazioni con la chiave e il secret. La pagina elenca i codici corriere del tuo account. Usane uno o più.

Verifica della connessione a ShipStation non riuscita: il messaggio indica il motivo. Controlla la API Key e la API Secret, poi salva di nuovo per ripetere la verifica.

La tariffa non corrisponde a quella di ShipStation: il pacco viene costruito dai pesi e dalle dimensioni dei prodotti, con gli articoli impilati in una scatola. I prodotti senza dimensioni vengono tariffati solo in base al peso. Le tariffe sono in cache per 1 ora. Clicca su Save nella pagina dell'estensione per svuotare la cache.

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

Per sviluppatori: l'indirizzo delle API di ShipStation può essere sostituito con l'impostazione vfd_shst_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 ShipStation. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable ShipStation shipping, Sort order, Tax class e Geo zone. Le tariffe in cache e il risultato della verifica di connessione vengono sempre rimossi. Se Remove data on uninstall è attivo, vengono eliminati anche le impostazioni ShipStation 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, il costo e il servizio ShipStation.

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 ShipStation nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per rimuovere il pacchetto caricato.

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