VibeFox PostNL for OpenCart — Guida

Requisiti

OpenCart: 3.0.x (testato su 3.0.5.0) o 4.0.2 e successivi (testato su 4.1.0.3).

PHP: 8.0 o successivo.

Chiave API PostNL (solo per i punti di ritiro): i punti di ritiro vengono caricati dall'API Checkout di PostNL. I clienti business di PostNL trovano la chiave API in Mijn PostNL, sotto My account > API beheren. La sandbox di PostNL richiede una chiave sandbox separata. L'opzione di consegna a domicilio non richiede alcuna chiave.

Chiave di licenza VibeFox: si acquista 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_postnl-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_postnl.ocmod.zip. Installa solo il pacchetto per la tua versione di OpenCart. La chiave di licenza è la stessa per entrambe le versioni.

OpenCart 3

1. Nell'amministrazione vai su Extensions > Installer, fai clic su Upload e scegli il file vfd_postnl-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non devi aggiornare Extensions > Modifications. In alternativa all'Installer, puoi copiare il contenuto della cartella upload di questo pacchetto nella cartella principale del tuo negozio.

2. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox PostNL e fai clic su Install (il pulsante verde +).

3. Fai clic su Edit (il pulsante con la matita) per aprire la pagina delle impostazioni.

4. Inserisci la tua chiave di licenza VibeFox in License key nel blocco di licenza in alto nella pagina Edit e fai clic su Activate (vedi Chiave di licenza).

5. Attiva PostNL pickup point e/o PostNL home address e inserisci i prezzi. Per i punti di ritiro inserisci anche la API key di PostNL e il Ship from (postcode) (vedi Configurazione). Fai clic su Save.

OpenCart 4

1. Nell'amministrazione vai su Extensions > Installer, fai clic su Upload e scegli il file vfd_postnl.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. Fai clic su Install (il pulsante verde +) accanto a esso.

3. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox PostNL, fai clic su Install (il pulsante verde +), poi su Edit (il pulsante con la 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 nelle due versioni.

Dopo l'installazione entrambe le opzioni sono disattivate finché non ne attivi una e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni PostNL che hai conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox PostNL > Edit. Le sezioni sono elencate a sinistra. Un unico pulsante Save in fondo salva l'intera pagina senza ricaricarla. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.

Se un valore è errato, non viene salvato nulla e la pagina mostra il motivo: un nome di opzione vuoto, più lungo di 64 caratteri o contenente < > ; = # { }; un ordine di visualizzazione che non è un numero intero; un peso minimo superiore a quello massimo; oppure una classe fiscale o una zona geografica non valide. I problemi minori vengono salvati con una nota: un numero non valido o negativo lascia vuoto il suo campo, un CAP di spedizione non valido viene salvato vuoto e un prezzo non valido nella tabella viene ignorato.

Sopra le impostazioni la pagina mostra avvisi: manca la chiave API o il CAP di spedizione per i punti di ritiro, la sandbox è attiva, non è impostato alcun prezzo, l'ultima richiesta a PostNL non riuscita con data ed errore, oppure un negozio senza una classe di peso "kg".

Generale

Ogni tipo di consegna è un'opzione a sé stante al checkout. Le impostazioni di questa pagina valgono per entrambe.

PostNL pickup point: attiva o disattiva l'opzione del punto di ritiro. Il cliente deve scegliere un punto PostNL al checkout. È offerta solo per gli indirizzi dei Paesi Bassi e del Belgio e solo con una chiave API. Predefinito: disattivato.

Pickup point option name: il nome che il cliente vede al checkout. Predefinito: PostNL pickup point. Obbligatorio, fino a 64 caratteri, senza < > ; = # { }.

PostNL home address: attiva o disattiva l'opzione di consegna a domicilio. Non viene scelto alcun punto. Funziona per ogni paese con un prezzo. Predefinito: disattivato.

Home delivery option name: il nome che il cliente vede al checkout. Predefinito: PostNL. Stesse regole del nome del punto di ritiro.

Sort order: la posizione di PostNL tra i metodi di spedizione al checkout. Un numero intero.

Tax class: la classe fiscale di entrambe le opzioni. Con una classe fiscale OpenCart aggiunge la sua imposta ai prezzi. No tax 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 da Mijn PostNL (My account > API beheren). Viene inviata a PostNL nell'intestazione "apikey" e non viene mai mostrata ai clienti né scritta nel registro. Dopo il salvataggio il campo resta vuoto e mostra Saved - leave empty to keep it. Inserisci un valore nuovo solo per modificarla.

Remove the saved API key: spunta la casella e fai clic su Save per eliminare la chiave salvata. L'opzione del punto di ritiro non viene più offerta.

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

Ship from (country): il paese in cui consegni i pacchi a PostNL: Paesi Bassi o Belgio. PostNL usa l'indirizzo del mittente per la data di ritiro. All'installazione viene impostato sul paese del negozio se è Paesi Bassi o Belgio, altrimenti sui Paesi Bassi.

Ship from (postcode): il CAP del mittente, per esempio 1234AB nei Paesi Bassi o 1000 in Belgio. Obbligatorio per i punti di ritiro: OpenCart non ha un CAP del negozio, quindi non viene preso dall'indirizzo del negozio. 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 dei punti di ritiro memorizzati nella cache e l'ultimo errore API.

Prezzi (nella valuta predefinita del negozio, IVA esclusa)

I prezzi valgono per entrambe le opzioni. PostNL non dispone di un'API pubblica per le tariffe, quindi l'estensione non richiede tariffe in tempo reale. Per un cliente che paga in un'altra valuta, OpenCart converte il prezzo con il tasso di cambio del tuo negozio.

Price per country: una riga per ogni paese di destinazione. Fai clic su Add country per aggiungere una riga e sul pulsante × 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" e "6,95". Le righe senza prezzi vengono rimosse 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 volta. Per item (price x quantity) lo moltiplica per il numero di articoli che richiedono spedizione.

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

Condizioni

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

Minimum subtotal: mostra le opzioni solo quando il subtotale del carrello raggiunge almeno questo importo. Lascialo vuoto per mostrarle sempre.

Minimum weight (kg): nasconde le opzioni quando il carrello pesa meno. I pesi dei prodotti vengono convertiti dalla loro classe di peso. Lascialo vuoto per nessun limite.

Maximum weight (kg): nasconde le opzioni per carrelli più pesanti. I pacchi PostNL arrivano fino a 30 kg nel Benelux. 0 significa nessun limite. Se lo lasci vuoto, si applicano 30 kg, oppure nessun limite quando Ignore shipping zones è attivo.

Tutti gli importi e i pesi accettano la virgola decimale.

Disponibilità

Geo zone: offri PostNL solo per gli indirizzi di questa zona geografica. All zones (predefinito) significa nessun limite. La zona geografica non viene verificata quando Ignore shipping zones è attivo. Le zone geografiche si gestiscono in System > Localisation > Geo Zones.

Ignore shipping zones: quando è attivo, la zona geografica non viene verificata e PostNL viene offerto per i paesi selezionati sotto (tutti i paesi se l'elenco è vuoto). Quando è disattivo, conta solo la zona geografica.

Countries: i paesi di destinazione per questa modalità. Lascialo vuoto per consentire tutti i paesi. Questo campo viene usato solo quando Ignore shipping zones è attivo. L'opzione del punto di ritiro continua a essere offerta solo per i Paesi Bassi e il Belgio.

Avanzate

Debug log: scrive messaggi di debug in storage/logs/vfd_ptnl_debug.log.php (su OpenCart 4 system/storage/logs/vfd_ptnl_debug.log.php). Il file non può essere letto dal web. Gli errori API e gli ordini senza un punto di ritiro valido vengono sempre registrati. Non viene scritta alcuna chiave API né alcun dato dei clienti. Disattiva il registro quando hai finito. Quando il file raggiunge 5 MB, viene avviato un nuovo registro.

Log: mostra la dimensione e le ultime voci del registro di debug. Fai clic su Clear log per svuotarlo.

Remove data on uninstall: quando è attivo, la disinstallazione dell'estensione elimina le impostazioni PostNL e il registro. Gli elenchi di punti in cache vengono sempre rimossi. I punti di ritiro salvati negli ordini vengono sempre conservati.

Importazione / Esportazione

Export: fai clic su Download JSON per salvare le impostazioni in un file JSON. La chiave API non viene esportata.

Import: incolla un JSON esportato in precedenza e fai clic su Import per ripristinare le impostazioni, per esempio in un altro negozio. I valori vengono verificati come in un salvataggio normale. La chiave API salvata viene conservata.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di ciascuna opzione PostNL. Se Ignore shipping zones è attivo, PostNL viene offerto solo per un paese consentito, indipendentemente dalla zona geografica. Altrimenti, se è impostata una Geo zone, l'indirizzo deve trovarsi al suo interno. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri prodotti non aggiungono peso e non sono inclusi nel subtotale. L'estensione verifica il peso del carrello e il 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, l'opzione viene nascosta. Se il subtotale del carrello raggiunge Free shipping from, il prezzo è 0. Il prezzo viene mostrato al cliente nella sua valuta, con l'IVA della Tax class selezionata.

L'opzione del punto di ritiro viene offerta solo per gli indirizzi dei Paesi Bassi e del Belgio, e solo con una chiave API. Quando l'indirizzo di consegna ha un CAP completo, l'estensione chiede all'API Checkout di PostNL i tre punti di ritiro più vicini. Invia il CAP del cliente, la via e il numero civico, la città e il paese, e l'indirizzo di spedizione del negozio. Per l'opzione di consegna a domicilio non viene inviato nulla. Se PostNL non è raggiungibile o non ha punti per l'indirizzo, l'opzione del punto di ritiro viene nascosta e la consegna a domicilio resta disponibile. Il timeout dell'API è di 12 secondi.

Gli elenchi dei punti sono memorizzati nella cache per 6 ore per indirizzo, e le risposte "nessun punto" per 1 ora. Le richieste non riuscite vengono memorizzate nella cache per 10 minuti, così un'interruzione non rallenta ogni aggiornamento del checkout. La cache viene conservata nella tabella del database propria dell'estensione. L'ultimo errore viene mostrato nella pagina dell'estensione fino alla richiesta successiva riuscita.

L'estensione non richiede tariffe PostNL in tempo reale e non crea etichette di spedizione, codici a barre, tracciamento, resi né pre-avvisi. Non dispone di opzioni per il giorno di consegna, la consegna serale o quella mattutina. Crea la spedizione in Mijn PostNL o in un altro strumento PostNL usando il punto di ritiro salvato.

Su OpenCart 4 il cliente fa clic su Choose nel blocco del metodo di spedizione della pagina di checkout e sceglie un'opzione PostNL nella finestra Shipping method options. I prezzi sono gli stessi di OpenCart 3.

Punti di ritiro

Quando l'indirizzo di consegna si trova nei Paesi Bassi o in Belgio, sotto l'opzione del punto di ritiro compare un elenco PostNL pickup point con i tre punti più vicini: nome dell'azienda, indirizzo e distanza, dal più vicino. La pagina non attende mai PostNL: se l'elenco non è ancora in cache, viene caricato appena l'opzione viene selezionata. Prima che venga inserito un CAP completo, il cliente vede "Enter your postcode (for example 1234 AB) to see PostNL pickup points." (4 cifre per il Belgio). Il punto scelto viene salvato subito per il checkout.

Il punto è obbligatorio. Quando il cliente fa clic su Continue nella fase del metodo di spedizione, il server verifica il punto con l'elenco di PostNL per l'indirizzo di consegna. Senza un punto, il cliente vede "Please choose a PostNL pickup point." Se il punto non è nell'elenco, il cliente vede "The chosen PostNL pickup point is not available for this address. Please choose it again." Se PostNL non è raggiungibile, il cliente vede "PostNL pickup points cannot be loaded right now. Please try again in a few minutes or choose another shipping method." Un punto scelto per un altro indirizzo non viene mai usato per l'ordine. Il nome e l'indirizzo salvati con l'ordine provengono da PostNL, non dal browser.

Pagine dell'ordine, e-mail e fattura: il punto viene aggiunto al metodo di spedizione dell'ordine, per esempio "PostNL pickup point: nome, indirizzo" (il nome dell'opzione del punto di ritiro, poi il punto) (fino a 128 caratteri, su OpenCart 4 fino a 255). Viene mostrato ovunque OpenCart mostri il metodo di spedizione: lo storico ordini del cliente, le e-mail degli ordini, la fattura e Sales > Orders.

Pagina dell'ordine nell'amministrazione: in Sales > Orders la pagina dell'ordine mostra sopra lo storico un riquadro PostNL pickup point con il punto, il Location code e il Partner ID. Compare solo per gli ordini con un punto salvato, anche dopo la disattivazione dell'estensione.

Su OpenCart 4 l'elenco dei punti compare nella finestra Shipping method options, sotto l'opzione PostNL pickup point, e viene caricato di nuovo ogni volta che la finestra si apre, perché l'indirizzo può cambiare nel checkout in una sola pagina. Il pulsante Continue della finestra non procede senza un punto valido, con gli stessi messaggi. OpenCart 4 mantiene un unico ordine per il checkout e lo aggiorna ogni volta che il cliente conferma di nuovo, e il punto dell'ordine viene aggiornato insieme ad esso.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox PostNL è il primo blocco in Extensions > Extensions > Shipping > VibeFox PostNL > Edit, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (per esempio la data fino a cui 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 ci sono la riga Product: opencart-shipping-postnl 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 blocco seguono la lingua dell'amministrazione (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 oppure License expired on con una data. Dopo la modifica dell'indirizzo del negozio, o dopo aver liberato uno slot di dominio nel tuo account, fai clic 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 suo slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, le opzioni di spedizione PostNL non vengono mostrate ai clienti al checkout e non viene calcolato alcun prezzo di spedizione. Un utente amministratore che ha effettuato l'accesso al pannello di amministrazione nello stesso browser vede comunque le opzioni nel negozio, contrassegnate da (unlicensed — visible to admins only), così puoi configurare e provare l'estensione prima di acquistare una chiave. Su OpenCart 4 questa anteprima non è disponibile: il negozio non vede l'accesso dell'amministratore, quindi senza una chiave attiva le opzioni sono nascoste a tutti. Dopo aver aperto una volta la pagina Edit, 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 assistenza richiedono il rinnovo. Lo stato viene controllato 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

PostNL non compare al checkout: verifica che la licenza sia attiva e che PostNL pickup point o PostNL home address sia attivo. Verifica la Geo zone (o che Ignore shipping zones sia attivo e il paese consentito), che sia impostato un prezzo per il paese, i limiti di peso e il Minimum subtotal. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.

L'opzione del punto di ritiro non compare: viene mostrata solo per gli 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 alto nella pagina dell'estensione e il campo Log. Gli errori vengono sempre registrati; attiva il Debug log per i dettagli.

"PostNL pickup points cannot be loaded right now": PostNL non era raggiungibile, ha rifiutato la chiave API oppure manca il CAP di spedizione. La pagina dell'estensione mostra l'ultimo errore. Una chiave sandbox funziona solo con Sandbox attivo, una chiave reale solo con esso disattivato.

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

I pesi dei prodotti sembrano errati: se la pagina dell'estensione avvisa che il negozio non ha una classe di peso "kg", controlla System > Localisation > Weight Classes. I pesi dei prodotti vengono convertiti in base al nome dell'unità della loro classe, e le unità sconosciute vengono lette come kg.

La pagina mostra "Warning: You do not have permission to modify VibeFox PostNL!": il tuo gruppo di utenti amministratori può solo visualizzare le impostazioni. Concedi al gruppo il permesso di modifica per extension/shipping/vfd_postnl (OpenCart 3) o extension/vfd_postnl/shipping/vfd_postnl (OpenCart 4) in System > Users > User Groups.

Per gli sviluppatori: l'indirizzo dell'API PostNL può essere sostituito con l'impostazione vfd_ptnl_api_url (per i test); non ha un campo nella pagina delle impostazioni.

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e fai clic su Uninstall (il pulsante rosso −) accanto a VibeFox PostNL. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre lo stato dell'estensione, Sort order, Tax class e Geo zone. Gli elenchi dei punti in cache e l'ultimo errore API vengono sempre rimossi. Se Remove data on uninstall è attivo, vengono eliminati anche le impostazioni PostNL, il registro di debug e i punti dei checkout che non sono mai diventati ordini. Se è disattivo, le altre impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. Gli ordini esistenti conservano il loro metodo di spedizione, il costo e il punto di ritiro salvato.

Su OpenCart 4, per rimuovere anche i file dell'estensione, dopo la disinstallazione vai su Extensions > Installer e fai clic su Uninstall (il pulsante arancione −) accanto a VibeFox PostNL nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per eliminare il pacchetto caricato.

PostNL è un marchio del rispettivo titolare. Questa estensione non è affiliata a PostNL né approvata da PostNL.