VibeFox PostNL 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.

Chiave API PostNL (solo per i punti di ritiro): i punti di ritiro vengono caricati dalla PostNL Checkout API. I clienti business di PostNL trovano la chiave API in Mijn PostNL alla voce My account > API beheren. La sandbox di PostNL richiede una chiave sandbox separata. I metodi con consegna a domicilio non richiedono una chiave.

Chiave di licenza VibeFox: si acquista 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_postnl in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

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

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

5. Compila i prezzi. Per i punti di ritiro inserisci anche la API key PostNL e il Ship from (postcode) (vedi Configurazione).

6. Aggiungi VibeFox PostNL a una zona di spedizione in WooCommerce > Settings > Shipping > Shipping zones, per esempio Paesi Bassi e Belgio. Nella zona imposta il Title e il Delivery to. Aggiungi il metodo una seconda volta per l'altro tipo di consegna.

Configurazione

Tutte le impostazioni, tranne il titolo e il tipo di consegna, si trovano in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox PostNL. Valgono per tutte le zone di spedizione. Quando aggiungi il metodo a una zona, la finestra della zona ha due campi:

Title (zone): il nome che il cliente vede per questo metodo di zona. Lascialo vuoto per usare il Name globale.

Delivery to (zone): As in the global settings (predefinito), PostNL pickup point (customer chooses a point) oppure Home address. Aggiungi il metodo due volte a una zona per offrirli entrambi.

Sopra le impostazioni la pagina mostra degli avvisi: chiave API o codice postale di spedizione mancanti per i punti di ritiro, sandbox attiva, nessun prezzo impostato e l'ultima richiesta a PostNL non riuscita, con data ed errore.

Generale

Enable/Disable: attiva o disattiva la consegna PostNL in tutte le zone contemporaneamente.

Name: il nome del metodo di spedizione mostrato al checkout. Un Title impostato nella zona lo sostituisce. Predefinito: PostNL.

Delivery to: il tipo di consegna predefinito per i metodi di zona che usano As in the global settings, e per la modalità Ignore zones.

Tax status: Taxable aggiunge l'imposta WooCommerce al costo di spedizione, None non la aggiunge.

API PostNL (punti di ritiro) (non necessaria per la consegna a domicilio)

API key: la tua chiave API PostNL da Mijn PostNL (My account > API beheren). Viene inviata a PostNL nell'intestazione "apikey", memorizzata nel database di WordPress e mai mostrata ai clienti né scritta nel registro.

Sandbox: usa la sandbox di PostNL (api-sandbox.postnl.nl) con una chiave API sandbox. I clienti vedranno allora punti di ritiro di prova. Tienila disattivata su un negozio attivo.

Ship from (country): il paese da cui consegni i pacchi a PostNL, Paesi Bassi o Belgio. Per impostazione predefinita è il paese del tuo negozio. PostNL usa l'indirizzo del mittente per la data di ritiro.

Ship from (postcode): il codice postale del mittente, per esempio 1234AB nei Paesi Bassi o 1000 in Belgio. Lascialo vuoto per usare il codice postale del negozio da WooCommerce > Settings > General quando il negozio si trova nello stesso paese. Un codice postale non valido viene rifiutato con un messaggio. Quando modifichi la chiave API, l'impostazione della sandbox o l'indirizzo di spedizione, gli elenchi dei punti di ritiro in cache vengono cancellati.

Prezzi (nella valuta del negozio)

PostNL non offre un'API pubblica per le tariffe, quindi il plugin non richiede tariffe in tempo reale e non converte mai i prezzi.

Price per country: una riga per ogni paese di destinazione. Fai clic su + Add country per aggiungere una riga e sulla croce per eliminarne una. Scegli * All other countries per una riga che copre tutti i paesi senza una riga propria. Ogni riga ha un Price e classi di peso facoltative in base al peso del carrello: 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 classe di peso sostituisce Price; lascialo vuoto per usare Price. Un Price pari a 0 significa spedizione gratuita. Sono accettati sia "6.95" sia "6,95". Le righe vuote e i codici paese non validi vengono rimossi al salvataggio. Se un paese compare due volte, viene mantenuta la prima riga. I prezzi non validi vengono ignorati con un messaggio.

Calculation: Per order addebita il prezzo una sola volta. Per item (price x quantity) lo moltiplica per il numero di articoli spedibili nel carrello.

Price for other countries: usato quando la tabella non contiene né il paese né una riga *. Lascialo vuoto per nascondere il metodo in quel caso.

Condizioni

Free shipping from: il subtotale del carrello da cui la consegna è gratuita. Si applica solo dove viene trovato un prezzo. Lascialo vuoto per non offrire mai la spedizione gratuita.

Minimum subtotal: mostra il metodo solo quando il subtotale del carrello è almeno questo importo. Lascialo vuoto per mostrarlo sempre.

Minimum weight (kg): nasconde il metodo quando il carrello pesa meno. I pesi dei prodotti vengono convertiti dall'unità del tuo negozio. Lascialo vuoto per nessun limite.

Maximum weight (kg): nasconde il metodo per i carrelli più pesanti. Predefinito: 30 (i pacchi PostNL arrivano fino a 30 kg nel Benelux). Lascialo vuoto per nessun limite.

Hide for shipping classes: nasconde il metodo quando il carrello contiene un prodotto di una di queste classi di spedizione di WooCommerce.

Tutti gli importi e i pesi accettano la virgola decimale, anche con il separatore delle migliaia (1.234,50 o 1,234.50). Un numero non valido viene ignorato con un messaggio.

Disponibilità senza zone di spedizione

Ignore zones: offre PostNL anche nei paesi indicati sotto quando nessuna zona lo aggiunge. Le zone che contengono il metodo continuano a funzionare come di consueto. Questa modalità usa il Name e il Delivery to globali.

Countries: i paesi di destinazione per questa modalità. Lascialo vuoto per usare tutti i paesi verso cui il negozio spedisce. Questo campo viene usato solo quando Ignore zones è attivo.

Avanzate

Debug log: scrive i messaggi di debug in WooCommerce > Status > Logs (origine "vfd-postnl"). Gli errori API vengono sempre registrati. Non viene scritta alcuna chiave API né alcun dato del cliente. Disattiva il registro quando hai finito.

Remove data on uninstall: se attivo, eliminare il plugin rimuove le impostazioni PostNL e i metodi di zona. Disattivare il plugin non elimina mai le impostazioni. I punti di ritiro salvati negli ordini vengono sempre conservati.

Come funziona al checkout

Quando il cliente inserisce un indirizzo di consegna, WooCommerce chiede al plugin una tariffa. Il plugin verifica le condizioni: peso del carrello, subtotale minimo e classi di spedizione. Poi prende il prezzo dalla tabella per il paese e la classe di peso, oppure il prezzo per gli altri paesi. Se non c'è un prezzo, il metodo viene nascosto. Se il subtotale del carrello raggiunge Free shipping from, il prezzo è 0.

Un metodo con punto di ritiro viene offerto solo per indirizzi nei Paesi Bassi e in Belgio e solo con una chiave API. Non appena il cliente inserisce un codice postale valido, il plugin chiede alla PostNL Checkout API i punti di ritiro più vicini. Invia il codice postale, la via, il numero civico, la città e il paese del cliente, oltre all'indirizzo di spedizione del tuo negozio. Per i metodi con consegna a domicilio non viene inviato nulla. Se PostNL non è raggiungibile o non restituisce punti per l'indirizzo, il metodo con punto di ritiro viene nascosto e gli altri metodi restano disponibili. Il timeout dell'API è di 12 secondi.

Gli elenchi dei punti vengono memorizzati nella cache per 6 ore per codice postale, e le risposte "nessun punto" per 1 ora. Le richieste non riuscite vengono memorizzate nella cache per 10 minuti, così che un'interruzione non rallenti ogni aggiornamento del checkout. L'ultimo errore viene mostrato nella schermata delle impostazioni.

Il metodo funziona nel checkout classico e nei blocchi Carrello e Checkout. È compatibile con l'archiviazione ad alte prestazioni degli ordini di WooCommerce (HPOS).

Il plugin non richiede tariffe PostNL in tempo reale e non crea etichette di spedizione, codici a barre, track and trace, resi o pre-avvisi. Non ha opzioni di giorno di consegna, consegna serale o mattutina. Crea la spedizione in Mijn PostNL o in un altro strumento PostNL usando il punto di ritiro salvato.

Punti di ritiro

Quando il cliente seleziona un metodo con punto di ritiro, sotto appare un elenco PostNL pickup point con i tre punti più vicini: nome dell'azienda, indirizzo e distanza. Prima che il cliente inserisca un codice postale, vede il messaggio "Inserisci il tuo codice postale (per esempio 1234 AB) per vedere i punti di ritiro PostNL." (4 cifre per il Belgio). La scelta viene ricordata quando il checkout si aggiorna.

Il punto è obbligatorio. Senza un punto, il checkout si blocca con il messaggio "Scegli un punto di ritiro PostNL." Il server controlla il punto con l'elenco di PostNL per l'indirizzo di spedizione. Se non è nell'elenco, il checkout si blocca con il messaggio "Il punto di ritiro PostNL scelto non è disponibile per questo indirizzo. Sceglilo di nuovo." Il nome e l'indirizzo salvati con l'ordine provengono da PostNL, non dal browser.

Schermata dell'ordine nell'amministrazione: PostNL pickup point con il nome, l'indirizzo e il Location code, sotto l'indirizzo di spedizione.

Pagina di ringraziamento e vista dell'ordine in Il mio account: PostNL pickup point con il nome e l'indirizzo.

E-mail degli ordini: il nome e l'indirizzo del punto nelle e-mail HTML e in testo semplice.

Nel database il punto viene salvato nei metadati dell'ordine _vfd_ptnl_servicepoint_id (codice di localizzazione PostNL), _vfd_ptnl_servicepoint_name (nome e indirizzo) e _vfd_ptnl_servicepoint (ID partner, azienda, via, numero civico, codice postale, città, paese).

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza si trova in cima a WooCommerce > Settings > Shipping > VibeFox PostNL. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, per esempio la data fino alla quale la licenza è attiva, e il tuo dominio. Usa Check now per controllare 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 il suo slot di dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, PostNL non viene mostrato ai clienti al checkout. Gli amministratori del negozio connessi lo vedono ancora, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugin 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 controllato di nuovo automaticamente in background.

Risoluzione dei problemi

PostNL non compare al checkout: controlla che la licenza sia attiva, che Enable/Disable sia attivo e che il metodo sia aggiunto alla zona del paese del cliente (oppure che Ignore zones sia attivo e il paese sia consentito). Verifica che sia impostato un prezzo per il paese, i limiti di peso, Minimum subtotal e Hide for shipping classes.

Il metodo con punto di ritiro non compare: viene mostrato solo per indirizzi olandesi e belgi, solo con una chiave API, un codice postale di spedizione e un prezzo, e solo quando PostNL restituisce punti per il codice postale del cliente. Controlla gli avvisi in cima alla schermata delle impostazioni e WooCommerce > Status > Logs, origine "vfd-postnl". Gli errori vengono sempre registrati; attiva Debug log per i dettagli.

"I punti di ritiro PostNL non possono essere caricati al momento": PostNL non è raggiungibile, ha rifiutato la chiave API oppure manca il codice postale di spedizione. La schermata delle impostazioni mostra l'ultimo errore. Una chiave sandbox funziona solo con Sandbox attivo, una chiave live solo con l'opzione disattivata.

I clienti vedono punti di ritiro di prova: disattiva Sandbox.

Filtri per sviluppatori: vfd_ptnl_number_of_locations (predefinito 3), vfd_ptnl_checkout_request (corpo della richiesta) e vfd_ptnl_api_url.

Il blocco della licenza mostra un errore: segui il messaggio nel blocco. Per 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 mantiene tutte le impostazioni e cancella solo gli elenchi dei punti di ritiro in cache. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugin. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi, insieme agli elenchi dei punti in cache e all'ultimo errore API. Le impostazioni e i metodi di zona vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano per una reinstallazione successiva. Gli ordini esistenti conservano le loro righe di spedizione e il punto di ritiro salvato.

PostNL è un marchio del rispettivo titolare. Questo plugin non è affiliato né approvato da PostNL.