VibeFox Delhivery for WooCommerce — Guida
Requisiti
WordPress: 5.8 o successivo.
WooCommerce: 5.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.
PHP: 8.0 o successivo.
Token API Delhivery (solo per le tariffe in tempo reale): accedi a Delhivery One e apri Settings > API setup. L'articolo di aiuto di Delhivery «API token generation» spiega i passaggi. I token di test funzionano con l'ambiente di staging. Ti serve anche il codice PIN a 6 cifre del tuo punto di ritiro. Se usi solo i prezzi fissi, non ti serve un token.
Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un solo 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_delhivery in /wp-content/plugins/ tramite FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox Delhivery, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugin.
4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.
5. Inserisci il token API e il tuo codice PIN di partenza, scegli Express o Surface e Pre-paid o COD. Se la valuta del tuo negozio non è INR, inserisci il tasso di conversione. Facoltativamente, inserisci i prezzi fissi (vedi Configurazione).
6. Aggiungi VibeFox Delhivery a una zona di spedizione (per esempio India) in WooCommerce > Settings > Shipping > Shipping zones, oppure attiva Ignore zones e scegli i paesi.
Configurazione
Tutte le impostazioni sono in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox Delhivery. Si applicano a tutte le zone di spedizione. Quando aggiungi il metodo a una zona, la finestra della zona ha un solo campo:
Title (zone): il nome che il cliente vede per questa zona. Lascialo vuoto per usare il Method title globale.
Ogni volta che salvi le impostazioni, le tariffe Delhivery in cache vengono cancellate. Prezzi e importi accettano «9.99» e «9,99».
Generale
Enable/Disable: attiva o disattiva il metodo in tutte le zone contemporaneamente.
Method title: il nome del metodo di spedizione mostrato al checkout. Predefinito: Delhivery. Una zona può sostituirlo con il proprio Title.
Tax status: Taxable aggiunge l'imposta di WooCommerce al costo di spedizione, None non la aggiunge.
Account API Delhivery (necessario solo per le tariffe in tempo reale)
Environment: Production (track.delhivery.com) (predefinito) oppure Staging / test account (staging-express.delhivery.com). Usa Staging solo con un token di test Delhivery.
API token: il tuo token API Delhivery. Viene inviato solo nell'header di autorizzazione e non viene mai scritto nei log.
Origin pincode: il codice PIN a 6 cifre del tuo punto di ritiro o magazzino, per esempio 110001.
Tariffe in tempo reale
Una tariffa in tempo reale viene richiesta per destinazioni indiane con un codice PIN a 6 cifre valido, per una spedizione diretta (consegnata).
Shipping mode: la modalità di fatturazione Delhivery usata per la tariffa: Express (predefinito) oppure Surface.
Payment type: il tipo di pagamento inviato a Delhivery: Pre-paid (predefinito) oppure COD (pagamento alla consegna; Delhivery aggiunge il proprio costo COD). Il plugin non lo cambia in base al metodo di pagamento scelto dal cliente.
Rate amount: Delhivery restituisce l'importo con e senza GST.
INR to (store currency) conversion rate: le tariffe Delhivery sono in rupie indiane. Se la valuta del tuo negozio non è INR, inserisci quante unità della tua valuta vale una rupia, per esempio 0.011. Se lo lasci vuoto, le tariffe in tempo reale non vengono usate, si applicano i prezzi fissi e sopra le impostazioni compare un avviso. Non serve se la valuta del negozio è INR.
Prezzi fissi (usati quando non c'è una tariffa in tempo reale)
I prezzi fissi vengono usati quando non c'è ancora un token o un codice PIN, quando la destinazione è fuori dall'India, quando il codice PIN non è servito o quando l'API restituisce un errore. Sono nella valuta del tuo negozio.
Prices per country: uno per riga, nel formato COUNTRY_CODE:price, per esempio IN:120. Viene controllato prima del prezzo di riserva.
Fallback price: usato quando non si applica né una tariffa in tempo reale né un prezzo per paese. Lascialo vuoto per nascondere il metodo. 0 significa gratis.
Fixed price is charged: Per order addebita il prezzo una sola volta. Per item (price × quantity) lo moltiplica per il numero di articoli nel carrello. Una tariffa Delhivery in tempo reale è sempre riferita al peso totale del pacco.
Condizioni
Free shipping from: la spedizione è gratuita se il subtotale del carrello è almeno pari a questo importo. Non viene inviata alcuna richiesta a Delhivery. Lascialo vuoto per disattivarlo.
Show from subtotal: mostra il metodo solo se il subtotale del carrello è almeno pari a questo importo. Lascialo vuoto per mostrarlo sempre.
Min weight (kg): il peso minimo del carrello per mostrare il metodo. 0 significa nessun limite.
Max weight (kg): nasconde il metodo se il carrello è più pesante. Predefinito: 30. 0 significa nessun limite.
I pesi dei prodotti vengono convertiti in kg dall'unità di peso del tuo negozio. La tariffa usa il peso effettivo del carrello (la somma dei pesi dei prodotti), senza peso volumetrico né scatole.
Excluded shipping classes: nasconde il metodo se un articolo del carrello appartiene a una di queste classi di spedizione di WooCommerce.
Disponibilità senza zone di spedizione
Ignore zones: offre Delhivery senza aggiungerlo a una zona di spedizione, per i paesi indicati qui sotto.
Countries: i paesi di destinazione per questa modalità. Lascialo vuoto per usare tutti i paesi in cui spedisci. Viene usato solo quando Ignore zones è attivo.
Avanzate
Debug log: registra i calcoli delle tariffe in WooCommerce > Status > Logs, origine vfd_delhivery. Gli errori dell'API vengono sempre registrati, anche quando questa opzione è disattivata. Token e codici PIN completi dei clienti non vengono mai registrati.
Remove data on uninstall: se attivo, eliminando il plugin vengono rimosse tutte le sue impostazioni, i metodi di zona e le tariffe in cache. La disattivazione del plugin non cancella mai nulla.
Come funziona al checkout
Quando il cliente inserisce un indirizzo di spedizione, WooCommerce chiede una tariffa al plugin. Il plugin controlla prima il peso del carrello, il subtotale e le classi di spedizione escluse. Se si applica la spedizione gratuita, il cliente ottiene la consegna gratuita e non viene inviata alcuna richiesta a Delhivery.
Per un indirizzo indiano con un codice PIN a 6 cifre valido, il plugin invia a Delhivery i codici PIN di partenza e di destinazione, il peso del carrello in grammi, la modalità di spedizione e il tipo di pagamento, e mostra l'importo restituito convertito nella valuta del tuo negozio. Ogni risposta viene memorizzata nella cache per 1 ora. Una richiesta non riuscita viene memorizzata per 10 minuti, così il checkout non attende Delhivery a ogni aggiornamento. Il timeout dell'API è di 10 secondi.
Se non c'è una tariffa in tempo reale, si usa il prezzo del paese o il prezzo di riserva. Se non è impostato nessuno dei due, il metodo viene nascosto. Il cliente non vede mai un errore dell'API.
Il metodo funziona con il checkout classico e con i blocchi Carrello e Checkout. È compatibile con l'archiviazione degli ordini ad alte prestazioni di WooCommerce (HPOS).
Il plugin calcola le tariffe e mostra un link di tracciamento. Non crea spedizioni o lettere di vettura, non stampa etichette, non richiede ritiri o manifesti, non verifica la copertura dei codici PIN, non stima le date di consegna, non sincronizza gli stati di tracciamento e non quota le tariffe internazionali di Delhivery. Fuori dall'India si usano solo i prezzi fissi.
Ordini e tracciamento
Nella schermata dell'ordine, sotto l'indirizzo di spedizione, il blocco Delhivery mostra la modalità di spedizione (Express o Surface) e l'origine del prezzo: tariffa Delhivery in tempo reale, prezzo fisso o soglia di spedizione gratuita.
Crea la spedizione in Delhivery One, poi incolla il suo AWB nel campo Delhivery AWB / tracking number e salva l'ordine. Nell'area admin compare un link Track on delhivery.com. Il cliente vede Delhivery tracking con un link nella pagina dell'ordine in Il mio account e nelle email d'ordine (HTML e testo semplice). L'AWB viene salvato prima dello stato dell'ordine, quindi l'email «Ordine completato» lo include già se completi l'ordine nello stesso salvataggio.
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 Delhivery. 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 ricontrollare 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 solo dominio. Rimuovere la chiave da un sito non libera il suo posto sul dominio. Liberalo dal tuo account vibefox.net.
Senza una chiave attiva, Delhivery non viene mostrato ai clienti al checkout. Gli amministratori del negozio connessi lo vedono ancora, contrassegnato come (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 ricontrollato automaticamente in background.
Risoluzione dei problemi
Delhivery non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che il metodo sia aggiunto alla zona del paese del cliente (oppure che Ignore zones sia attivo e il paese sia consentito). Controlla i limiti di peso, Show from subtotal ed Excluded shipping classes. Senza una tariffa in tempo reale serve un prezzo per paese o un Fallback price.
Le tariffe in tempo reale non compaiono: verifica il token API, un Origin pincode valido e, in un negozio con valuta diversa da INR, il tasso di conversione. Il cliente deve inserire un codice PIN indiano valido a 6 cifre. Attiva Debug log e apri WooCommerce > Status > Logs, origine vfd_delhivery, per vedere gli errori dell'API, per esempio un codice PIN non servito.
Il GST viene applicato due volte: l'importo totale di Delhivery include già il GST. Imposta Rate amount su Gross amount (excluding GST) oppure Tax status su None.
Test: usa Environment Staging con un token di test Delhivery.
Le tariffe sembrano obsolete dopo una modifica: salva la pagina delle impostazioni. Questo cancella le tariffe Delhivery in cache.
Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera un posto 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. Impostazioni, metodi di zona e tariffe in cache vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano per una successiva reinstallazione. I numeri AWB restano negli ordini e gli ordini esistenti mantengono le proprie righe di spedizione.
Delhivery è un marchio registrato del rispettivo titolare. Questo plugin non è affiliato a Delhivery né approvato da Delhivery.