VibeFox Correos CityPaq for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni precedenti di PHP.

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

Credenziali API Correos (solo per l'elenco live degli armadietti): l'elenco degli armadietti CityPaq di Correos legge gli armadietti attivi dall'API Correos "terminals". 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 mostrati anche in My applications sul portale. Se i clienti inseriscono l'armadietto da soli o scelgono dal tuo elenco, non ti servono credenziali API.

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un solo dominio.

Installazione

1. Nel back office vai su Modules > Module Manager e clicca su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento clicca su Configure, oppure cerca più tardi VibeFox Correos CityPaq nell'elenco dei moduli e clicca su Configure.

3. Inserisci la tua chiave di licenza VibeFox in License key nel blocco licenza in alto nella pagina Configure e clicca su Activate (vedi Chiave di licenza).

4. Compila la tabella prezzi, scegli come il cliente seleziona l'armadietto (vedi Configurazione) e clicca su Save.

All'installazione il modulo crea il corriere Correos CityPaq con il testo dei tempi di consegna Delivery to a Correos CityPaq parcel locker. Il corriere è assegnato a tutti i gruppi di clienti e alla zona Spagna. Puoi modificare zone, gruppi di clienti, tempi di consegna, logo e limiti di dimensione in Shipping > Carriers. Non impostare lì i prezzi: il prezzo proviene sempre dal modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Correos CityPaq > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Prezzi e importi accettano una virgola o un punto decimale.

Gli avvisi sopra le impostazioni ti segnalano quando il corriere non viene trovato, 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 nel tuo elenco, nessuna credenziale API), qual è stato l'ultimo errore API di Correos, e quando l'unità di peso del tuo negozio non è riconosciuta dal modulo (i pesi dei prodotti vengono allora letti come kg; imposta kg, g, lb o oz in International > Localization). Se il nome è vuoto, non valido o più lungo di 64 caratteri, se un peso o un importo non è un numero valido pari o superiore a 0, oppure se Min weight (kg) è maggiore di Max weight (kg), la pagina mostra un errore e non viene salvato nulla. I prezzi non validi nella tabella prezzi 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 corriere non viene mai offerto per altri paesi.

Enable/Disable: attiva o disattiva la spedizione Correos CityPaq. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.

Name: il nome del metodo di spedizione mostrato al cliente al checkout. È anche il nome del corriere. Predefinito: Correos CityPaq. Obbligatorio, massimo 64 caratteri.

Tax: la regola fiscale del corriere. PrestaShop aggiunge questa imposta sui prezzi della tabella. No tax significa che i prezzi sono definitivi.

Prezzi (il titolo della sezione mostra la valuta predefinita del 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, al netto delle imposte.

Price table: una riga per Spain (ES) e/o una riga predefinita * Default. Ogni riga ha un Price base e prezzi opzionali per le dimensioni dei pacchi 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 sull'icona del cestino per rimuoverne una. Senza una riga corrispondente il corriere 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. È l'impostazione predefinita.

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 dall'unità di peso del tuo negozio (per esempio kg, g, lb o oz).

Condizioni

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

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

Minimum order amount: mostra il corriere solo quando il subtotale del carrello (prodotti che richiedono spedizione, dopo gli sconti, prima delle imposte) raggiunge questo importo. Lascia vuoto per mostrarlo sempre.

Spedizione gratuita

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

Free shipping from: il subtotale del carrello (dopo gli sconti, prima delle imposte) da cui questo corriere costa 0. Usato solo quando Free shipping è attivo.

Selezione 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 codice postale dell'indirizzo di consegna e può cercarne un altro di 5 cifre. Quando un codice postale non ha armadietti, vengono elencati prima quelli della stessa zona, poi quelli della stessa provincia, con i codici postali più vicini per primi (fino a 50). Ogni armadietto mostra nome, indirizzo, codice postale, città e orari di apertura. Se l'elenco non può essere caricato o non trova nulla, il cliente inserisce l'armadietto al suo posto.

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 al localizzatore 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 codice postale 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 il tuo elenco mentre My lockers è vuoto, ai clienti viene chiesto di inserire l'armadietto.

My lockers: usato quando Locker selection è impostato sul tuo elenco. Un armadietto per riga: CODE | Name | Address | Postal code | City. Codice e nome sono obbligatori. Se un codice è indicato due volte, viene usata solo la prima riga.

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

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 cambiarlo. Seleziona Remove the saved client ID and client secret e clicca su Save per eliminarli. Quando non c'è nulla di salvato, la sezione mostra No credentials saved. Quando cambi le credenziali o la selezione dell'armadietto, gli elenchi di armadietti in cache vengono cancellati.

Disponibilità senza zone di spedizione

Ignore shipping zones: offre CityPaq per ogni indirizzo spagnolo, anche se la zona dell'indirizzo non è collegata al corriere. Quando è attivo, il corriere viene collegato a tutte le zone attive, comprese quelle create in seguito. Quando lo disattivi di nuovo, il corriere riprende le zone che aveva prima. Disattivato (consigliato) significa che si usano le zone impostate in Shipping > Carriers.

Avanzate

Debug log: scrive le righe di debug in logs/vfd_cpq_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori 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: quando attivo, disinstallando il modulo vengono eliminati impostazioni, corriere, elenchi in cache e registri. Gli armadietti salvati negli ordini vengono conservati. Quando disattivo, tutto viene conservato per una reinstallazione.

Come funziona al checkout

Nel passaggio di spedizione PrestaShop chiede al modulo il prezzo di CityPaq. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nell'importo dell'ordine. Il modulo verifica 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 e poi mostrato nella valuta del carrello del cliente. L'imposta viene aggiunta dalla regola fiscale del corriere.

Quando il cliente seleziona CityPaq, sotto il corriere compare il riquadro CityPaq locker. La scelta viene salvata nel carrello non appena il cliente la effettua. Un armadietto non accettabile viene rifiutato con un messaggio, e la scelta precedente resta valida. Con l'elenco Correos, un codice di armadietto viene accettato solo se Correos lo ha proposto per il codice postale cercato, e nome e indirizzo vengono presi da Correos. Un cliente può cercare fino a 30 codici postali diversi per carrello. Dopo di che vede Troppe ricerche. Inserisci l'armadietto CityPaq che hai trovato sulla mappa Correos.

Il pulsante Continue del passaggio di spedizione non procede senza un armadietto valido. Anche questo è verificato sul server. Il cliente vede, per esempio, Scegli l'armadietto CityPaq in cui vuoi ritirare il tuo pacco. Quando l'ordine viene effettuato, l'armadietto del carrello viene salvato nell'ordine.

L'elenco Correos viene richiesto solo quando il cliente seleziona CityPaq, non per ogni visitatore del passaggio di spedizione. Un elenco viene memorizzato nella cache per 12 ore per codice postale. Una richiesta non riuscita viene memorizzata nella cache per 10 minuti, così il checkout non attende Correos a ogni aggiornamento. Il timeout dell'API è di 12 secondi. Il cliente non vede mai l'errore tecnico, solo un breve messaggio e il campo manuale. Il riquadro dell'armadietto funziona con i temi Classic e Hummingbird.

Il modulo 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 salvato nell'ordine. Il cliente lo vede come CityPaq locker: nella pagina di conferma dell'ordine e nella pagina dei dettagli dell'ordine nel suo account. Nell'e-mail di conferma dell'ordine e nell'e-mail di nuovo ordine del modulo Mail alerts, l'armadietto viene aggiunto alla riga del corriere, per esempio Correos CityPaq - CityPaq locker: ....

Nella pagina ordine dell'amministrazione, il blocco CityPaq locker mostra l'armadietto e il suo Locker code: quando è stato scelto da un elenco. Per modificarlo, usa il campo Change CityPaq locker e clicca su Save: con il tuo elenco, scegli un altro armadietto dal menu a tendina; con l'elenco 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 per mantenere l'armadietto attuale. Ogni modifica aggiunge un messaggio privato all'ordine: Armadietto CityPaq modificato in: .... Cambiare l'armadietto richiede il permesso di modificare gli ordini. Non serve l'accesso alle pagine Modules.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza License — VibeFox Correos CityPaq è il primo blocco di Modules > Module Manager > VibeFox Correos CityPaq > Configure, 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 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: presta-shipping-correos-citypaq e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo i dipendenti con il permesso Configure per il modulo possono modificare la chiave. I testi del blocco seguono la lingua del back office (sono inclusi inglese e russo).

Se la chiave non viene accettata, il blocco indica il motivo, ad esempio Key not found, This key belongs to another product, Domain limit reached o License expired on seguito da una data. Dopo un cambio dell'indirizzo del negozio, o dopo aver liberato uno slot di dominio nel tuo account, clicca su Check now. Se il server delle licenze non è raggiungibile, il modulo continua a funzionare con l'ultimo stato noto.

Una chiave funziona su un dominio: quello del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, il corriere Correos CityPaq non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Lo storefront di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il corriere è nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non testarlo al checkout. Un promemoria compare in Modules > Module Manager, nella scheda Alerts. Gli ordini esistenti non sono interessati.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene controllato di nuovo automaticamente mentre lavori nel back office: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve alcuna attività cron. Disinstallare o reimpostare il modulo 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. In Shipping > Carriers verifica che il corriere copra la zona Spagna e il gruppo del cliente (oppure attiva Ignore shipping zones). Verifica che la tabella prezzi abbia una riga per la Spagna o una riga *, e che il carrello rientri nei limiti di peso e di Minimum order amount. Inoltre, i prodotti possono essere limitati a determinati corrieri nella pagina del prodotto.

I clienti devono digitare l'armadietto anche se è selezionato l'elenco Correos: verifica che API client ID e API client secret siano salvati e leggi l'avviso sopra le impostazioni. Mostra l'ultimo errore 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 codice postale: Correos non ha trovato armadietti attivi per quel codice postale, la sua zona o la sua provincia. Il cliente può cercare un altro codice postale o inserire l'armadietto trovato sul localizzatore CityPaq di Correos.

Il menu a tendina dei miei armadietti 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: sul localizzatore CityPaq di Correos, collegato sotto il campo dell'armadietto.

La pagina dice che il corriere non è stato trovato, o che il corriere non può essere aggiornato: il corriere è stato eliminato in Shipping > Carriers. Ripristina il modulo in Modules > Module Manager per ricrearlo. Il ripristino mantiene le impostazioni e lo stato del corriere.

Note per sviluppatori: l'armadietto di un carrello e di un ordine viene salvato nella tabella vfd_cpq_locker (con il prefisso del tuo database). Il modulo usa l'API di produzione "terminals" di Correos.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Correos CityPaq e scegli Uninstall. La chiave di licenza, lo stato della licenza, gli elenchi di armadietti Correos in cache e l'ultimo errore API vengono sempre rimossi. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini conservano la loro cronologia), e vengono rimosse le impostazioni, il registro e gli armadietti dei carrelli senza ordine. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni vengono conservate. Reinstallare il modulo ripristina lo stato del corriere che aveva prima. Gli armadietti salvati negli ordini non vengono mai eliminati.

Correos e CityPaq sono marchi dei rispettivi proprietari. Questo modulo non è affiliato né approvato da Correos.