VibeFox PostNord for OpenCart — Guida

Requisiti

OpenCart: 3.0.x (testato con la versione 3.0.5.0) o 4.0.2 e successivi (testato con la versione 4.1.0.3).

PHP: 8.0 o successivo.

Chiave API PostNord (per il selettore dei punti di servizio): crea un account gratuito su developer.postnord.com, aggiungi un'applicazione e copia la sua chiave API. Senza la chiave il metodo di spedizione continua a funzionare, ma i clienti non possono scegliere un punto di servizio.

Contratto PostNord: per spedire pacchi ti serve il tuo consueto contratto cliente PostNord, per esempio MyPack Collect o MyPack Home.

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_postnord-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_postnord.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'area di amministrazione vai su Extensions > Installer, fai clic su Upload e scegli il file vfd_postnord-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non serve aggiornare Extensions > Modifications. In alternativa all'Installer, puoi copiare il contenuto della cartella upload di questo pacchetto nella cartella principale del negozio.

2. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox PostNord 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 nel campo License key del blocco licenza in alto nella pagina Edit e fai clic su Activate (vedi Chiave di licenza).

5. Attiva Enable/Disable (consegna al punto di servizio) e/o Home delivery, incolla la API key di PostNord, scegli l'Agreement country, compila i Country prices oppure un Fallback cost (vedi Configurazione) e fai clic su Save.

OpenCart 4

1. Nell'area di amministrazione vai su Extensions > Installer, fai clic su Upload e scegli il file vfd_postnord.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 PostNord, 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 PostNord che avevi conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox PostNord > Edit. Le sezioni sono elencate a sinistra. Un pulsante Save in fondo salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella anche gli elenchi dei punti di servizio in cache. 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 vuoto, più lungo di 64 caratteri o che contiene < > ; = # { }, un ordine di visualizzazione che non è un numero intero, uno stato fiscale o una zona geografica non validi, oppure un Min weight (kg) maggiore di Max weight (kg). Un campo numerico con un valore che non è un numero pari o superiore a 0 viene salvato vuoto, con un messaggio. Una cella della tabella dei prezzi che non è un numero pari o superiore a 0 viene salvata come 0, con un messaggio.

Sopra le impostazioni la pagina avvisa quando non è ancora presente una chiave API, quando non è ancora impostato alcun prezzo e quando il negozio non ha la classe di peso "kg".

Generale

Le due opzioni di consegna vengono offerte nella zona geografica impostata in Availability, oppure per i paesi indicati in Ignore shipping zones.

Enable/Disable: attiva o disattiva la consegna PostNord a un punto di servizio o a un armadietto per pacchi. Il cliente sceglie il punto al checkout. Predefinito: disattivato.

Name: il nome dell'opzione del punto di servizio al checkout, per esempio "PostNord MyPack Collect". Predefinito: PostNord. Obbligatorio, fino a 64 caratteri, senza < > ; = # { }.

Home delivery: offre anche la consegna a domicilio PostNord, una seconda opzione senza punto di servizio. Predefinito: disattivato.

Home delivery name: il nome dell'opzione di consegna a domicilio al checkout, per esempio "PostNord MyPack Home". Predefinito: PostNord Home delivery. Stesse regole di Name.

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

Tax status: None (the prices are final) (predefinito), oppure una classe fiscale: in tal caso OpenCart aggiunge ai prezzi l'imposta sulla spedizione di quella classe. Vale per entrambe le opzioni.

API PostNord (selettore dei punti di servizio)

API key: la chiave API della tua applicazione su developer.postnord.com. Viene inviata a PostNord solo dal tuo server, mai al browser, e non viene mai scritta nel registro. Dopo il salvataggio il campo resta vuoto e mostra Saved - leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarla.

Remove the saved API key: spunta la casella e fai clic su Save per eliminare la chiave salvata.

Test mode: usa l'ambiente di test PostNord (atapi2.postnord.com). Solo per le chiavi emesse per l'ambiente di test.

Agreement country: il paese del tuo contratto cliente PostNord: Svezia, Danimarca, Norvegia o Finlandia. Determina quali punti di servizio vengono offerti. Same as the delivery country (predefinito) usa il paese del cliente.

Prezzi

Il titolo della sezione mostra la valuta predefinita del negozio. I prezzi sono in quella valuta, IVA esclusa, e sono gli stessi per entrambe le opzioni. PostNord non ha un'API pubblica dei prezzi, quindi imposti tu i prezzi, di norma quelli del tuo contratto PostNord. L'ordine è: soglia di spedizione gratuita, poi tabella per paese, infine il costo di riserva.

Calculation type: Per order (predefinito) addebita il prezzo una sola volta. Per item (price x number of items) lo moltiplica per il numero di articoli nel carrello.

Country prices: un prezzo per paese di destinazione e peso del carrello. Fai clic su Add country per aggiungere una riga e sul pulsante × per rimuoverla. Ogni riga ha una colonna Price e colonne di peso: 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. Una colonna di peso con 0 usa la colonna Price, e un Price pari a 0 significa spedizione gratuita. Il paese * All other countries copre ogni paese senza una riga propria. Decimali con virgola o punto (9,99 oppure 9.99). Una nuova riga parte come * All other countries con tutti i prezzi a 0. Scegli il paese e inserisci i prezzi prima di salvare, oppure rimuovi la riga. Una cella vuota viene salvata come 0.

Fallback cost: viene usato quando la tabella per paese non ha una riga per la destinazione né una riga *. Lascialo vuoto per nascondere PostNord in quei paesi.

Free shipping from: il subtotale del carrello (prodotti che richiedono la spedizione, dopo il coupon, IVA esclusa) a partire dal quale PostNord è gratuito. Viene verificato prima della tabella per paese, quindi vale anche per un paese senza riga di prezzo. Lascialo vuoto per non offrire mai la spedizione gratuita.

Disponibilità

Min weight (kg): nasconde PostNord quando il carrello pesa meno. I pesi dei prodotti vengono convertiti dalla loro classe di peso. Predefinito: 0, cioè nessun limite.

Max weight (kg): nasconde PostNord quando il carrello pesa di più. Predefinito: 30. 0 significa nessun limite. Verifica il limite di peso del tuo servizio PostNord: gli armadietti accettano meno dei punti di servizio.

Minimum subtotal: mostra PostNord solo se il subtotale del carrello (prodotti che richiedono la spedizione, dopo il coupon, IVA esclusa) raggiunge almeno questo importo. Lascialo vuoto per mostrarlo sempre.

Geo zone: offre PostNord solo per gli indirizzi in questa zona geografica. All zones (predefinito) significa nessun limite. Le zone geografiche si gestiscono in System > Localisation > Geo Zones. Non viene usata finché Ignore shipping zones è attivo.

Ignore shipping zones: se attivo, la zona geografica non viene verificata e PostNord viene offerto per i paesi indicati sotto. Se disattivo, viene offerto solo nella zona geografica.

Countries (Ignore shipping zones): i paesi di destinazione per questa modalità. Lascialo vuoto per consentire tutti i paesi. Questo campo viene usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: scrive i calcoli delle tariffe e le chiamate API in storage/logs/vfd_ptnd_debug.log.php. Il file non può essere letto dal web. Gli errori dell'API vengono sempre registrati. La chiave API non viene mai registrata. 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: se attivo, disinstallando l'estensione vengono eliminate le impostazioni PostNord e il registro. Gli elenchi dei punti di servizio in cache vengono sempre rimossi. I punti di servizio 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 il JSON esportato in precedenza e fai clic su Import per ripristinare le impostazioni, per esempio su un altro negozio. I valori vengono verificati come in un normale salvataggio. La chiave API salvata viene mantenuta.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di ogni opzione PostNord. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non rientrano nel subtotale. L'estensione verifica la zona geografica o l'elenco dei paesi, il peso del carrello e il subtotale minimo. Se si applica la spedizione gratuita, il prezzo è 0. Altrimenti il prezzo viene dalla tabella per paese e, in seguito, dal costo di riserva. Se non c'è alcun prezzo, l'opzione viene nascosta. Il prezzo viene calcolato nella valuta predefinita e mostrato al cliente nella sua valuta, con l'imposta della Tax status selezionata. Il calcolo del prezzo non contatta mai PostNord.

Per l'opzione del punto di servizio e un indirizzo di consegna in Svezia, Danimarca, Norvegia o Finlandia, il tuo server chiede alla PostNord Business Location API i 10 punti di servizio più vicini al codice postale di consegna. Invia il paese e il codice postale di consegna e il paese del contratto. Il timeout dell'API è di 10 secondi. Gli elenchi vengono memorizzati nella cache per 6 ore per ogni codice postale, e le risposte "nessun punto" per 1 ora. Gli errori dell'API vengono memorizzati nella cache per 5 minuti, così un'interruzione di PostNord non rallenta ogni aggiornamento del checkout. La cache è conservata nella tabella del database propria dell'estensione. Il passaggio della consegna non attende mai PostNord: se l'elenco non è ancora in cache, viene caricato quando il cliente seleziona l'opzione.

Per altre destinazioni le opzioni possono comunque essere offerte con i tuoi prezzi, senza selettore. L'opzione di consegna a domicilio non mostra mai un selettore.

L'estensione non richiede prezzi PostNord in tempo reale e non crea etichette di spedizione, non prenota spedizioni (EDI), non fornisce numeri di tracciamento e non invia e-mail di tracciamento. Non esiste una vista a mappa. Per le spedizioni usa PostNord Portal, Skicka Direkt Business o uno strumento per le etichette; questi strumenti hanno bisogno dell'ID del punto di servizio salvato.

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

Punti di ritiro

Quando l'indirizzo di consegna si trova in Svezia, Danimarca, Norvegia o Finlandia, sotto l'opzione del punto di servizio compare un elenco PostNord service point con i punti più vicini, raggruppati per città, ciascuno con indirizzo e distanza. Prima di inserire un codice postale, il cliente vede "Inserisci il tuo codice postale per scegliere un punto di servizio PostNord." La scelta viene salvata subito per il checkout.

Quando l'elenco è caricato, un punto è obbligatorio. Senza un punto, Continue nel passaggio del metodo di consegna si blocca con il messaggio "Seleziona un punto di servizio PostNord." Il punto scelto viene verificato sul server rispetto all'elenco PostNord per l'indirizzo di consegna. Un punto scelto per un altro codice postale non viene usato.

Il selettore non blocca mai una vendita. Se l'elenco non può essere caricato (chiave API non ancora impostata, API PostNord non disponibile, nessun punto vicino al codice postale), il cliente vede una nota e può comunque effettuare l'ordine. PostNord consegna allora al punto di servizio più vicino all'indirizzo.

Pagine degli ordini, e-mail e fattura: il punto viene aggiunto al metodo di spedizione dell'ordine, per esempio "PostNord: nome, indirizzo (ID 12345)" (il nome dell'opzione, poi il punto). Se il testo supera i 128 caratteri, l'indirizzo viene omesso (su OpenCart 4 non c'è questo limite e l'indirizzo viene sempre mantenuto). Compare ovunque OpenCart mostra il metodo di spedizione: nella cronologia ordini del cliente, nelle e-mail d'ordine, nella fattura e in Sales > Orders. Un ordine senza punto mantiene il nome semplice del metodo.

Pagina dell'ordine nell'area di amministrazione: in Sales > Orders la pagina dell'ordine mostra sopra la cronologia un pannello PostNord service point con nome, indirizzo e Service point ID. Se non è stato scelto alcun punto, indica "non selezionato - PostNord consegna al punto di servizio più vicino all'indirizzo di spedizione".

Su OpenCart 4 l'elenco dei punti di servizio compare nella finestra Shipping method options, sotto l'opzione del punto di servizio, 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 dell'elenco, con lo stesso messaggio. Se il cliente fa clic su di esso mentre l'elenco è ancora in caricamento, la finestra attende l'elenco senza messaggi e poi clicca di nuovo da sola su Continue. Anche un elenco non disponibile non blocca l'ordine. OpenCart 4 mantiene un unico ordine per il checkout e lo aggiorna ogni volta che il cliente conferma di nuovo, e il punto di servizio dell'ordine viene aggiornato insieme ad esso.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza License — VibeFox PostNord è il primo blocco della pagina Extensions > Extensions > Shipping > VibeFox PostNord > Edit, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopo, 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 ci sono la riga Product: opencart-shipping-postnord 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 cambiare la chiave. I testi del blocco seguono la lingua del pannello di amministrazione (sono incluse le lingue 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 lo slot del dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, le opzioni di spedizione PostNord 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

PostNord non compare al checkout: verifica che la licenza sia attiva e che Enable/Disable (o Home delivery) sia attivo. Controlla la Geo zone, oppure l'elenco Countries quando Ignore shipping zones è attivo. Verifica che sia impostato un prezzo per il paese (riga del paese, riga * o Fallback cost), i limiti di peso e il Minimum subtotal. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.

Il selettore indica che i punti di servizio non possono essere caricati: controlla la API key e l'impostazione Test mode. Una chiave di produzione non funziona con l'ambiente di test, e viceversa. Attiva il Debug log, ricarica il checkout e controlla il campo Log nella pagina dell'estensione. L'ordine può comunque essere effettuato; PostNord consegnerà allora al punto di servizio più vicino.

Punti di servizio inattesi: controlla l'Agreement country. Determina quali punti di servizio vengono offerti.

La spedizione è gratuita per errore: controlla le Country prices per le righe con un Price pari a 0, soprattutto una riga * aggiunta con Add country e lasciata incompleta, e controlla il Free shipping from.

I punti di servizio sembrano obsoleti dopo una modifica: fai clic su Save nella pagina dell'estensione. Questo svuota gli elenchi in cache.

I pesi dei prodotti sembrano errati: se la pagina dell'estensione avvisa che il negozio non ha la 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 riporta "Warning: You do not have permission to modify VibeFox PostNord!": il tuo gruppo di utenti amministratori potrebbe poter solo visualizzare le impostazioni. Concedi al gruppo il permesso di modifica per extension/shipping/vfd_postnord (OpenCart 3) o extension/vfd_postnord/shipping/vfd_postnord (OpenCart 4) in System > Users > User Groups.

Per gli sviluppatori: l'indirizzo dell'API PostNord può essere sostituito con l'impostazione vfd_ptnd_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 PostNord. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart reimposta sempre lo stato dell'estensione, il Sort order, il Tax status e la Geo zone. Gli elenchi dei punti di servizio in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, vengono eliminati anche le impostazioni PostNord, il registro di debug e i punti di servizio dei checkout che non sono mai diventati un ordine. 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 servizio 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 PostNord nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per eliminare il pacchetto caricato.

PostNord è un marchio del rispettivo proprietario. Questa estensione non è affiliata a PostNord né approvata da PostNord.