VibeFox PostNL for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x, tema Classic o Hummingbird (o un tema basato su di essi).

PHP: 8.0 o successivo. Il modulo rifiuta di installarsi su versioni di PHP più vecchie.

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 PostNL richiede una chiave sandbox separata. Il corriere per la consegna a domicilio non richiede una chiave.

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 trova più tardi VibeFox PostNL nell'elenco dei moduli e clicca su Configure.

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

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

Al momento dell'installazione il modulo crea due corrieri: PostNL pickup point con il testo dei tempi di consegna Delivery to a PostNL pickup point, e PostNL con PostNL delivery to the home address. Entrambi sono collegati alle zone dei Paesi Bassi e del Belgio e a tutti i gruppi di clienti. Puoi aggiungere zone e modificare 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 PostNL > Configure. Ogni sezione ha un proprio pulsante Save, che salva l'intera pagina. In WooCommerce un metodo viene aggiunto due volte a una zona, una per tipo di consegna. In PrestaShop ogni tipo di consegna è un corriere a sé, con il proprio nome, stato e zone.

Sopra le impostazioni la pagina mostra avvisi: chiave API o CAP di spedizione mancanti per i punti di ritiro, sandbox attiva, nessun prezzo impostato, l'ultima richiesta PostNL fallita con data ed errore, un'unità di peso del negozio che il modulo non riconosce e un corriere eliminato.

Generale

PostNL pickup point: attiva o disattiva il corriere con punto di ritiro. Il cliente deve scegliere un punto PostNL al checkout. Viene offerto solo per indirizzi nei Paesi Bassi e in Belgio e solo con una chiave API. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.

Pickup point carrier name: il nome che il cliente vede al checkout. Predefinito: PostNL pickup point. Obbligatorio.

PostNL home address: attiva o disattiva il corriere per la consegna a domicilio. Non viene scelto alcun punto. Funziona per ogni paese con un prezzo. Stesso interruttore dello stato del corriere.

Home delivery carrier name: il nome che il cliente vede al checkout. Predefinito: PostNL. Obbligatorio.

Tax status: la regola fiscale di entrambi i corrieri. Una regola Taxable aggiunge ai prezzi l'imposta sulla spedizione di quella regola. None significa che i prezzi sono definitivi.

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

API key: la tua chiave API PostNL, presa da Mijn PostNL (My account > API beheren). Viene inviata a PostNL nell'intestazione "apikey" e non viene mai mostrata ai clienti né scritta nel log. Dopo il salvataggio il campo resta vuoto e mostra Saved - leave empty to keep it. Inserisci un nuovo valore solo per modificarlo.

Remove the saved API key: spunta la casella e clicca su Save per eliminare la chiave salvata. Il corriere con punto di ritiro non viene più offerto.

Sandbox: usa la sandbox PostNL (api-sandbox.postnl.nl) con una chiave API sandbox. I clienti vedono allora punti di ritiro di prova. Lascialo disattivato su un negozio in produzione.

Ship from (country): il paese da cui consegni i pacchi a PostNL, Netherlands o Belgium. Predefinito: Netherlands. PostNL usa l'indirizzo del mittente per la data di ritiro.

Ship from (postcode): il CAP del mittente, ad esempio 1234AB nei Paesi Bassi o 1000 in Belgio. Lascia vuoto per usare il CAP del negozio da Shop Parameters > Contact > Stores quando il negozio si trova nello stesso paese. Un CAP non valido viene salvato vuoto con un avviso. Quando modifichi la chiave API, l'impostazione della sandbox o l'indirizzo di spedizione, vengono cancellati gli elenchi di punti di ritiro in cache e l'ultimo errore API.

Prezzi (nella valuta predefinita del negozio, IVA esclusa)

I prezzi si applicano a entrambi i corrieri. PostNL non offre un'API pubblica per le tariffe, quindi il modulo non richiede tariffe in tempo reale. Per un cliente che paga in un'altra valuta, PrestaShop converte il prezzo con il tasso di cambio del tuo negozio.

Price per country: una riga per ogni paese di destinazione. Clicca su + Add country per aggiungere una riga e sull'icona del cestino per rimuoverla. 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. Il prezzo di una classe di peso sostituisce Price; lascialo vuoto per usare Price. Un Price di 0 significa spedizione gratuita. Sono accettati "6.95", "6,95" e importi con separatore delle migliaia come "1.234,50" o "1,234.50". 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 avviso.

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

Price for other countries: usato quando la tabella non contiene né il paese né una riga *. Lascialo vuoto per nascondere lì i corrieri.

Condizioni

Free shipping from: il subtotale del carrello (prodotti da spedire, IVA esclusa, dopo gli sconti) a partire dal quale la consegna è gratuita. Si applica solo dove viene trovato un prezzo. Lascia vuoto per non offrire mai la spedizione gratuita.

Minimum subtotal: mostra i corrieri solo quando il subtotale del carrello è almeno pari a questo importo. Lascia vuoto per mostrarli sempre.

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

Maximum weight (kg): nasconde i corrieri per carrelli più pesanti. Predefinito: 30 (i pacchi PostNL arrivano fino a 30 kg nel Benelux). 0 significa nessun limite. Se lo lasci vuoto, nelle zone dei corrieri si applicano 30 kg, e nessun limite vale solo per i paesi raggiunti tramite Ignore zones. Un peso minimo superiore al massimo viene rifiutato con un errore, perché i corrieri non verrebbero mai mostrati.

Tutti gli importi e i pesi accettano la virgola decimale, anche con il separatore delle migliaia. Un numero non valido o negativo viene ignorato con un avviso e il campo viene salvato vuoto.

Disponibilità senza zone di spedizione

Normalmente i corrieri vengono offerti nelle zone di spedizione a cui sono collegati in Shipping > Carriers.

Ignore zones: offre PostNL anche nei paesi sotto indicati, che le sue zone non contengono. I corrieri vengono allora collegati a tutte le zone attive, incluse quelle che creerai in seguito. Quando lo disattivi di nuovo, i corrieri riprendono le zone che avevano prima.

Countries: i paesi di destinazione per questa modalità. Lascia vuoto per consentire tutti i paesi. Questo campo viene usato solo quando Ignore zones è attivo. In questi paesi possono essere offerti entrambi i corrieri; il corriere con punto di ritiro, però, solo per Paesi Bassi e Belgio.

Avanzate

Debug log: scrive messaggi di debug in logs/vfd_ptnl_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori API vengono sempre registrati. Non viene scritta alcuna chiave API né alcun dato dei clienti. Disattiva il log quando hai finito.

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

Remove data on uninstall: se attivo, disinstallando il modulo vengono eliminati le impostazioni PostNL e i corrieri. Se disattivo, disinstallando i corrieri vengono solo disattivati. I punti di ritiro salvati sugli ordini vengono sempre conservati.

Come funziona al checkout

Nel passaggio di spedizione PrestaShop chiede al modulo il prezzo di ogni corriere PostNL. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nel subtotale. Il modulo verifica le condizioni: peso del carrello e subtotale minimo. 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 corriere viene nascosto. Se il subtotale del carrello raggiunge Free shipping from, il prezzo è 0.

Il corriere con punto di ritiro viene offerto solo per indirizzi nei Paesi Bassi e in Belgio e solo con una chiave API. Quando l'indirizzo di consegna ha un CAP valido, il modulo chiede alla PostNL Checkout API i tre punti di ritiro più vicini. Invia il CAP, la via, il numero civico, la città e il paese del cliente, e l'indirizzo di spedizione del negozio. Per il corriere per la consegna a domicilio non viene inviato nulla. Se PostNL non è raggiungibile o non ha punti per l'indirizzo, il corriere con punto di ritiro viene nascosto e quello per la consegna a domicilio resta disponibile. Il timeout dell'API è di 12 secondi.

Gli elenchi di punti vengono memorizzati nella cache per 6 ore per CAP, e le risposte "nessun punto" per 1 ora. Le richieste fallite vengono memorizzate nella cache per 10 minuti, così un'interruzione non rallenta ogni aggiornamento del checkout. L'ultimo errore viene mostrato nella pagina del modulo.

Se modifichi un corriere in Shipping > Carriers dopo che ha ricevuto ordini, PrestaShop lo salva come nuova versione del corriere. Il modulo segue automaticamente la nuova versione.

Il modulo 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 consegna in giornata, 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 il corriere con punto di ritiro, sotto appare un elenco PostNL pickup point con i tre punti più vicini: nome dell'azienda, indirizzo e distanza. La pagina non attende mai PostNL: se l'elenco non è ancora in cache, viene caricato appena il corriere viene selezionato. Prima che venga inserito un CAP completo, il cliente vede "Inserisci il tuo CAP (ad esempio 1234 AB) per vedere i punti di ritiro PostNL." (4 cifre per il Belgio). Il punto scelto viene salvato nel carrello e resta quando il checkout si aggiorna.

Il punto è obbligatorio. Senza di esso il cliente non può proseguire e vede "Scegli un punto di ritiro PostNL." Quando il cliente clicca su Continue, il server controlla il punto con l'elenco di PostNL per l'indirizzo di consegna. Se non è nell'elenco, il cliente vede "Il punto di ritiro PostNL scelto non è disponibile per questo indirizzo. Sceglilo di nuovo." Se PostNL non è raggiungibile, il cliente vede "I punti di ritiro PostNL non possono essere caricati in questo momento. Riprova tra qualche minuto o scegli un altro metodo di spedizione." Un punto scelto per un altro indirizzo non viene mai usato per l'ordine. Nome e indirizzo salvati con l'ordine provengono da PostNL, non dal browser.

Pagina dell'ordine nell'amministrazione: un blocco PostNL pickup point con nome e indirizzo, il Location code e il Partner ID.

Pagine di conferma e di dettaglio dell'ordine: PostNL pickup point con nome e indirizzo.

E-mail degli ordini: nome e indirizzo del punto vengono aggiunti al nome del corriere nell'e-mail di conferma dell'ordine. La e-mail di nuovo ordine del negozio (modulo Mail alerts) mostra anche il codice di localizzazione.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox PostNL è il primo blocco della pagina Modules > Module Manager > VibeFox PostNL > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca 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 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-postnl e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo i dipendenti con l'autorizzazione 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, per esempio Key not found, This key belongs to another product, Domain limit reached o License expired on seguito da una data. Dopo aver cambiato l'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 solo dominio: il dominio del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, i corrieri PostNL non vengono mostrati ai clienti al checkout e non viene calcolata alcuna tariffa di spedizione. Lo storefront di PrestaShop non sa che hai effettuato l'accesso al back office, quindi i corrieri vengono nascosti anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non puoi provarlo 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 assistenza richiedono un rinnovo. Lo stato viene verificato 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 a settimana. Non serve alcun cron job. La disinstallazione del modulo rimuove sempre la chiave di licenza e lo stato della licenza. Il Reset di questo modulo non cancella i dati, quindi la chiave e lo stato vengono conservati.

Risoluzione dei problemi

PostNL non compare al checkout: verifica che la licenza sia attiva e che l'interruttore del corriere sia acceso. In Shipping > Carriers verifica che il corriere copra la zona del paese del cliente e il gruppo del cliente (oppure che Ignore zones sia attivo e il paese consentito). Verifica che sia impostato un prezzo per il paese, i limiti di peso e Minimum subtotal. I prodotti possono anche essere limitati a determinati corrieri nella pagina del prodotto.

Il corriere con punto di ritiro non compare: viene mostrato solo per indirizzi olandesi e belgi, solo con una chiave API, un CAP di spedizione e un prezzo, e solo quando PostNL restituisce punti per il CAP del cliente. Controlla gli avvisi in cima alla pagina del modulo e il campo Log. Gli errori vengono sempre registrati; attiva Debug log per i dettagli.

"PostNL pickup points cannot be loaded right now": PostNL non è raggiungibile, ha rifiutato la chiave API oppure manca il CAP di spedizione. La pagina del modulo mostra l'ultimo errore. Una chiave sandbox funziona solo con Sandbox attivo, e una chiave live solo con esso disattivo.

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

I pesi dei prodotti sembrano errati: se la pagina del modulo avvisa che l'unità di peso del negozio non è riconosciuta, imposta un'unità standard (kg, g, lb o oz) in International > Localization alla voce Local units. Fino ad allora i pesi dei prodotti vengono letti come kg.

La pagina dice che un corriere PostNL non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Reimposta il modulo in Modules > Module Manager per ricrearlo. Il ripristino mantiene le impostazioni e lo stato dei corrieri.

Disinstallazione

Vai in Modules > Module Manager, apri il menu accanto a VibeFox PostNL e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. Gli elenchi di punti di ritiro in cache e l'ultimo errore API vengono sempre rimossi. Se Remove data on uninstall è attivo, i corrieri vengono eliminati (gli ordini conservano lo storico) e vengono rimosse le impostazioni e il log. Se è disattivo, i corrieri vengono solo disattivati e tutte le impostazioni restano. Reinstallare il modulo restituisce ai corrieri lo stato che avevano. Gli ordini esistenti conservano le loro righe di spedizione e il punto di ritiro salvato.

PostNL è un marchio registrato del rispettivo proprietario. Questo modulo non è affiliato a PostNL né approvato da PostNL.