VibeFox Mondial Relay 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) con il tema predefinito.

PHP: 8.0 o successivo.

Account Mondial Relay: il codice brand (Enseigne) e la chiave privata sono forniti con un account business di Mondial Relay: consulta la sezione per professionisti di mondialrelay.fr, la tua area clienti "Connect" o il tuo referente commerciale. Il selettore della mappa richiede solo il codice brand. L'elenco dei punti più vicini richiede entrambi. Per i test, Mondial Relay fornisce il codice brand BDTEST13 con la chiave privata PrivateK.

Chiave di licenza VibeFox: acquistata 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_mondialrelay-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_mondialrelay.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. Nel pannello di amministrazione vai su Extensions > Installer, fai clic su Upload e scegli il file vfd_mondialrelay-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 principale del tuo negozio.

2. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox Mondial Relay e fai clic su Install (il pulsante verde +).

3. Fai clic su Edit (il pulsante a forma di 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 fai clic su Activate (vedi Chiave di licenza).

5. Inserisci il tuo codice brand (Enseigne) e, per la modalità elenco, la chiave privata. Compila Country prices (per esempio una riga per la Francia) o un Fallback cost, attiva Enable/Disable e fai clic su Save.

OpenCart 4

1. Nel pannello di amministrazione vai su Extensions > Installer, fai clic su Upload e scegli il file vfd_mondialrelay.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. Fai clic su Install (il pulsante verde +) accanto a esso.

3. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox Mondial Relay, fai clic 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 4 e 5 per OpenCart 3. La pagina delle impostazioni e i suoi campi sono uguali nelle due versioni.

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

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox Mondial Relay > Edit. Le sezioni sono elencate a sinistra. Un solo pulsante Save salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella anche gli elenchi di punti di ritiro in cache. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.

Gli avvisi in cima alla pagina mostrano i problemi che nascondono il metodo: codice brand mancante, chiave privata mancante in modalità elenco, nessun prezzo per Francia, Belgio o Spagna, e un'unità di peso del negozio che l'estensione non riconosce (i pesi dei prodotti vengono allora letti come kg). Se Name è vuoto, supera i 64 caratteri o contiene uno dei caratteri < > ; = # { }, se Min weight (kg) è maggiore di Max weight (kg), o se il codice brand non è valido, la pagina mostra un errore e non viene salvato nulla. Un campo numerico con un valore che non è un numero (o è negativo) viene segnalato dopo Save e mantiene il valore precedente; gli altri impostazioni vengono salvate.

Generale

Consegna in Point Relais Mondial Relay per Francia, Belgio, Lussemburgo, Spagna, Portogallo e Paesi Bassi. Il metodo viene offerto nella sua zona geografica (vedi Availability) o, con Ignore shipping zones, nei paesi elencati.

Enable/Disable: mostra o nasconde Mondial Relay al checkout. Predefinito: disattivato.

Name: il nome del metodo di spedizione mostrato ai clienti nel carrello e al checkout. Predefinito: Mondial Relay Point Relais. Obbligatorio, fino a 64 caratteri.

Tax status: None (predefinito) significa che i prezzi della tabella sono definitivi. L'opzione Taxable con il nome di una classe fiscale significa che OpenCart aggiunge sopra i prezzi l'imposta di spedizione di quella classe.

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

Account Mondial Relay

Brand code (Enseigne): obbligatorio, fino a 8 lettere e cifre, per esempio BDTEST13 per i test. Viene usato dalla mappa dei punti di ritiro e dal Web Service. Senza di esso i clienti non possono scegliere un Point Relais, quindi il metodo non viene mostrato al checkout.

Private Key: necessaria solo per il selettore List of nearest points. Dopo il salvataggio il campo resta vuoto e mostra Saved - leave empty to keep it. Inserisci un valore nuovo solo per modificarla. Per eliminare la chiave salvata, spunta Remove the saved Private Key e fai clic su Save. Quando il codice brand e la chiave privata sono impostati, la connessione al Web Service di Mondial Relay viene verificata ogni volta che salvi le impostazioni, e un messaggio indica se sono validi.

Selettore del punto di ritiro

Il cliente deve scegliere un Point Relais prima di proseguire alla fase di pagamento. Il punto viene salvato nell'ordine.

Selettore: come il cliente sceglie un Point Relais.

Tariffe (nella valuta predefinita del negozio, IVA esclusa)

Mondial Relay non ha un'API pubblica per le tariffe: il prezzo proviene da questa tabella.

Country prices: prezzo per paese di destinazione e peso del pacco. Fai clic su Add country per aggiungere una riga e sul pulsante di rimozione per eliminarne una. Scegli * Default come paese per tutti gli altri paesi. Ogni riga ha un 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 vuota o con 0 usa la colonna Price. Se anche Price è vuoto, la consegna per quel peso è gratuita, quindi compila Price quando usi solo alcune colonne di peso. Decimali con punto o virgola (4.90 o 4,90). Le righe senza alcun prezzo e quelle con un paese sconosciuto vengono eliminate al salvataggio, e i valori che non sono numeri vengono segnalati e lasciati vuoti.

Fallback cost: usato per i paesi senza una riga nella tabella. Lascialo vuoto per nascondere il metodo per questi paesi.

Calculation type: come viene calcolato il prezzo.

Free shipping from: il subtotale del carrello (dopo gli sconti, senza IVA) a partire dal quale la consegna è gratuita. Lascialo vuoto se non vuoi la spedizione gratuita.

Disponibilità

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

Max weight (kg): nasconde il metodo quando il carrello pesa di più. Mondial Relay accetta pacchi fino a 30 kg nei Points Relais. Predefinito: 30. 0 significa nessun limite. Un campo vuoto significa 30 kg.

Minimum subtotal: mostra il metodo solo quando il subtotale del carrello (prodotti che richiedono spedizione, dopo gli sconti, senza IVA) è almeno questo importo. Lascialo vuoto per mostrarlo sempre.

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

Ignore shipping zones: quando è attivo, la Geo zone non viene verificata: il metodo viene offerto solo nei paesi indicati sotto, oppure in tutti i paesi supportati se l'elenco è vuoto.

Countries (ignore zones): i paesi di destinazione per quella modalità. Questo campo viene usato solo quando Ignore shipping zones è attivo. L'elenco contiene solo i paesi con Points Relais.

Avanzate

Debug log: scrive i calcoli delle tariffe, le chiamate al Web Service e le scelte dei punti in storage/logs/vfd_mrel_debug.log.php (su OpenCart 4 system/storage/logs/vfd_mrel_debug.log.php). Il file non può essere letto dal web. Gli errori vengono sempre registrati, anche con questa opzione disattivata. Chiavi e dati dei clienti non vengono mai registrati. Quando il file raggiunge 5 MB, viene spostato in vfd_mrel_debug.old.log.php e si avvia un nuovo log.

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

Remove data on uninstall: se attivo, disinstallando l'estensione vengono eliminate le impostazioni e il log. Se disattivo (predefinito), vengono conservate per una nuova installazione. Gli elenchi di punti in cache vengono sempre rimossi. I punti di ritiro salvati negli ordini vengono conservati.

Importa / Esporta

Export: fai clic su Download JSON per salvare le impostazioni in un file JSON, senza la chiave privata.

Import: incolla un JSON esportato in precedenza e fai clic su Import per ripristinare le impostazioni, per esempio in un altro negozio. Si applicano gli stessi controlli di Save. La chiave privata salvata viene conservata.

Come funziona al checkout

Il metodo viene offerto solo per i paesi con Points Relais: Francia, Belgio, Lussemburgo, Spagna, Portogallo e Paesi Bassi. Viene nascosto quando i clienti non potrebbero scegliere un punto: senza codice brand, o in modalità elenco senza la chiave privata. Se è impostata una Geo zone e l'indirizzo è al di fuori di essa, il metodo non viene offerto. Con Ignore shipping zones attivo, la zona geografica non viene verificata e vengono serviti solo i paesi di quell'elenco (tutti i paesi supportati se è vuoto).

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri prodotti non aggiungono peso e non sono inclusi nel subtotale. I pesi dei prodotti vengono convertiti dalla loro classe di peso di OpenCart in kg. Il subtotale è il prezzo dei prodotti che richiedono spedizione, dopo lo sconto del coupon e prima delle imposte. L'estensione verifica il peso del carrello e il subtotale minimo. Il prezzo proviene dalla riga del paese (o dalla riga *): la colonna di peso e, altrimenti, Price. Senza una riga si usa il costo di riserva. Se non c'è alcun prezzo, il metodo viene nascosto. Se il subtotale raggiunge Free shipping from, il prezzo diventa 0. Il prezzo viene calcolato nella valuta predefinita del negozio, arrotondato ai suoi decimali e mostrato nella valuta del cliente con l'imposta della Tax status selezionata. Per calcolare il prezzo non viene inviata alcuna richiesta a Mondial Relay.

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

L'estensione non richiede tariffe in tempo reale: Mondial Relay non ha un'API pubblica per le tariffe. Non crea spedizioni, non stampa etichette e non traccia i pacchi. Crea le spedizioni nel tuo spazio "Connect" di Mondial Relay usando il numero di Point Relais mostrato nell'ordine. La consegna a domicilio (Domicile) non viene offerta.

Punti di ritiro

Quando il cliente seleziona l'opzione Mondial Relay nella fase del metodo di spedizione, sotto di essa compare un riquadro Mondial Relay pickup point.

Modalità mappa: il pulsante Choose a Point Relais apre in una finestra la mappa ufficiale di Mondial Relay per il paese di consegna, il codice postale e il peso del pacco. Quando il cliente sceglie un punto, questo viene mostrato come Selected: e il pulsante diventa Change Point Relais. Il widget della mappa viene caricato da widget.mondialrelay.com e la sua libreria da unpkg.com solo quando il cliente apre la mappa. Menzionalo nella tua informativa sulla privacy.

Modalità elenco: un menu a tendina - Choose a Point Relais - mostra i 10 punti più vicini al codice postale di consegna, con la loro distanza. Il punto scelto viene mostrato con i suoi orari. L'elenco viene caricato dal tuo server, quindi per esso nel browser non viene eseguito alcuno script di terze parti. Gli elenchi vengono memorizzati in cache per 12 ore, una risposta vuota per 1 ora, e una richiesta non riuscita viene ricordata per 5 minuti. Il timeout del Web Service è di 10 secondi. Senza codice postale il cliente vede Enter your postcode to see the nearest pickup points. Se non viene trovato alcun punto o l'elenco non è disponibile, il cliente vede un messaggio come "L'elenco dei punti di ritiro non è disponibile al momento. Usa la mappa." e gli viene offerta la mappa.

Il punto scelto viene salvato subito per la sessione del cliente. Un punto è obbligatorio. Quando il cliente fa clic su Continue, il negozio verifica di nuovo il punto. Senza un punto, il cliente vede Please choose a Mondial Relay pickup point. e non può proseguire al pagamento. Un punto in un paese diverso da quello dell'indirizzo di consegna viene rifiutato con un messaggio che indica che il punto non si trova nel paese di consegna. In modalità elenco il punto viene inoltre confrontato con l'elenco per l'indirizzo. Dopo che l'ordine è stato effettuato, la scelta viene cancellata, così il carrello successivo sceglie di nuovo.

Su OpenCart 4 il riquadro Mondial Relay pickup point compare nella finestra Shipping method options, sotto l'opzione Mondial Relay, e la mappa si apre all'interno di quella finestra. Il tasto Escape chiude solo la mappa. Il pulsante Continue della finestra non procede senza un punto valido, con gli stessi messaggi.

Quando l'ordine viene effettuato, il punto resta associato all'ordine. Il metodo di spedizione dell'ordine mostra il nome del metodo seguito dal nome, dall'indirizzo e dal numero del punto, per esempio Mondial Relay Point Relais: TABAC DU LOUVRE, 12 RUE DE RIVOLI, 75001 PARIS (FR-066974), così il cliente lo vede nell'e-mail dell'ordine e nello storico ordini del suo account. L'e-mail di nuovo ordine per il negozio mostra il punto con il suo numero nel blocco dei commenti. In Sales > Orders, la pagina dell'ordine mostra un riquadro Mondial Relay pickup point con il nome del punto, l'indirizzo e il numero Point Relais, oppure No Point Relais was saved for this order. Su OpenCart 4 il riquadro è mostrato sopra History. OpenCart 4 mantiene un unico ordine per il checkout e lo aggiorna ogni volta che il cliente conferma di nuovo, e il punto dell'ordine viene aggiornato insieme ad esso. Se il cliente passa quell'ordine a un altro metodo di spedizione, il suo punto viene rimosso.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza License — VibeFox Mondial Relay è il primo blocco di Extensions > Extensions > Shipping > VibeFox Mondial Relay > Edit, 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: opencart-shipping-mondialrelay e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo gli utenti amministratori con il permesso di modifica per l'estensione possono cambiare la chiave. I testi del blocco seguono la lingua del pannello di 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 oppure License expired on con una data. Dopo la modifica 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, 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. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, Mondial Relay non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Un utente amministratore che ha effettuato l'accesso al pannello di amministrazione nello stesso browser vede comunque il metodo nel negozio, contrassegnato da (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 dell'amministratore, quindi senza una chiave attiva il metodo è nascosto a tutti. Dopo aver aperto una volta la pagina Edit, nella Dashboard del pannello di 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 assistenza richiedono il rinnovo. Lo stato viene controllato di nuovo automaticamente quando apri la Dashboard del pannello di 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. La disinstallazione dell'estensione rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Mondial Relay non compare al checkout: verifica che la licenza sia attiva e che Enable/Disable sia attivo. Controlla Geo zone, oppure Ignore shipping zones e il suo elenco di paesi. Controlla gli avvisi in cima alla pagina dell'estensione: il metodo viene nascosto senza codice brand, in modalità elenco senza la chiave privata, per un paese senza prezzo, fuori dai limiti di peso e di subtotale, e per i paesi senza Points Relais. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.

Il test del Web Service non è riuscito dopo il salvataggio: il messaggio mostra l'errore di Mondial Relay, per esempio un codice brand non valido o una chiave di sicurezza non valida. Verifica il codice brand e la chiave privata con Mondial Relay.

L'elenco dei punti è vuoto o non disponibile: il cliente ha bisogno prima di un codice postale di consegna. Se il Web Service non funziona, al suo posto viene offerta la mappa. Attiva Debug log, ricarica il checkout e controlla il campo Log nella pagina dell'estensione per il motivo.

La mappa non si apre: la mappa viene caricata da widget.mondialrelay.com e unpkg.com. Verifica che un blocco della privacy o degli script, oppure una Content Security Policy del tuo negozio, non li blocchino. Se la mappa non può essere caricata, il cliente vede "Non è stato possibile caricare la mappa di Mondial Relay. Riprova più tardi o scegli un altro metodo di spedizione."

La pagina dell'ordine dice No Point Relais was saved for this order: l'ordine è stato effettuato senza un punto del paese di consegna. Il motivo viene scritto nel log. Chiedi al cliente il Point Relais prima di creare la spedizione.

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

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e fai clic su Uninstall (il pulsante rosso −) accanto a VibeFox Mondial Relay. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable/Disable, Sort order, Tax status e Geo zone. Gli elenchi di punti in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, vengono eliminate anche le altre impostazioni e il log di debug. Se è disattivo, vengono conservate e riutilizzate quando reinstalli l'estensione. I punti di ritiro salvati negli ordini vengono sempre conservati, e gli ordini esistenti mantengono il loro metodo di spedizione e il loro costo.

Su OpenCart 4, per rimuovere anche i file dell'estensione, dopo la disinstallazione vai su Extensions > Installer e fai clic su Uninstall (il pulsante arancione −) accanto a VibeFox Mondial Relay nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per eliminare il pacchetto caricato.

Mondial Relay è un marchio del suo rispettivo titolare. Questa estensione non è affiliata né approvata da Mondial Relay.