VibeFox Packeta 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), con il checkout predefinito del tema predefinito.

PHP: 8.0 o successivo.

Chiave API di Packeta: la trovi nella sezione clienti di Packeta (client.packeta.com) sotto Client support. È composta da 16 lettere e cifre. Il widget ne ha bisogno per aprirsi nel checkout, quindi il metodo viene mostrato ai clienti solo dopo che è stata inserita la chiave API.

Paesi: Repubblica Ceca, Slovacchia, Ungheria o Romania devono essere paesi abilitati nel tuo negozio. Sono presenti nei dati standard di OpenCart. L'Ungheria non ha regioni in OpenCart, quindi il campo regione dell'indirizzo resta vuoto; non ha importanza.

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_packeta-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_packeta.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_packeta-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 Packeta 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. Incolla la tua chiave di licenza VibeFox in License key nel blocco della licenza in alto nella pagina Edit e fai clic su Activate (vedi License key).

5. Inserisci la tua API key di Packeta e i tuoi prezzi: almeno una riga di Country prices (per esempio * Default) oppure un Fallback cost. Attiva Enable/Disable e fai clic su Save. La pagina mostra se Packeta ha accettato la chiave.

OpenCart 4

1. Nell'amministrazione vai su Extensions > Installer, fai clic su Upload e scegli il file vfd_packeta.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 Packeta, fai clic su Install (il pulsante verde +), poi su Edit (il pulsante con la matita).

4. Inserisci la chiave di licenza, la chiave API e i prezzi 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 il metodo è disattivato finché non attivi Enable/Disable e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni Packeta che hai conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox Packeta > 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.

Il metodo viene offerto solo per i paesi della rete propria di punti di ritiro di Packeta: CZ, SK, HU e RO. Sopra le impostazioni la pagina mostra il risultato della verifica della chiave API e avvisi sui problemi: nessuna chiave API, nessun prezzo, paesi selezionati al di fuori della rete Packeta oppure un'unità di peso del negozio che l'estensione non riconosce. Gli avvisi vengono aggiornati dopo ogni salvataggio.

Tutti i prezzi e i limiti accettano la virgola o il punto come separatore decimale (4,99 o 4.99). Un numero non valido o negativo viene rifiutato con un messaggio e viene mantenuto il valore precedente di quel campo; gli altri campi vengono salvati.

Generale

Enable/Disable: attiva o disattiva Packeta nel checkout. Predefinito: disattivato.

Name: il nome del metodo di spedizione mostrato al cliente. Predefinito: Packeta pickup point. Obbligatorio, massimo 64 caratteri.

API key: la tua chiave API di Packeta da client.packeta.com > Client support. Puoi anche incollare la password API di 32 caratteri: vengono salvati solo i primi 16 caratteri, che costituiscono la chiave API. La chiave API è pubblica: viene inviata al browser del cliente per aprire il widget. Quando salvi una nuova chiave, viene verificata con il feed dei corrieri di Packeta e la pagina mostra Packeta API key verified oppure indica che Packeta l'ha rifiutata. Se la verifica non può essere eseguita, la chiave viene salvata e verificata di nuovo al salvataggio successivo.

Widget language: la lingua del widget dei punti di ritiro. Store / visitor language (predefinito) segue la lingua della pagina. Puoi anche fissarla su ceco, slovacco, ungherese, rumeno, inglese, tedesco, polacco o ucraino.

Pickup point types: quali punti Packeta offre il widget.

Tax status: la classe fiscale di OpenCart applicata al prezzo di spedizione, oppure None (no tax on shipping) (predefinito).

Sort order: la posizione di Packeta tra i metodi di spedizione nel checkout. Un numero intero.

Prezzi

Packeta non dispone di un'API pubblica per le tariffe. I prezzi provengono da questa tabella e vengono inseriti nella valuta predefinita del tuo negozio, IVA esclusa. I clienti che pagano in un'altra valuta vedono il prezzo convertito.

Calculation type: Per order (predefinito) addebita il prezzo una sola volta. Per item (price x quantity) lo moltiplica per la quantità di prodotti che richiedono spedizione.

Country prices: un prezzo per paese di destinazione e per peso del pacco. Fai clic su Add country per aggiungere una riga e sul pulsante × per rimuoverla. Ogni riga ha un Price e colonne di peso: XS fino a 1 kg, S da 1 a 2 kg, M da 2 a 3 kg, L da 3 a 5 kg e XL oltre 5 kg. Una colonna di peso lasciata a 0 usa la colonna Price. La riga * Default viene usata per i paesi che non hanno una riga propria. Una nuova riga parte come * Default con tutti i prezzi a 0, il che significa spedizione gratuita. Scegli il paese e inserisci i prezzi prima di salvare, oppure rimuovi la riga. Se lo stesso paese (o * Default) compare in due righe, al salvataggio ne viene mantenuta solo la prima. Se un valore della tabella non è un numero uguale o maggiore di 0, la tabella non viene salvata e la pagina elenca i valori errati.

Fallback cost: viene usato quando la tabella dei paesi non ha una riga per la destinazione né una riga * Default. Lascialo vuoto per non offrire il metodo in quel caso.

Free shipping from: il subtotale del carrello (dopo il coupon, IVA esclusa) a partire dal quale la spedizione Packeta è gratuita. Viene verificato prima della tabella dei prezzi: da questo importo la spedizione è gratuita in ogni paese Packeta in cui il metodo è offerto, anche in uno senza riga paese o costo di riserva. Lascialo vuoto per non offrire mai la spedizione gratuita.

Disponibilità

Minimum weight (kg): nasconde il metodo quando il carrello pesa meno. I pesi dei prodotti vengono convertiti dalle loro classi di peso di OpenCart. Vuoto o 0 significa nessun limite.

Maximum weight (kg): nasconde il metodo quando il carrello pesa di più. Predefinito: 15. I punti di ritiro e le Z-BOX di Packeta di solito accettano pacchi fino a 15 kg; verifica il tuo contratto con Packeta. Vuoto o 0 significa nessun limite. Un peso minimo superiore a quello massimo viene rifiutato al salvataggio e vengono mantenuti entrambi i valori precedenti.

Minimum cart subtotal: offri il metodo solo quando il subtotale del carrello (dopo il coupon, IVA esclusa) raggiunge questo importo.

Geo zone: offri Packeta solo per gli indirizzi di questa zona geografica. All zones (predefinito) significa nessun limite. 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 il metodo viene offerto per i paesi selezionati sotto. Quando è disattivo (predefinito), viene offerto solo nella zona geografica indicata sopra.

Countries (ignore zones mode): i paesi di destinazione per questa modalità. Lascialo vuoto per usare tutti i paesi Packeta. I paesi al di fuori della rete di punti di ritiro Packeta vengono ignorati. Questo campo viene usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: scrive i calcoli delle tariffe e le scelte dei punti di ritiro in storage/logs/vfd_pckt_debug.log.php. Il file non può essere letto dal web. Non vengono registrati dati personali dei clienti né la chiave API. Gli errori e le verifiche della chiave API non riuscite vengono sempre registrati. Disattiva il registro quando hai finito. Quando il file raggiunge 5 MB, viene spostato in vfd_pckt_debug.old.log.php e ne viene avviato uno nuovo.

Log (last lines): 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 e il registro. Quando è disattivo (predefinito), le impostazioni vengono conservate per una reinstallazione. Il punto di ritiro salvato negli ordini viene sempre conservato.

Importazione / Esportazione

Esportazione: fai clic su Download JSON per salvare le impostazioni in un file JSON, inclusa la chiave API, che è pubblica.

Importazione: 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.

Come funziona nel checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di Packeta. Se è impostata una Geo zone (e Ignore shipping zones è disattivo) e l'indirizzo si trova al di fuori di essa, Packeta non viene offerto. 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 le condizioni: paese di consegna nella rete Packeta, chiave API, elenco dei paesi in modalità ignora zone, peso del carrello e subtotale minimo del carrello. Il subtotale è il prezzo dei prodotti che richiedono spedizione, dopo lo sconto del coupon e senza IVA. Buoni regalo, punti fedeltà e credito del negozio non vengono considerati. Se si applica la spedizione gratuita, il prezzo è 0. Altrimenti il prezzo proviene dalla tabella dei paesi, poi dal costo di riserva. Se non c'è un prezzo, il metodo viene nascosto. Il prezzo viene mostrato al cliente nella sua valuta, con l'IVA della Tax status selezionata.

Sotto l'opzione Packeta della fase del metodo di spedizione c'è il pulsante Choose pickup point. Apre nel browser del cliente il widget ufficiale di Packeta con il paese di destinazione, il peso del carrello, i tipi di punto scelti e la lingua del widget. Dopo che il cliente ha scelto un punto, il suo nome e il suo indirizzo vengono mostrati sotto il metodo e il pulsante cambia in Change pickup point. Il punto viene salvato per la sessione di checkout e rimane quando la pagina viene ricaricata. Un punto scelto per un altro paese non viene usato se l'indirizzo di consegna passa a un altro paese.

Durante il checkout il tuo server non richiede nulla a Packeta. Lo script del widget viene caricato da widget.packeta.com, solo nella pagina del checkout. Se viene bloccato (da un blocco pubblicità o privacy, da una politica di sicurezza dei contenuti o da un'interruzione di Packeta), il cliente vede il messaggio "The Packeta pickup point widget could not be loaded. Please reload the page or choose another shipping method."

Le tariffe Packeta non vengono richieste in tempo reale; provengono dalla tua tabella. L'estensione non crea spedizioni Packeta, non stampa etichette né traccia i pacchi, e non offre consegna a domicilio né punti di ritiro di corrieri partner di serie. Comunica l'ID del punto di ritiro dell'ordine a Packeta nel modo che usi di solito, per esempio tramite importazione in client.packeta.com. Il pulsante del punto di ritiro funziona con il checkout standard di OpenCart del tema predefinito.

Su OpenCart 4 il cliente fa clic su Choose nel blocco del metodo di spedizione della pagina di checkout e sceglie Packeta nella finestra Shipping method options. Il pulsante Choose pickup point e il punto scelto compaiono in quella finestra, sotto l'opzione Packeta, e il widget Packeta si apre sopra di essa. I prezzi sono gli stessi di OpenCart 3.

Punti di ritiro

Il punto di ritiro è obbligatorio. Se il cliente fa clic su Continue nella fase del metodo di spedizione senza sceglierne uno, la fase non viene completata e il cliente vede il messaggio "Please choose a Packeta pickup point." Se il punto scelto si trova in un paese diverso da quello dell'indirizzo di consegna, il cliente vede "The selected Packeta pickup point is not in your shipping country. Please choose a pickup point again." L'estensione non verifica l'ID del punto con Packeta; controlla solo che sia stato scelto un punto e che il suo paese corrisponda.

Il punto viene associato all'ordine quando questo viene creato:

Metodo di spedizione dell'ordine: il nome e l'indirizzo del punto vengono aggiunti al nome del metodo, per esempio Packeta pickup point: <point> (fino a 128 caratteri). Il cliente lo vede nello storico dell'ordine e nell'e-mail dell'ordine, ed è stampato in fattura. La pagina di conferma dell'ordine di OpenCart non mostra il metodo di spedizione.

Pagina dell'ordine nell'amministrazione: apri l'ordine in Sales > Orders. Un riquadro Packeta pickup point mostra nome e indirizzo, il Pickup point ID e il paese. Se un ordine Packeta non ha un punto, il riquadro indica "No pickup point was selected for this order."

Su OpenCart 4 il pulsante Continue della finestra Shipping method options non procede senza un punto, 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. Il riquadro Packeta pickup point della pagina dell'ordine nell'amministrazione è mostrato sopra la sezione History.

Il punto viene memorizzato nella tabella propria dell'estensione, vfd_pckt_point (sessione di checkout, ordine, ID del punto, nome e indirizzo, paese).

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza License — VibeFox Packeta è il primo blocco di Extensions > Extensions > Shipping > VibeFox Packeta > Edit, sopra le impostazioni. Incolla la chiave in License key e fai clic su Activate. Dopo, 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-packeta 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 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 nella 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, Packeta non viene mostrato ai clienti nel checkout e non viene calcolata alcuna tariffa. Un utente amministratore che ha effettuato l'accesso al pannello di amministrazione nello stesso browser vede comunque il metodo nel negozio, contrassegnato 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 il metodo è nascosto 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

Packeta non compare nel checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che la API key sia inserita e che il paese di consegna sia CZ, SK, HU o RO. Verifica che sia impostato un prezzo per il paese (riga del paese, riga * Default oppure Fallback cost), i limiti di peso e di subtotale, e Geo zone (oppure Ignore shipping zones e i suoi paesi). Verifica che i prodotti abbiano Requires Shipping impostato su Yes. La pagina delle impostazioni elenca in alto i problemi di configurazione. Attiva Debug log per vedere il motivo in Log (last lines).

Packeta ha rifiutato la chiave API: copia di nuovo la chiave API da client.packeta.com > Client support e salva. Fino ad allora il widget non può aprirsi nel checkout.

Il widget non si apre: lo script di Packeta è bloccato da un blocco pubblicità o privacy, da una politica di sicurezza dei contenuti oppure da un'interruzione di Packeta. Consenti widget.packeta.com nella tua politica di sicurezza dei contenuti.

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

I limiti di peso o le colonne di peso sembrano errati: se la pagina segnala l'unità di peso del negozio, usa le classi di peso con unità kg, g, lb oppure oz e imposta la classe di peso predefinita in System > Settings, scheda Local. Le altre unità vengono lette come chilogrammi.

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

Per gli sviluppatori: altre estensioni possono aggiungere paesi, passare al widget opzioni come gli ID dei corrieri, cambiare l'URL dello script del widget o la sua lingua con gli eventi di OpenCart vfd_packeta/countries, vfd_packeta/widget_options, vfd_packeta/widget_url e vfd_packeta/widget_language (trigger con il prefisso catalog/, per esempio catalog/vfd_packeta/widget_options).

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e fai clic su Uninstall (il pulsante rosso −) accanto a VibeFox Packeta. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable/Disable, Sort order, Tax status e Geo zone. La verifica salvata della chiave API viene sempre rimossa, e il pulsante del punto di ritiro e il riquadro dell'ordine non vengono più mostrati. Se Remove data on uninstall è attivo, vengono eliminati le impostazioni, il registro e i punti di ritiro 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 sempre il punto di ritiro salvato e il punto nel loro metodo di spedizione.

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 Packeta nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per eliminare il pacchetto caricato.

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