VibeFox Packeta 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 Packeta: la trovi nella sezione clienti di Packeta (client.packeta.com), sotto Client support. Ha 16 lettere e cifre. Il widget ne ha bisogno per aprirsi nel checkout, quindi il metodo viene mostrato ai clienti solo dopo l'inserimento della chiave API.
Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un 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_packeta in /wp-content/plugins/ via FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox Packeta, 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. Inserisci la tua API key Packeta e i prezzi: almeno una riga di Country prices (per esempio * Default) oppure un Fallback cost. Salva. La pagina indica se Packeta ha accettato la chiave.
6. Aggiungi VibeFox Packeta alle tue zone di spedizione per Repubblica Ceca, Slovacchia, Ungheria o Romania in WooCommerce > Settings > Shipping > Shipping zones, oppure attiva Ignore shipping zones.
Configurazione
Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox Packeta. Si applicano a tutte le zone di spedizione. Quando aggiungi il metodo a una zona, la finestra della zona contiene un solo campo:
Title (zone): il nome che i clienti vedono in questa zona. Lascialo vuoto per usare il Name globale.
Il metodo viene proposto solo per i paesi della rete di punti di ritiro propria di Packeta: CZ, SK, HU e RO. Sopra le impostazioni la pagina mostra il risultato della verifica della chiave API e avvisi sui problemi, per esempio chiave API mancante, prezzo mancante o paesi selezionati al di fuori della rete Packeta.
Tutti i prezzi e i limiti accettano la virgola o il punto come separatore decimale (4,99 o 4.99). Un numero non valido viene rifiutato con un messaggio e viene mantenuto il valore precedente.
Generale
Enable/Disable: attiva o disattiva il metodo in tutte le zone contemporaneamente.
Name: il nome del metodo di spedizione mostrato al cliente. Una zona può sostituirlo con un proprio Title. Predefinito: Packeta pickup point.
API key: la tua chiave API Packeta da client.packeta.com > Client support. Puoi anche incollare la password API di 32 caratteri: vengono salvati solo i primi 16 caratteri, cioè 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 che Packeta l'ha rifiutata. Se la verifica non può essere eseguita, la chiave viene salvata e verificata di nuovo la volta successiva che salvi.
Widget language: la lingua del widget dei punti di ritiro. Store / visitor language (predefinito) segue la lingua della pagina. Puoi anche impostarla fissa su ceco, slovacco, ungherese, rumeno, inglese, tedesco, polacco o ucraino.
Pickup point types: quali punti Packeta propone il widget.
Tax status: Taxable aggiunge l'imposta di WooCommerce al costo di spedizione, None non la aggiunge.
Prezzi
Packeta non dispone di un'API pubblica per le tariffe. I prezzi provengono da questa tabella e vengono inseriti nella valuta del negozio.
Calculation type: Per order addebita il prezzo una sola volta. Per item (price x quantity) lo moltiplica per il numero di articoli spedibili nel carrello.
Country prices: un prezzo per paese di destinazione e per peso del pacco. Fai clic su + Add country per aggiungere una riga e sulla croce per rimuoverla. Ogni riga ha un Price e colonne di peso: XS fino a 1 kg, S 1–2 kg, M 2–3 kg, L 3–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 senza 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 compare in due righe, al salvataggio viene mantenuta solo la prima.
Fallback cost: usato quando la tabella dei paesi non ha una riga per la destinazione e non esiste una riga * Default. Lascialo vuoto per non proporre il metodo in quel caso.
Free shipping from: il subtotale del carrello (dopo gli sconti, senza imposte) a partire dal quale la spedizione Packeta è gratuita. Si applica solo dove è impostato un prezzo: una riga di paese, la riga * Default o il costo di ripiego. Lascialo vuoto per non proporre mai la spedizione gratuita.
Disponibilità
Minimum weight (kg): nasconde il metodo quando il carrello pesa meno. Il peso del carrello viene convertito dall'unità di peso del tuo negozio. 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 i Z-BOX Packeta di solito accettano pacchi fino a 15 kg; verifica il tuo contratto con Packeta. Vuoto o 0 significa nessun limite.
Minimum cart subtotal: propone il metodo solo quando il subtotale del carrello (dopo gli sconti, senza imposte) raggiunge questo importo.
Excluded shipping classes: nasconde il metodo quando il carrello contiene un prodotto di una di queste classi di spedizione di WooCommerce.
Ignore shipping zones: se attivo, il metodo viene proposto per i paesi selezionati qui sotto, anche se non è aggiunto alla zona di spedizione corrispondente. Se disattivo, viene proposto solo nelle zone a cui è stato aggiunto.
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 WooCommerce > Status > Logs (origine «vfd-packeta»). Non vengono registrati dati personali dei clienti né la chiave API. I controlli falliti della chiave API vengono sempre registrati. Disattiva il registro quando hai finito.
Remove data on uninstall: se attivo, eliminando il plugin vengono rimosse le impostazioni e le istanze di zona di questo metodo. Disattivare il plugin non elimina mai nulla. Il punto di ritiro salvato negli ordini viene sempre conservato.
Come funziona nel checkout
Quando il cliente inserisce un indirizzo di consegna, WooCommerce chiede al plugin una tariffa. Il plugin verifica le condizioni: paese di consegna nella rete Packeta, chiave API, peso del carrello, subtotale minimo del carrello e classi di spedizione escluse. Il prezzo proviene dalla tabella dei paesi, poi dal costo di ripiego. Se non c'è un prezzo, il metodo viene nascosto. Se si applica la spedizione gratuita, il cliente vede il metodo senza costi.
Quando il cliente seleziona il metodo Packeta, sotto di esso compare 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 l'indirizzo vengono mostrati sotto il metodo e il pulsante diventa Change pickup point. La scelta viene ricordata nella sessione del cliente quando il checkout si aggiorna o la pagina viene ricaricata.
Il tuo server non richiede nulla a Packeta durante il checkout. Lo script del widget viene caricato da widget.packeta.com. Se viene bloccato (da un blocco pubblicità o privacy, da una content security policy 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.»
Il metodo funziona nel checkout classico e nei blocchi Carrello e Checkout. È compatibile con l'archiviazione ad alte prestazioni degli ordini di WooCommerce (HPOS).
I prezzi Packeta non vengono richiesti in tempo reale; provengono dalla tua tabella. Il plugin non crea spedizioni Packeta, non stampa etichette e non traccia i pacchi, e non offre la consegna a domicilio né i punti di ritiro di corrieri partner di serie. Consegna l'ID del punto di ritiro dell'ordine a Packeta nel modo che usi di solito, per esempio con un'importazione in client.packeta.com.
Punti di ritiro
Il punto di ritiro è obbligatorio. Se il cliente effettua l'ordine senza sceglierne uno, il checkout si blocca con il messaggio «Please choose a Packeta pickup point.». Se il punto scelto si trova in un paese diverso da quello dell'indirizzo di spedizione, il checkout si blocca con il messaggio «The selected Packeta pickup point is not in your shipping country. Please choose a pickup point again.». Entrambi i controlli vengono eseguiti sul server, sia nel checkout classico sia in quello a blocchi. Il plugin non verifica l'ID del punto presso Packeta; controlla solo che sia stato scelto un punto e che il suo paese corrisponda.
Il punto viene salvato con l'ordine al momento della sua creazione:
Schermata dell'ordine in amministrazione: Packeta pickup point con nome, indirizzo, Pickup point ID e paese, sotto l'indirizzo di spedizione. Se un ordine Packeta non ha un punto, la schermata indica «No pickup point was selected for this order.».
Pagina di ringraziamento e visualizzazione dell'ordine: Packeta pickup point: con nome e indirizzo.
E-mail dell'ordine: nome e indirizzo del punto nelle e-mail HTML e in testo semplice. Le e-mail per l'amministratore includono anche il Pickup point ID.
Nel database il punto è memorizzato nei metadati dell'ordine _vfd_pckt_point_id, _vfd_pckt_point_name (nome e indirizzo) e _vfd_pckt_point_country.
Chiave di licenza
Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Shipping > VibeFox Packeta. 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 verificare 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 dominio. Rimuovere la chiave da un sito 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. I gestori del negozio che hanno effettuato l'accesso 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 il rinnovo. Lo stato viene verificato di nuovo automaticamente in background.
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 destinazione sia CZ, SK, HU o RO. Controlla che sia impostato un prezzo per il paese (riga del paese, riga * Default o Fallback cost), i limiti di peso e subtotale, Excluded shipping classes, e che il metodo sia aggiunto alla zona corrispondente (oppure che Ignore shipping zones sia attivo). La pagina delle impostazioni elenca in alto i problemi di configurazione. Attiva Debug log per vedere il motivo in WooCommerce > Status > Logs.
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 content security policy o da un'interruzione di Packeta. Consenti widget.packeta.com nella tua content security policy. Gli sviluppatori possono cambiare l'URL dello script con il filtro vfd_pckt_widget_url.
La spedizione è gratuita per errore: controlla in Country prices le righe con un Price di 0, soprattutto una riga * Default aggiunta con + Add country e lasciata vuota.
Altri paesi o corrieri: di serie il metodo funziona per CZ, SK, HU e RO. Gli sviluppatori possono aggiungere paesi con il filtro vfd_pckt_countries e passare al widget gli ID dei corrieri con il filtro vfd_pckt_widget_options.
Il blocco 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 conserva tutti i dati. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi, insieme alla verifica della chiave API salvata. Le impostazioni e i metodi di zona vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano disponibili per una reinstallazione successiva. Gli ordini esistenti conservano le loro righe di spedizione e il punto di ritiro salvato.
Packeta è un marchio del rispettivo titolare. Questo plugin non è affiliato né approvato da Packeta.