VibeFox Delhivery for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni precedenti di PHP.

Token API di 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. Entrambi i link si trovano nella pagina del modulo. 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 prezzi fissi, non ti serve un token.

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un dominio.

Installazione

1. Nel back office vai su Modules > Module Manager e fai clic su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, fai clic su Configure oppure trova più tardi VibeFox Delhivery nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la chiave di licenza VibeFox in License key nel blocco licenza in cima alla pagina Configure e fai clic su Activate (vedi Chiave di licenza).

4. Inserisci il token API e il codice PIN di partenza, scegli Express o Surface e Pre-paid o COD. Se la valuta predefinita del tuo negozio non è INR, inserisci il tasso di cambio. Facoltativamente, inserisci i prezzi fissi (vedi Configurazione). Fai clic su Save.

All'installazione il modulo crea il corriere Delhivery con il testo del tempo di consegna Courier delivery (India) e la pagina di tracciamento di Delhivery come URL di tracciamento. Il corriere viene assegnato a tutte le zone e a tutti i gruppi di clienti. Zone, gruppi di clienti, tempo di consegna, logo e limiti di dimensione puoi modificarli in Shipping > Carriers. Non impostare lì i prezzi: il prezzo proviene sempre dal modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Delhivery > Configure. Valgono per tutte le zone. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella anche le tariffe Delhivery in cache. Gli importi accettano «9.99» e «9,99». Se un campo numerico non contiene un numero non negativo, viene mostrato un errore e non si salva nulla.

Se la valuta predefinita del tuo negozio non è INR, è salvato un token API e non è impostato alcun tasso di cambio, un avviso sopra il modulo ricorda che le tariffe in tempo reale non vengono usate finché non inserisci il tasso. Se l'unità di peso del tuo negozio non è una delle unità standard (kg, g, lb o oz), un avviso ti chiede di impostarla in International > Localization (Local units), perché altrimenti i pesi dei prodotti vengono letti come chilogrammi.

Generale

Enable Delhivery: attiva o disattiva il corriere. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.

Method title: il nome del corriere mostrato nel carrello e al checkout. Predefinito: Delhivery. Obbligatorio, massimo 64 caratteri.

Tax: la regola fiscale del corriere, oppure No tax. Con una regola, PrestaShop aggiunge l'imposta al costo di spedizione.

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 di Delhivery.

API token: il tuo token API di Delhivery. Viene inviato solo nell'intestazione di autorizzazione e non viene mai scritto nei log. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.

Remove saved token: attiva e salva per eliminare il token salvato. Da quel momento si usano solo i prezzi fissi.

Origin pincode: il codice PIN a 6 cifre del tuo punto di ritiro o magazzino, per esempio 110001. Se non ha 6 cifre, viene mostrato un avviso e le tariffe in tempo reale non vengono richieste finché non è corretto.

Tariffe in tempo reale

Una tariffa in tempo reale viene richiesta per le destinazioni indiane con un codice PIN valido a 6 cifre, per una spedizione diretta (consegna).

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 (cash on delivery — Delhivery adds its COD charge). Il modulo non lo cambia in base al metodo di pagamento scelto dal cliente.

Rate amount: Delhivery restituisce l'importo con e senza GST.

INR to (shop currency) conversion rate: l'etichetta mostra la valuta predefinita del tuo negozio. Le tariffe di Delhivery sono in rupie indiane. Se la valuta predefinita non è INR, inserisci quante unità della tua valuta vale una rupia, per esempio 0.011. Il tasso deve essere maggiore di 0. Se lo lasci vuoto, le tariffe in tempo reale non vengono usate e si applicano i prezzi fissi. Non serve se la valuta predefinita è INR.

Prezzi fissi (usati quando non è disponibile una tariffa in tempo reale)

I prezzi fissi si usano quando non c'è ancora un token o un codice PIN, quando la destinazione è al di fuori dell'India, quando il codice PIN non è servito o quando l'API restituisce un errore. Sono espressi nella valuta predefinita del tuo negozio, IVA esclusa.

Prices per country: uno per riga, nel formato COUNTRY_CODE:price, per esempio IN:120. Vengono verificati prima del prezzo di riserva. Le righe in un altro formato vengono eliminate al salvataggio e un avviso le elenca.

Fallback price: usato quando non si applicano né una tariffa in tempo reale né un prezzo per paese. Lascialo vuoto per nascondere il corriere. 0 significa gratuito.

Fixed price is charged: Per order applica il prezzo una sola volta. Per item (price × quantity) lo moltiplica per il numero di articoli nel carrello. Una tariffa Delhivery in tempo reale riguarda sempre il peso totale del pacco.

Condizioni

Free shipping from: la consegna è gratuita se il subtotale del carrello (prodotti che richiedono spedizione, dopo gli sconti, prima delle tasse) è almeno di questo importo. Non viene inviata alcuna richiesta a Delhivery. Lascia vuoto per disattivare.

Show from subtotal: mostra il corriere solo se il subtotale del carrello è almeno di questo importo. Lascia vuoto per mostrarlo sempre.

Min weight: il peso minimo del carrello in kg per mostrare il corriere. 0 significa nessun limite.

Max weight: nasconde il corriere se il carrello è più pesante, in kg. Predefinito: 30. 0 significa nessun limite, un campo vuoto significa 30 kg. Min weight non può essere maggiore di Max weight: la pagina mostra un errore e non salva nulla.

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.

Disponibilità senza zone di spedizione

Ignore zones: quando è disattivata, i paesi sono definiti dalle zone del corriere in Shipping > Carriers. Quando è attivata, il corriere viene collegato a tutte le zone (anche a quelle che creerai in seguito) e offerto per i paesi indicati sotto. Disattivandola, il corriere riottiene le sue zone precedenti.

Countries: i paesi di destinazione per quella modalità, scelti tra i tuoi paesi attivi. Lascia vuoto per usare tutti i paesi verso cui spedisci. Usato solo quando Ignore zones è attivata.

Avanzate

Debug log: scrive i calcoli delle tariffe in logs/vfd_dlv_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori dell'API vengono sempre registrati, anche quando questa opzione è disattivata. Token e codici PIN completi dei clienti non vengono mai registrati.

Log: mostra la dimensione e gli ultimi inserimenti del log. Fai clic su Clear log per svuotarlo.

Remove data on uninstall: quando è attivata, la disinstallazione del modulo elimina le impostazioni Delhivery, il corriere, le tariffe in cache, i dati degli ordini e i log. Quando è disattivata, tutto viene conservato per una reinstallazione. I numeri AWB degli ordini non vengono mai eliminati.

Come funziona al checkout

Nel passaggio di spedizione PrestaShop chiede al modulo il prezzo Delhivery. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nel subtotale. Il modulo controlla prima i paesi (quando Ignore zones è attivata), il peso del carrello e Show from subtotal. Se si applica la spedizione gratuita, il prezzo è 0 e non viene inviata alcuna richiesta a Delhivery.

Per un indirizzo indiano con un codice PIN valido a 6 cifre, il modulo 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. L'importo restituito viene convertito da INR nella valuta predefinita del tuo negozio e poi mostrato nella valuta del carrello del cliente. Ogni risposta viene memorizzata nella cache per 1 ora. Una richiesta non riuscita viene memorizzata nella cache 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 corriere viene nascosto. Il cliente non vede mai un errore dell'API. Il motivo viene scritto nel log.

Se modifichi il corriere in Shipping > Carriers dopo che ha ricevuto ordini, PrestaShop lo salva come nuova versione del corriere. Il modulo segue automaticamente la nuova versione.

Il modulo calcola le tariffe e fornisce ai clienti 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 calcola le tariffe internazionali di Delhivery. Al di fuori dell'India si usano solo i prezzi fissi.

Ordini e tracciamento

Quando un ordine viene effettuato con Delhivery, il modulo salva con l'ordine la modalità di spedizione e la fonte del prezzo. Nella pagina dell'ordine nel back office, il blocco Delhivery mostra Mode: (Express o Surface), Price: (tariffa Delhivery in tempo reale, prezzo fisso o soglia di spedizione gratuita) e il Delhivery AWB / tracking number, oppure Not entered yet.

Crea la spedizione in Delhivery One, poi inserisci il suo AWB come numero di tracciamento dell'ordine nel blocco Carriers della pagina dell'ordine (Edit). Il blocco Delhivery mostra allora un link Track on delhivery.com. Il cliente vede un link di tracciamento nella cronologia dell'ordine e riceve l'email con stato «In transito» da PrestaShop.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Delhivery è il primo blocco della pagina Modules > Module Manager > VibeFox Delhivery > Configure, 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 si trovano la riga Product: presta-shipping-delhivery e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo i dipendenti con il permesso Configure per il modulo possono modificare la chiave. I testi del blocco seguono la lingua del back office (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 o License expired on con una data. Dopo un cambio dell'indirizzo del negozio, o dopo aver liberato un posto dominio nel tuo account, fai clic su Check now. Se il server delle licenze non è raggiungibile, il modulo continua a funzionare con l'ultimo stato noto.

Una chiave funziona su un solo dominio: quello del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo posto dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, il corriere Delhivery non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Lo storefront di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il corriere è nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non testarlo al checkout. Un promemoria compare in Modules > Module Manager, nella scheda Alerts. Gli ordini esistenti non sono interessati.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene ricontrollato automaticamente mentre lavori nel back office: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve alcun cron job. Disinstallare o ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Delhivery non compare al checkout: verifica che la licenza sia attiva e che Enable Delhivery sia attivato. In Shipping > Carriers verifica che il corriere copra la zona del paese del cliente e il gruppo del cliente, oppure attiva Ignore zones e controlla Countries. Controlla i limiti di peso e Show from subtotal. Senza una tariffa in tempo reale serve un prezzo per paese o un Fallback price. I prodotti possono anche essere limitati a determinati corrieri nella pagina del prodotto.

Le tariffe in tempo reale non compaiono: controlla il token API, un Origin pincode valido e, se la valuta predefinita non è INR, il tasso di cambio. Il cliente deve inserire un codice PIN indiano valido a 6 cifre. Attiva Debug log, ricarica il checkout e controlla il campo Log nella pagina del modulo. Mostra il motivo, per esempio un codice PIN non servito o un errore HTTP di Delhivery.

Il GST viene addebitato due volte: l'importo totale di Delhivery include già il GST. Imposta Rate amount su Gross amount (excluding GST) oppure imposta Tax su No tax.

Test: imposta Environment su Staging e usa un token di test di Delhivery.

Le tariffe sembrano obsolete dopo una modifica: fai clic su Save nella pagina del modulo. Questo cancella le tariffe Delhivery in cache.

La pagina dice che il corriere Delhivery non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Reimposta il modulo in Modules > Module Manager per ricrearlo.

Per gli sviluppatori: il modulo esegue gli hook actionVfdDlvApiUrl e actionVfdDlvApiTimeout, che possono cambiare l'indirizzo dell'API e il timeout.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Delhivery e scegli Uninstall. La chiave di licenza, lo stato della licenza e le tariffe in cache vengono sempre rimosse. Se Remove data on uninstall è attivata, il corriere riottiene le sue zone precedenti e viene eliminato (gli ordini conservano la loro cronologia), e vengono rimosse le impostazioni, il log e i dati Delhivery degli ordini (modalità e fonte del prezzo). Se è disattivata, il corriere viene solo disattivato e tutte le impostazioni vengono conservate. Reinstallando il modulo, il corriere viene ripristinato con lo stato che aveva prima. I numeri AWB restano negli ordini.

Delhivery è un marchio registrato del rispettivo titolare. Questo modulo non è affiliato a Delhivery né da essa approvato.