VibeFox Correos CityPaq for OpenCart — Guida

Requisiti

OpenCart: 3.0.x (testato con 3.0.5.0) oppure 4.0.2 e versioni successive (testato con 4.1.0.3).

PHP: 8.0 o successivo.

Spedizione in Spagna: gli armadietti CityPaq esistono solo in Spagna, quindi il metodo viene offerto solo per gli indirizzi di consegna in Spagna.

Credenziali API di Correos (solo per l'elenco degli armadietti in tempo reale): l'elenco CityPaq di Correos legge gli armadietti attivi dall'API "terminals" di Correos. Nel portale sviluppatori di Correos apri l'API "terminals" e usa Request access per la tua applicazione. Correos approva le richieste dei propri clienti business e invia un client ID e un client secret. Sono visibili anche in My applications nel portale. Se i clienti inseriscono l'armadietto da soli o scelgono dalla tua lista, non ti servono credenziali API.

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_correos_citypaq-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_correos_citypaq.ocmod.zip. Installa solo il pacchetto della 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, clicca su Upload e scegli il file vfd_correos_citypaq-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non devi aggiornare Extensions > Modifications. Invece dell'Installer puoi anche copiare il contenuto della cartella upload di questo pacchetto nella cartella principale del tuo negozio.

2. Vai su Extensions > Extensions, scegli il tipo di estensione Shipping. Trova VibeFox Correos CityPaq e clicca su Install (il pulsante verde +).

3. Clicca su Edit (il pulsante a forma di matita) per aprire la pagina delle impostazioni.

4. Inserisci la tua chiave di licenza VibeFox nel campo License key del riquadro della licenza in cima alla pagina Edit e clicca su Activate (vedi Chiave di licenza).

5. Compila la tabella prezzi, scegli come il cliente seleziona l'armadietto (vedi Configurazione), attiva Enable/Disable e clicca su Save.

OpenCart 4

1. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_correos_citypaq.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 Correos CityPaq, clicca su Install (il pulsante verde +), poi su Edit (il pulsante a forma di 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 in entrambe le versioni.

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

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox Correos CityPaq > Edit. Le sezioni sono elencate a sinistra. Un unico pulsante Save in fondo salva l'intera pagina senza ricaricarla. Prezzi e importi accettano la virgola o il punto decimale. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.

In cima alla pagina compaiono avvisi quando la tabella prezzi non ha una riga per la Spagna né una riga predefinita, quando la selezione dell'armadietto scelta non può funzionare (nessun armadietto nella tua lista, credenziali API mancanti), quale sia stato l'ultimo errore dell'API di Correos, e quando il negozio non ha una classe di peso con unità kg (i pesi dei prodotti vengono allora convertiti in base al nome dell'unità: kg, g, lb od oz; le unità sconosciute vengono lette come kg). Controlla System > Localisation > Weight Classes. Se il nome è vuoto, non valido o supera i 64 caratteri, se un peso o un importo non è un numero valido pari o superiore a 0, se Min weight (kg) è maggiore di Max weight (kg), o se Sort order non è un numero intero, la pagina mostra un errore e non viene salvato nulla. I prezzi non validi nella tabella, le righe duplicate e le righe non valide o duplicate in My lockers vengono segnalati come avvisi, e il resto viene salvato.

Generale

Gli armadietti CityPaq esistono solo in Spagna, quindi il metodo non viene mai offerto per altri paesi.

Enable/Disable: attiva o disattiva la spedizione con Correos CityPaq. Predefinito: disattivato.

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

Tax class: OpenCart aggiunge l'imposta di questa classe ai prezzi della tabella. No tax significa che i prezzi sono definitivi.

Sort order: la posizione del metodo nell'elenco dei metodi di spedizione. Un numero intero.

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

Correos non pubblica un'API tariffaria per CityPaq, quindi il prezzo proviene da questa tabella. Inserisci i prezzi del tuo contratto con Correos nella valuta predefinita del negozio, IVA esclusa.

Price table: una riga per Spain (ES) e/o una riga predefinita * Default. Ogni riga ha un Price base e prezzi facoltativi per le dimensioni 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). Un prezzo di dimensione pari a 0 o vuoto usa il prezzo base. Clicca su Add row per aggiungere una riga e sul pulsante × per rimuoverla. Senza una riga corrispondente il metodo viene nascosto. Se un paese compare due volte, viene usata solo la prima riga.

Calculation type: come viene determinata la dimensione del pacco.

Per order (size by the total cart weight): un prezzo per l'intero carrello, scelto in base al peso totale. È il predefinito.

Per item (size by each item weight, multiplied by quantity): ogni prodotto riceve il prezzo della propria dimensione, moltiplicato per la sua quantità, e i prezzi vengono sommati.

I pesi dei prodotti vengono convertiti in kg dalla classe di peso di ciascun prodotto.

Condizioni

Min weight (kg): nasconde il metodo quando il carrello è più leggero. 0 significa nessun limite.

Max weight (kg): nasconde il metodo quando il carrello è più pesante. Predefinito: 30, perché CityPaq accetta pacchi fino a 30 kg. 0 significa nessun limite.

Minimum order amount: mostra il metodo solo quando il subtotale dei prodotti che richiedono spedizione (dopo il coupon, prima delle tasse) raggiunge questo importo. Lascia il campo vuoto per mostrarlo sempre.

Spedizione gratuita

Free shipping: attiva la spedizione gratuita con CityPaq a partire dall'importo indicato sotto.

Free shipping from: il subtotale dei prodotti che richiedono spedizione (dopo il coupon, prima delle tasse) a partire dal quale questo metodo costa 0. Viene usato solo quando Free shipping è attivo.

Scelta dell'armadietto CityPaq

La sezione contiene un link al localizzatore ufficiale degli armadietti CityPaq di Correos.

Locker selection: come il cliente sceglie l'armadietto prima di effettuare l'ordine. Predefinito: il cliente inserisce l'armadietto.

Customer chooses from the Correos CityPaq list (Correos API, credentials below): il cliente vede gli armadietti CityPaq attivi del CAP dell'indirizzo di consegna e può cercare un altro CAP di 5 cifre. Quando un CAP non ha armadietti, vengono elencati gli armadietti della stessa zona e poi della stessa provincia, prima i CAP più vicini (fino a 50). Se l'elenco non può essere caricato o non trova nulla, il cliente inserisce l'armadietto manualmente.

Customer enters the locker (code or address from the Correos finder): un campo obbligatorio per il codice dell'armadietto (per esempio S0000213D) o l'indirizzo, da 3 a 120 caratteri, con un link alla mappa CityPaq di Correos.

Customer chooses from my list of lockers (below): un menu a tendina obbligatorio con gli armadietti di My lockers. Gli armadietti vicini al CAP del cliente compaiono per primi.

Do not ask for a locker: nessuna domanda sull'armadietto al checkout.

Se scegli l'elenco Correos senza credenziali API, oppure la tua lista mentre My lockers è vuota, al cliente viene chiesto di inserire l'armadietto manualmente.

Elenco CityPaq di Correos (API) (usato solo con l'elenco CityPaq di Correos)

La sezione contiene un link alla pagina dell'API "terminals" nel portale sviluppatori di Correos. Viene letto solo l'elenco degli armadietti. I prezzi provengono sempre dalla tabella prezzi.

API client ID: il client_id della tua applicazione nel portale sviluppatori di Correos.

API client secret: il client_secret della tua applicazione nel portale sviluppatori di Correos.

Dopo il salvataggio entrambi i campi restano vuoti e mostrano Saved - leave empty to keep it. Inserisci un nuovo valore solo per modificarlo. Spunta Remove the saved client ID and client secret e clicca su Save per eliminarli. Se non c'è nulla di salvato, la sezione mostra No credentials saved. Quando cambi le credenziali o la selezione dell'armadietto, vengono cancellati gli elenchi di armadietti in cache e l'ultimo errore API.

Disponibilità

Geo zone: offre il metodo solo per gli indirizzi in questa zona geografica. All zones (predefinito) significa tutti gli indirizzi spagnoli. Le zone geografiche si gestiscono in System > Localisation > Geo Zones.

Ignore geo zone: offre CityPaq per tutti gli indirizzi spagnoli, anche se non rientrano nella zona geografica indicata sopra.

Avanzate

Debug log: scrive righe di debug in storage/logs/vfd_cpq_debug.log.php (su OpenCart 4 system/storage/logs/vfd_cpq_debug.log.php). Il file non può essere letto dal web. Gli errori dell'API di Correos vengono sempre scritti, anche quando questa opzione è disattivata. Credenziali e dati personali non vengono mai registrati.

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

Remove data on uninstall: se attivo, la disinstallazione dell'estensione elimina le impostazioni, gli elenchi in cache e i registri. Gli armadietti salvati negli ordini restano. Se disattivo (predefinito), tutto viene conservato per una nuova installazione.

Importazione / Esportazione

Export: clicca su Download JSON per salvare le impostazioni in un file JSON. Client ID e secret dell'API non vengono inclusi.

Import: incolla un JSON di impostazioni esportato da questa estensione e clicca su Import. I valori vengono verificati come in un normale salvataggio. Le credenziali salvate vengono conservate.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione la tariffa CityPaq. Se è impostata una Geo zone (e Ignore geo zone è disattivato) e l'indirizzo è al di fuori di essa, CityPaq non viene offerto. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri prodotti non aggiungono peso e non sono inclusi nell'importo dell'ordine. L'estensione verifica poi che l'indirizzo di consegna sia in Spagna, il peso del carrello e l'importo minimo dell'ordine, trova la riga di prezzo per la Spagna (o la riga *) e la dimensione del pacco, e restituisce il prezzo. Se si applica la spedizione gratuita, il prezzo è 0. Il prezzo viene calcolato nella valuta predefinita del negozio, arrotondato ai decimali di quella valuta, e mostrato al cliente nella sua valuta con l'imposta della Tax class selezionata. Per il prezzo non viene inviata alcuna richiesta a Correos.

Il riquadro CityPaq locker compare sotto il metodo CityPaq nel passaggio del metodo di spedizione. La scelta viene salvata appena il cliente la effettua. Un armadietto non accettabile viene rifiutato con un messaggio, e resta la scelta precedente. Con l'elenco di Correos, un codice di armadietto viene accettato solo se Correos lo ha offerto per il CAP cercato, e il suo nome e indirizzo vengono presi da Correos. Un cliente può cercare fino a 30 CAP diversi per sessione di checkout. Dopodiché il cliente vede Too many searches. Please enter the CityPaq locker you found on the Correos map.

Il pulsante Continue del passaggio del metodo di spedizione non prosegue con CityPaq senza un armadietto valido. Questo viene verificato lato server. Il cliente vede, per esempio, Please choose the CityPaq locker where you want to collect your parcel. Quando l'ordine viene effettuato, l'armadietto viene salvato nell'ordine.

Su OpenCart 4 il cliente clicca su Choose nel blocco del metodo di spedizione della pagina di checkout e sceglie CityPaq nella finestra Shipping method options. Il riquadro CityPaq locker compare in quella finestra sotto l'opzione CityPaq e funziona come descritto sopra. Il pulsante Continue della finestra non prosegue con CityPaq senza un armadietto valido. OpenCart 4 mantiene un unico ordine per il checkout e lo aggiorna ogni volta che il cliente conferma di nuovo, e l'armadietto dell'ordine viene aggiornato insieme ad esso.

L'elenco di Correos viene richiesto solo quando CityPaq è il metodo selezionato, non mentre il passaggio viene disegnato. Un elenco viene memorizzato nella cache per 12 ore per CAP. Una richiesta non riuscita viene memorizzata per 10 minuti, così il checkout non attende Correos a ogni aggiornamento. Il cliente non vede mai l'errore tecnico, ma solo il messaggio The Correos CityPaq list cannot be loaded right now. e il campo manuale.

L'estensione non ottiene tariffe in tempo reale da Correos, non mostra una mappa, non pre-registra spedizioni, non stampa etichette, non richiede ritiri e non traccia i pacchi. Crea la spedizione nel tuo account Correos usando l'armadietto salvato nell'ordine.

Punti di ritiro

L'armadietto scelto viene aggiunto al metodo di spedizione dell'ordine, per esempio Correos CityPaq - CityPaq locker: .... Così il cliente lo vede nello storico ordini del proprio account e nelle email di ordine, ed è stampato sulla fattura e mostrato in Sales > Orders. La pagina di conferma ordine di OpenCart non mostra il metodo di spedizione.

Nella pagina dell'ordine nell'amministrazione, il riquadro CityPaq locker sopra lo storico mostra l'armadietto e il suo Locker code: quando è stato scelto da un elenco. Per cambiarlo, usa il campo Change CityPaq locker e clicca su Save: con la tua lista, scegli un altro armadietto dal menu a tendina; con l'elenco di Correos, inserisci un codice di armadietto (viene cercato presso Correos) o un indirizzo; negli altri casi, inserisci un nuovo codice o indirizzo. Lascia il campo vuoto, oppure lascia -- Keep the current locker --, per mantenere l'armadietto attuale. Ogni modifica aggiorna anche il testo del metodo di spedizione dell'ordine e aggiunge una voce allo storico CityPaq locker changed to: ... senza notificare il cliente. Per cambiare l'armadietto serve il permesso di modifica degli ordini (sale/order). Non serve l'accesso alle impostazioni dell'estensione. Il riquadro viene mostrato per gli ordini CityPaq anche quando l'estensione è disattivata.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il riquadro della licenza License — VibeFox Correos CityPaq è il primo riquadro in Extensions > Extensions > Shipping > VibeFox Correos CityPaq > Edit, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopodiché il riquadro 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 controllare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuovere la chiave da questo negozio. Sotto di essi ci sono la riga Product: opencart-shipping-correos-citypaq 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 modificare la chiave. I testi del riquadro seguono la lingua del pannello di amministrazione (sono incluse le lingue inglese e russo).

Se la chiave non viene accettata, il riquadro spiega il motivo, per 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 che hai liberato un posto per il 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 posto del dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, il metodo di spedizione Correos CityPaq non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Un utente amministratore che è collegato al pannello di 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 il login al pannello di amministrazione, quindi senza una chiave attiva il metodo è nascosto a tutti. Dopo che hai aperto la pagina Edit una volta, 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 supporto richiedono il rinnovo. Lo stato viene verificato 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

Correos CityPaq non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che l'indirizzo di consegna sia in Spagna. Controlla Geo zone (o attiva Ignore geo zone). Verifica che la tabella prezzi abbia una riga per la Spagna o una riga *, che il carrello rientri nei limiti di peso e di Minimum order amount, e che i prodotti abbiano Requires Shipping impostato su Yes.

Il cliente deve digitare l'armadietto anche se è selezionato l'elenco di Correos: verifica che API client ID e API client secret siano salvati e guarda l'avviso in cima alla pagina delle impostazioni. Mostra l'ultimo errore dell'API di Correos. HTTP 401/403 significa che Correos ha rifiutato le credenziali: controllale e verifica che la tua applicazione abbia accesso all'API "terminals". Dopo un errore, il tentativo successivo viene fatto dopo 10 minuti.

Nessun armadietto per un CAP: Correos non ha trovato armadietti attivi per quel CAP, la sua zona o la sua provincia. Il cliente può cercare un altro CAP oppure inserire l'armadietto trovato sulla mappa CityPaq di Correos.

Il menu a tendina di my lockers non compare: My lockers è vuoto oppure le sue righe non sono valide. Ogni riga richiede almeno CODE | Name.

Dove i clienti trovano il codice dell'armadietto: sulla mappa CityPaq di Correos collegata sotto il campo dell'armadietto.

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

Per gli sviluppatori: l'armadietto di una sessione di checkout e quello di un ordine sono memorizzati nella tabella vfd_cpq_locker (con il prefisso del tuo database). L'indirizzo dell'API di Correos può essere sostituito con l'impostazione vfd_cpq_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 Correos CityPaq. 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. Gli elenchi di armadietti Correos in cache e l'ultimo errore API vengono sempre rimossi. Se Remove data on uninstall è attivo, vengono eliminati anche impostazioni, registro e armadietti delle sessioni di checkout senza ordine. Se è disattivo, le altre impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. Gli armadietti salvati negli ordini non vengono mai eliminati, e gli ordini esistenti mantengono il loro metodo e costo di spedizione.

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

Correos e CityPaq sono marchi dei rispettivi titolari. Questa estensione non è affiliata né approvata da Correos.