VibeFox Sameday Easybox for OpenCart — Guida

Requisiti

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

PHP: 8.0 o successivo.

Nome utente e password API di Sameday: l'accesso API fa parte di un account business Sameday in Romania, Ungheria o Bulgaria. Chiedi al tuo account manager Sameday o al team di integrazione Sameday. Le credenziali sono spesso le stesse del portale eAWB (eawb.sameday.ro, .hu o .bg). Per l'API demo, Sameday fornisce credenziali di prova separate. Senza nome utente e password API il metodo non viene offerto, perché il cliente non potrebbe scegliere un locker.

Paese e contee: il paese del tuo account Sameday deve essere attivo in System > Localisation > Countries. La stima di Sameday richiede la contea dell'indirizzo di consegna (il campo Region / State). OpenCart ha le contee di Romania e Bulgaria, ma in OpenCart 3 nessuna per l'Ungheria (in OpenCart 4.1 ci sono). L'estensione può aggiungerle per te (vedi più sotto, locker easybox). Senza di esse, i prezzi provengono dalla tua tabella o dal costo di riserva.

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un solo 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_sameday_easybox-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_sameday_easybox.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_sameday_easybox-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non devi aggiornare Extensions > Modifications. Invece dell'Installer, puoi copiare il contenuto della cartella upload di questo pacchetto nella cartella radice del tuo negozio.

2. Vai su Extensions > Extensions, scegli il tipo di estensione Shipping, trova VibeFox Sameday Easybox 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 di licenza in alto nella pagina Edit, e clicca su Activate (vedi Chiave di licenza).

5. Inserisci il tuo API username e la tua API password di Sameday, scegli il Sameday country, attiva Enable/Disable e clicca su Save. La pagina dovrebbe mostrare "Connected to Sameday ... easybox lockers". Pickup point e Easybox service vengono compilati dal tuo account.

6. Imposta i prezzi: Exchange rate of the estimate se la valuta del tuo negozio è diversa da quella di Sameday, e una riga di Country prices (ad esempio * Default) oppure un Fallback cost.

7. Se la pagina indica che OpenCart non ha contee per il tuo paese Sameday, clicca su Add counties nella sezione easybox lockers.

OpenCart 4

1. Nell'amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_sameday_easybox.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 a esso.

3. Vai su Extensions > Extensions, scegli il tipo di estensione Shipping, trova VibeFox Sameday Easybox, 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. Cambia solo l'URL del cron (vedi locker easybox).

Dopo l'installazione il metodo è disattivato finché non attivi Enable/Disable e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni conservate, ma il metodo parte disattivato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox Sameday Easybox > Edit. Le sezioni sono elencate a sinistra. Un pulsante Save in fondo salva l'intera pagina senza ricaricarla. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.

Sopra le impostazioni la pagina mostra lo stato della connessione: l'host di Sameday, il numero di locker easybox e quando è stato aggiornato l'elenco, oppure che Sameday ha rifiutato il nome utente o la password. Elenca anche i problemi di configurazione, ad esempio credenziali mancanti, prezzo mancante, tasso di cambio mancante per la stima, contee mancanti, nessuna classe di peso in chilogrammi o paesi selezionati al di fuori del tuo paese Sameday.

Alcuni errori bloccano il salvataggio, e non viene salvato nulla: Enter a valid name (1-64 characters, without < > ; = # { })., Sort order must be a whole number., una classe fiscale o una zona geografica non valida. Altri problemi mantengono solo un valore: tutti i prezzi e i limiti accettano una virgola o un punto come separatore decimale (4,99 o 4.99), e un numero non valido o negativo non viene salvato. Un avviso indica il campo e viene mantenuto il valore precedente.

Generali

Enable/Disable: mostra o nasconde il metodo al checkout. È lo stato dell'estensione in Extensions > Extensions > Shipping. Predefinito: disattivo.

Name: il nome del metodo di spedizione mostrato al cliente. Predefinito: Sameday easybox. Fino a 64 caratteri.

Tax class: --- None --- (predefinito) significa che il prezzo è definitivo. Con una classe fiscale, OpenCart aggiunge al prezzo l'imposta di quella classe.

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

Account Sameday (API)

Al salvataggio, l'estensione accede a Sameday e carica i tuoi servizi, i punti di ritiro e l'elenco dei locker easybox. L'elenco viene aggiornato ogni giorno.

API username: il tuo nome utente API di Sameday.

API password: la tua password API di Sameday. Non viene mai mostrata di nuovo: lascia il campo vuoto per mantenere quella salvata. Svuotare il nome utente rimuove anche la password. Se Sameday la rifiuta, non viene riprovata per 10 minuti.

Sameday country: il paese del tuo account Sameday: Romania (api.sameday.ro) (predefinito), Hungary (api.sameday.hu) o Bulgaria (api.sameday.bg). Vengono offerti i suoi locker, e il metodo viene mostrato solo per questo paese di destinazione.

Test mode: usa l'API demo di Sameday (sameday-api.demo.zitec.com) con credenziali demo.

Prezzi (il titolo della sezione mostra la valuta predefinita del tuo negozio)

L'ordine di utilizzo è: la stima di Sameday (quando Pickup point e Easybox service sono impostati), poi la tabella dei prezzi per paese e infine il costo di riserva. I prezzi della tabella si inseriscono nella valuta predefinita del negozio. I clienti che pagano in un'altra valuta vedono il prezzo convertito.

Pickup point: il tuo punto di ritiro Sameday, dove Sameday ritira i pacchi. Dopo un accesso riuscito è un elenco dei punti di ritiro del tuo account, e quello predefinito viene scelto automaticamente. Prima di allora è un campo per l'ID. Serve per la stima di Sameday. Scegli - not set (price table only) - per usare solo la tabella dei prezzi.

Easybox service: il servizio Sameday per la consegna easybox, di solito "Locker NextDay" (codice LN), scelto automaticamente. Serve per la stima di Sameday.

Exchange rate of the estimate: Sameday calcola le stime nella valuta del tuo paese Sameday: RON, HUF o BGN (EUR per i negozi bulgari che vendono in euro). Se il tuo negozio vende in un'altra valuta, inserisci il valore di 1 unità della valuta Sameday nella valuta del tuo negozio, ad esempio 0.20. Il tasso deve essere superiore a 0. Senza di esso la stima non viene usata e si applica la tabella dei prezzi. Lev ed euro vengono convertiti automaticamente al tasso fisso.

Table price: Per order addebita il prezzo una sola volta. Per item (price x quantity) lo moltiplica per il numero di articoli. Vale per il prezzo della tabella e per il costo di riserva. La stima di Sameday è sempre per l'intero pacco.

Country prices: un prezzo per paese di destinazione e peso del pacco. Clicca su Add country per aggiungere una riga e sul pulsante di rimozione per cancellarne una. Ogni riga ha una colonna Price e colonne di peso: XS fino a 1 kg, S 1-2 kg, M 2-3 kg, L 3-5 kg e XL oltre 5 kg. Una colonna di peso lasciata a 0 o vuota usa la colonna Price. La riga * Default si applica ai paesi senza una riga propria. Una nuova riga inizia come * Default con tutti i prezzi a 0, cioè spedizione gratuita. Scegli il paese e inserisci i prezzi prima di salvare, oppure rimuovi la riga. Se lo stesso paese compare in due righe, al salvataggio ne resta solo una, la prima, e un avviso lo segnala. Se una cella non è un numero pari o superiore a 0, la tabella non viene salvata.

Fallback cost: usato quando non c'è una stima di Sameday e la tabella dei paesi non ha una riga per la destinazione. Lascialo vuoto per non offrire il metodo in quel caso.

Free shipping from: il subtotale del carrello (prodotti che richiedono la spedizione, dopo gli sconti, senza imposte) da cui la consegna easybox è gratuita. Quando il subtotale lo raggiunge, il metodo viene offerto senza costi e non viene richiesto alcun prezzo. Lascialo vuoto per non offrire mai la spedizione gratuita.

Disponibilità

Minimum weight (kg): nasconde il metodo quando il carrello pesa meno. Il peso viene convertito dalla classe di peso dei prodotti. Vuoto o 0 significa nessun limite.

Maximum weight (kg): i pacchi più pesanti di questo valore non ricevono la consegna easybox. Predefinito: 30. Controlla il limite del tuo contratto Sameday e le dimensioni delle box easybox. Vuoto o 0 significa nessun limite. Un peso minimo superiore al massimo non viene salvato: un avviso lo indica e restano i valori precedenti.

Minimum cart subtotal: offri il metodo solo quando il subtotale del carrello (prodotti che richiedono la spedizione, dopo gli sconti, senza imposte) raggiunge questo importo. Vuoto significa nessun minimo.

Geo zone: offri il metodo solo per indirizzi in questa zona geografica. All Zones (predefinito) significa nessun limite. Le zone geografiche si gestiscono in System > Localisation > Geo Zones. Non viene verificata quando Ignore shipping zones è attivo.

Ignore shipping zones: quando è attivo, la zona geografica non viene verificata e il metodo viene offerto per i paesi selezionati sotto (il paese Sameday se l'elenco è vuoto). Quando è disattivo, vale solo la zona geografica sopra.

Countries (ignore zones mode): i paesi di destinazione per questa modalità. I paesi diversi dal paese Sameday vengono saltati, e la pagina li segnala. Questo campo viene usato solo quando Ignore shipping zones è attivo.

Locker easybox

Locker list: mostra quanti locker easybox in quante città sono caricati e quando. Refresh the locker list now lo ricarica. L'elenco viene aggiornato al salvataggio delle impostazioni e, quando ha più di un giorno, dopo una richiesta di checkout (al massimo una volta l'ora). Per un aggiornamento giornaliero fisso, richiama una volta al giorno l'URL mostrato qui da un cron del tuo server. Per OpenCart 3 l'URL è simile a https://your-store/index.php?route=extension/shipping/vfd_sameday_easybox/cron&token=(token), per OpenCart 4 a https://your-store/index.php?route=extension/vfd_sameday_easybox/shipping/vfd_sameday_easybox.cron&token=(token). Copia l'URL esattamente come lo mostrano le impostazioni. L'URL contiene un token segreto. Senza il token giusto risponde con un errore e non contatta Sameday. Non fa nulla nemmeno finché il metodo è disattivo.

Counties: mostra quante contee ha OpenCart per il tuo paese Sameday. Se non ne ha nessuna, clicca su Add counties. L'estensione aggiunge le contee di quel paese in System > Localisation > Zones, e il campo Region / State del modulo indirizzo le mostrerà. Le contee già presenti non vengono aggiunte due volte. In OpenCart 4.1 le contee di tutti e tre i paesi sono già presenti, quindi il pulsante non serve lì.

Avanzate

Debug log: scrive i calcoli delle tariffe, le chiamate API e le scelte dei locker in storage/logs/vfd_sdeb_debug.log.php, file che non può essere letto dal web. Gli errori API vengono sempre registrati. Nessuna password, token o dato personale del cliente viene registrato. Quando il file raggiunge 5 MB, si avvia un nuovo log. Disattiva il log quando hai finito.

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

Remove data on uninstall: quando è attivo, la disinstallazione dell'estensione elimina le impostazioni, i dati Sameday in cache e il log. Quando è disattivo (predefinito), le impostazioni vengono conservate. L'elenco dei locker e le cache vengono sempre rimossi. Il locker salvato negli ordini viene sempre conservato.

Importazione / Esportazione

Export: clicca su Download JSON per salvare le impostazioni in un file JSON. La password API non viene esportata.

Import: incolla il JSON esportato in precedenza e clicca su Import. I valori superano gli stessi controlli del modulo. La password salvata viene mantenuta.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo della consegna easybox di Sameday. L'estensione verifica la zona geografica (o i paesi di Ignore shipping zones), il paese di consegna del tuo account Sameday, le credenziali API e un elenco di locker utilizzabile, il peso del carrello e il subtotale minimo. Contano solo i prodotti con Requires Shipping impostato su Yes. Il subtotale è il prezzo di questi prodotti senza imposte, dopo lo sconto del coupon. Se si applica la spedizione gratuita, il cliente vede il metodo senza costi.

Altrimenti l'estensione chiede a Sameday una stima, una volta che il cliente ha inserito una città e una contea. Invia il tuo punto di ritiro e servizio, il peso del pacco e l'indirizzo del cliente (via, città, contea e CAP). Non vengono inviati nome, e-mail o telefono. Bucarest viene inviata come "Sector 1", come il plugin ufficiale di Sameday. La stima viene convertita nella valuta del tuo negozio. Se non c'è una stima (non configurata, ancora nessuna città o contea, errore, nessun tasso di cambio), il prezzo viene dalla tabella del paese, poi dal costo di riserva. Se non c'è alcun prezzo, il metodo viene nascosto. Il prezzo viene mostrato nella valuta del cliente con l'imposta della Tax class selezionata.

I problemi di Sameday non interrompono mai il checkout. La stima viene memorizzata nella cache per 1 ora. Un errore viene memorizzato nella cache per 10 minuti. Dopo un timeout o un errore del server, per 5 minuti non viene richiesta alcuna stima. Le richieste scadono dopo 15 secondi. Durante il checkout, l'elenco dei locker viene letto dal tuo server, non da Sameday.

L'estensione non crea AWB (spedizioni), non stampa etichette, non traccia i pacchi e non gestisce il contrassegno. Non offre consegna a domicilio con corriere né il widget mappa di Sameday. Crea l'AWB nel portale Sameday eAWB o nel tuo strumento abituale con l'ID del locker mostrato nell'ordine.

Su OpenCart 4 il cliente clicca su Choose nel blocco del metodo di spedizione della pagina di checkout e sceglie Sameday easybox nella finestra Shipping method options. I prezzi sono gli stessi di OpenCart 3.

Punti di ritiro

Quando il cliente seleziona il metodo, sotto di esso compare un blocco easybox locker con due elenchi: - Select city - e - Select easybox locker -. La città dell'indirizzo di consegna viene preselezionata se ha dei locker. Ogni locker mostra nome e indirizzo. La scelta viene salvata subito per il checkout, quindi resta anche se si riapre il passaggio della consegna.

Il locker è obbligatorio. Senza di esso il cliente non può proseguire e vede "Please choose a Sameday easybox locker.". Quando il cliente clicca su Continue, il server verifica che il locker scelto sia nell'elenco. Un ID di locker falsificato o rimosso viene rifiutato con "The selected easybox locker is not available any more. Please choose another easybox locker.". Se l'elenco non può essere caricato, il cliente vede "The easybox lockers could not be loaded. Please try again in a moment or choose another shipping method.". Nome e indirizzo salvati con l'ordine provengono dall'elenco, non dal browser.

Pagine dell'ordine, e-mail e fattura: il locker viene aggiunto al metodo di spedizione dell'ordine, ad esempio "Sameday easybox: nome - indirizzo" (prima il nome del metodo, poi il locker). Il cliente lo vede nella conferma d'ordine, nello storico ordini e nelle e-mail d'ordine, e tu lo vedi in fattura.

Pagina ordine nell'amministrazione: in Sales > Orders, la pagina dell'ordine ha un pannello Sameday easybox locker con nome e indirizzo e il Locker ID per l'AWB Sameday. Se un ordine easybox non ha un locker, il pannello indica "No easybox locker was selected for this order.". Il pannello viene mostrato anche mentre il metodo è disattivo.

Su OpenCart 4 il blocco easybox locker compare nella finestra Shipping method options, sotto l'opzione Sameday easybox, e l'elenco delle città viene ricaricato ogni volta che la finestra si apre, perché l'indirizzo può cambiare nel checkout in una pagina. Il pulsante Continue della finestra non procede senza un locker valido, con gli stessi messaggi. OpenCart 4 mantiene un unico ordine per il checkout e lo aggiorna ogni volta che il cliente conferma di nuovo, e il locker dell'ordine viene aggiornato con esso. Il pannello della pagina ordine nell'amministrazione viene mostrato sopra la sezione History.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox Sameday Easybox è il primo blocco di Extensions > Extensions > Shipping > VibeFox Sameday Easybox > Edit, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (ad 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-sameday-easybox 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 spiega il motivo, ad esempio Key not found, This key belongs to another product, Domain limit reached o License expired on con una data. Dopo che l'indirizzo del negozio cambia, o dopo aver 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 solo 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, il metodo di spedizione Sameday easybox non viene mostrato ai clienti al checkout e non viene richiesto né calcolato alcun prezzo. Un 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 provare l'estensione prima di acquistare una chiave. Su OpenCart 4 questa anteprima non è disponibile: il negozio non vede l'accesso all'amministrazione, 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 sono interessati.

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 o la pagina Edit dell'amministrazione: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve alcun cron. La disinstallazione dell'estensione rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Sameday easybox non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che nome utente e password API siano inseriti e che la pagina delle impostazioni dica "Connected to Sameday", e che il paese di destinazione sia quello del tuo account Sameday. Verifica che sia disponibile un prezzo (stima Sameday, riga del paese, riga * Default o Fallback cost), i limiti di peso e subtotale, Geo zone e i paesi di Ignore shipping zones. Verifica che i prodotti abbiano Requires Shipping impostato su Yes. Attiva Debug log per vedere il motivo nel campo Log.

Sameday ha rifiutato il nome utente o la password API: controllali e salva di nuovo. Le credenziali demo funzionano solo con Test mode attivo, quelle di produzione solo con esso disattivo. Nel frattempo viene offerto l'elenco dei locker salvato, se esiste, e la stima di Sameday non viene usata.

Il prezzo arriva dalla mia tabella, non da Sameday: la stima richiede un Pickup point, il Easybox service, le contee del tuo paese Sameday e, se la valuta del negozio è diversa da quella di Sameday, l'Exchange rate of the estimate. Viene richiesta solo dopo che il cliente ha inserito una città e una contea. Quando Sameday non è raggiungibile o restituisce un errore, si usa la tabella o il costo di riserva; il motivo è nel log.

L'elenco dei locker è vecchio o manca: clicca su Refresh the locker list now o salva le impostazioni. Se un aggiornamento non riesce, viene usato l'elenco precedente e lo stato lo segnala.

La spedizione è gratuita per errore: verifica Free shipping from e le righe di Country prices con un Price pari a 0, soprattutto una riga * Default aggiunta con Add country e lasciata vuota.

I limiti di peso o le colonne di peso non corrispondono: se la pagina avvisa che non esiste una classe di peso con unità "kg", aggiungi una classe di peso in chilogrammi in System > Localisation > Weight Classes.

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

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox Sameday Easybox. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable/Disable, Sort order, Tax class e Geo zone. L'elenco dei locker salvato, il risultato della verifica dell'account e tutte le cache vengono sempre rimossi. Se Remove data on uninstall è attivo, vengono eliminate anche le altre impostazioni, il token cron e il log. Se è disattivo, vengono conservate e riutilizzate alla reinstallazione dell'estensione. Gli ordini esistenti conservano il locker salvato.

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

Sameday ed easybox sono marchi dei rispettivi proprietari. Questa estensione non è affiliata a Sameday né approvata da Sameday.