VibeFox Correos CityPaq for WooCommerce — Guida

Requisiti

WordPress: 5.8 o successivo.

WooCommerce: 7.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.

PHP: 8.0 o successivo.

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

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

Installazione

1. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e fai clic su Install Now. Puoi anche caricare la cartella vfd_correos_citypaq in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox Correos CityPaq, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugins.

4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.

5. Compila la tabella prezzi e scegli come il cliente seleziona l'armadietto (vedi Configurazione).

6. Aggiungi VibeFox Correos CityPaq alla zona di spedizione per la Spagna in WooCommerce > Settings > Shipping > Shipping zones, oppure attiva Ignore shipping zones.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox Correos CityPaq. Valgono per tutte le zone di spedizione. Quando aggiungi il metodo a una zona, la finestra della zona ha un solo campo:

Title (zone): il nome di questa opzione al checkout per questa zona. Lascialo vuoto per usare il Name globale.

Gli avvisi sopra le impostazioni ti indicano quando la tabella prezzi non ha righe utilizzabili, quando la selezione dell'armadietto scelta non può funzionare (nessun armadietto nel tuo elenco, nessuna credenziale API) e qual è stato l'ultimo errore dell'API Correos. Prezzi e importi accettano la virgola o il punto decimale.

Generale

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

Enable/Disable: attiva o disattiva il metodo in tutte le zone contemporaneamente.

Name: il nome del metodo di spedizione mostrato al cliente al checkout. Predefinito: Correos CityPaq.

Tax status: Taxable aggiunge l'imposta di WooCommerce ai prezzi della tabella, None non la aggiunge.

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

Price table: una riga per Spain (ES) e/o una riga predefinita *. 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 per dimensione pari a 0 o vuoto usa il prezzo base. Fai clic su + Add row per aggiungere una riga e sulla croce per rimuoverne una. Inserisci le tariffe del tuo contratto Correos nella valuta del negozio. Senza una riga corrispondente il metodo viene nascosto. Prezzi non validi e righe duplicate vengono segnalati al salvataggio.

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 (kg, g, lbs o oz).

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 del carrello (dopo sconti, prima delle tasse) raggiunge questo importo. Lascia vuoto per mostrarlo sempre.

Excluded shipping classes: nasconde il metodo quando il carrello contiene un prodotto di una di queste classi di spedizione di WooCommerce, ad esempio articoli ingombranti che non entrano in un armadietto. Il plugin non verifica le dimensioni dei pacchi.

Spedizione gratuita

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

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

Selezione dell'armadietto CityPaq

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 spedizione e può cercare un altro codice postale di 5 cifre. Quando un codice postale non ha armadietti, vengono elencati quelli della stessa area, poi della stessa provincia, con i codici postali più vicini per primi. 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 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, con un link al localizzatore ufficiale 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, al cliente viene chiesto di inserire l'armadietto manualmente.

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. Le righe non valide e duplicate vengono segnalate al salvataggio.

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

La sezione contiene un link alla pagina dell'API "terminals" del 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 sul portale sviluppatori di Correos.

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

Quando cambi le credenziali o la selezione dell'armadietto, gli elenchi degli armadietti in cache vengono cancellati.

Disponibilità senza zone di spedizione

Ignore shipping zones: offre CityPaq per ogni indirizzo spagnolo, anche se nessuna zona di spedizione contiene questo metodo. Disattivato (consigliato) significa che il metodo viene offerto dove lo hai aggiunto a una zona di spedizione.

Avanzate

Debug log: scrive righe di debug in WooCommerce > Status > Logs, origine vfd-correos-citypaq. Gli errori dell'API Correos vengono sempre registrati, anche quando questa opzione è disattivata. Credenziali e dati personali non vengono mai registrati.

Remove data on uninstall: se attiva, eliminare il plugin rimuove le sue impostazioni e i metodi delle zone. Disattivare il plugin non elimina mai nulla. Gli armadietti salvati negli ordini restano.

Come funziona al checkout

Quando il cliente inserisce un indirizzo di consegna in Spagna, WooCommerce chiede al plugin una tariffa. Il plugin verifica il peso del carrello, l'importo minimo dell'ordine e le classi di spedizione escluse, trova la riga prezzi per la Spagna (o la riga *) e la dimensione del pacco, e mostra il prezzo. Se si applica la spedizione gratuita, il prezzo è 0.

Quando il cliente seleziona CityPaq, il campo dell'armadietto compare sotto il metodo. L'ordine non può essere effettuato senza un armadietto valido. Questo viene verificato anche sul server, incluso per gli ordini effettuati con i blocchi Carrello e Checkout. Con l'elenco Correos, un codice armadietto viene accettato solo se Correos lo ha offerto a questo cliente, e nome e indirizzo vengono presi da Correos. Il numero di ricerche per codice postale per sessione cliente è limitato. Quando si raggiunge il limite, il cliente inserisce l'armadietto manualmente.

Un elenco Correos 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 metodo funziona con il checkout classico e con i blocchi Carrello e Checkout. È compatibile con WooCommerce High-Performance Order Storage (HPOS).

Il plugin 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. Viene mostrato nella gestione ordini sotto l'indirizzo di spedizione, nella pagina di conferma dell'ordine, in My account > Orders e in tutte le e-mail degli ordini (HTML e testo semplice) come CityPaq locker.

Nella gestione ordini puoi cambiare l'armadietto nel campo Change CityPaq locker: scegline un altro dal tuo elenco oppure inserisci un nuovo codice o indirizzo. Con l'elenco Correos, un codice armadietto digitato viene verificato presso Correos. Lascia il campo vuoto per mantenere l'armadietto attuale. Ogni modifica aggiunge una nota all'ordine.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Shipping > VibeFox Correos CityPaq. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, ad esempio la data fino alla quale la licenza è attiva, e il tuo dominio. Usa Check now per verificare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuoverla da questo sito. Il link Manage licenses and domains in your account apre il tuo account vibefox.net.

Una chiave funziona su un solo dominio. Rimuovere la chiave da un sito non libera lo slot del dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, Correos CityPaq non viene mostrato ai clienti al checkout. Gli store manager connessi lo vedono comunque, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugins e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene ricontrollato automaticamente in background.

Risoluzione dei problemi

Correos CityPaq non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che l'indirizzo sia in Spagna e che il metodo sia aggiunto alla zona di spedizione corrispondente (o che Ignore shipping zones sia attivo). Controlla che la tabella prezzi abbia una riga per la Spagna o una riga *, e che il carrello rientri nei limiti di peso, Minimum order amount ed Excluded shipping classes.

I clienti devono digitare l'armadietto anche se è selezionato l'elenco Correos: verifica che API client ID e API client secret siano compilati e guarda l'avviso sopra le impostazioni. Mostra l'ultimo errore dell'API 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 effettuato dopo 10 minuti.

Nessun armadietto per un codice postale: Correos non ha trovato armadietti attivi per quel codice postale, la sua area o la sua provincia. Il cliente può cercare un altro codice postale oppure 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.

Note per sviluppatori: l'armadietto viene salvato nei meta dell'ordine _vfd_cpq_locker (testo mostrato ovunque) e _vfd_cpq_locker_id (codice armadietto, quando scelto dall'elenco Correos o dal tuo elenco). Il plugin usa l'API di produzione "terminals" di Correos. Per questa API non è documentata alcuna sandbox.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Ad esempio, se la chiave è già usata su un altro dominio, libera uno slot nel tuo account vibefox.net e fai clic su Check now. Se l'indirizzo del sito è cambiato, fai clic su Check now per attivare la chiave per il nuovo dominio. Se il server delle licenze non è raggiungibile, il plugin continua a funzionare con l'ultimo stato noto.

Disinstallazione

Disattivare il plugin conserva tutti i dati. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato di licenza di questo plugin vengono sempre rimossi, così come gli elenchi di armadietti Correos in cache e l'ultimo errore API. Impostazioni e metodi di zona vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano per una futura reinstallazione. Gli armadietti salvati negli ordini non vengono mai eliminati, e gli ordini esistenti mantengono le loro righe di spedizione.

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