VibeFox Delhivery for OpenCart — Guida

Requisiti

OpenCart: 3.0.x (testato su 3.0.5.0) o 4.0.2 e successive (testato su 4.1.0.3).

PHP: 8.0 o successivo.

Token API Delhivery (solo per 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 dell'estensione. I token di test funzionano con l'ambiente di staging. Ti serve anche il pincode a 6 cifre del tuo punto di ritiro. Se usi solo prezzi fissi, non ti serve un token.

Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un 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_delhivery-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_delhivery.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, clicca su Upload e scegli il file vfd_delhivery-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non serve aggiornare Extensions > Modifications. Invece dell'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 Delhivery e clicca su Install (il pulsante verde +).

3. Clicca 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 di licenza in cima alla pagina Edit e clicca su Activate (vedi Chiave di licenza).

5. Inserisci il token API e il tuo pincode 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). Attiva Enable Delhivery e clicca su Save.

OpenCart 4

1. Nell'area di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_delhivery.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. Clicca su Install (il pulsante verde +) accanto ad esso.

3. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox Delhivery, clicca 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 in entrambe le versioni.

Dopo l'installazione il metodo è disattivato finché non attivi Enable Delhivery e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni Delhivery che hai conservato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox Delhivery > Edit. Le sezioni sono elencate a sinistra. Un pulsante Save salva l'intera pagina senza ricaricarla. Ogni salvataggio cancella anche le tariffe Delhivery in cache. Gli importi accettano "9.99" e "9,99". Se un valore è errato, non viene salvato nulla e la pagina mostra il motivo, ad esempio Enter a valid method title (without < > ; = # { })., un messaggio che indica che un campo deve essere un numero non negativo, oppure Sort order must be a whole number. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.

Se la valuta predefinita del tuo negozio non è INR, è salvato un token API e non è impostato un tasso di cambio, un avviso in cima alla pagina ti ricorda che le tariffe in tempo reale non vengono usate finché non inserisci il tasso. Se il negozio non ha una classe di peso in chilogrammi e la sua unità di peso non è una delle unità standard (kg, g, lb o oz), un avviso segnala che i pesi dei prodotti vengono letti come chilogrammi. Imposta un'unità standard in System > Localisation > Weight Classes.

Generali

Le impostazioni si applicano a tutte le zone geografiche. Puoi limitare il metodo in Availability.

Enable Delhivery: offre Delhivery al checkout. Predefinito: disattivato.

Method title: il nome del metodo di spedizione mostrato al cliente nel carrello e al checkout. Predefinito: Delhivery. Obbligatorio, massimo 64 caratteri, senza i caratteri < > ; = # { }.

Tax class: la classe fiscale del costo di spedizione, oppure No tax (predefinito). Con una classe, OpenCart aggiunge l'imposta sul costo di spedizione.

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

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 per modificarlo.

Remove saved token: attivalo e salva per eliminare il token salvato. Da quel momento vengono usati solo i prezzi fissi.

Origin pincode: il pincode a 6 cifre del tuo punto di ritiro o magazzino, ad esempio 110001. Se non ha 6 cifre, le impostazioni vengono salvate con l'avviso The origin pincode must have 6 digits — live rates are not requested until it is fixed.

Tariffe in tempo reale

Una tariffa in tempo reale viene richiesta per le destinazioni in India con un pincode valido a 6 cifre, per una spedizione diretta (consegnata).

Shipping mode: la modalità di fatturazione Delhivery usata per la tariffa: Express (predefinito) o Surface.

Payment type: il tipo di pagamento inviato a Delhivery: Pre-paid (predefinito) o COD (cash on delivery — Delhivery adds its COD charge). L'estensione non lo cambia in base al metodo di pagamento scelto dal cliente.

Rate amount: Delhivery restituisce il costo con e senza GST.

INR to (store currency) conversion rate: l'etichetta mostra la valuta predefinita del tuo negozio. Le tariffe Delhivery sono in rupie indiane. Se la tua valuta predefinita non è INR, indica quante unità della tua valuta vale una rupia, ad 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 tua valuta predefinita è INR.

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

I prezzi fissi vengono usati quando non c'è ancora un token o un pincode, la destinazione è fuori dall'India, il pincode non è servito o l'API restituisce un errore. Sono nella valuta predefinita del tuo negozio, IVA esclusa.

Prices per country: uno per riga nel formato CODICE_PAESE:prezzo, ad esempio IN:120. Viene verificato 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 applica né una tariffa in tempo reale né un prezzo per paese. Lascialo vuoto per nascondere il metodo (predefinito). 0 significa gratuito.

Fixed price is charged: Per order (predefinito) 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 consegna è gratuita se il subtotale dei prodotti che richiedono spedizione (dopo il coupon, IVA esclusa) è almeno pari a questo importo. Nessuna richiesta viene inviata a Delhivery. Lascialo vuoto per disattivarlo.

Show from subtotal: mostra il metodo solo se questo subtotale è 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 (predefinito).

Max weight (kg): nasconde il metodo se il carrello è più pesante. 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 viene salvato nulla.

I pesi dei prodotti vengono convertiti in kg dalla loro classe di peso di OpenCart. La tariffa usa il peso effettivo del carrello (la somma dei pesi dei prodotti), senza peso volumetrico né scatole.

Disponibilità

Geo zone: offri Delhivery 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 verificato quando Ignore zones è attivo.

Ignore zones: quando è attivo, la zona geografica non viene verificata e il metodo viene offerto per i paesi sotto (tutti i paesi se l'elenco è vuoto).

Countries: i paesi di destinazione per quella modalità. Usato solo quando Ignore zones è attivo.

Avanzate

Debug log: scrive i calcoli delle tariffe in storage/logs/vfd_dlv_debug.log.php (su OpenCart 4 system/storage/logs/vfd_dlv_debug.log.php). Il file non può essere letto dal web. Gli errori dell'API vengono sempre registrati, anche quando questa opzione è disattivata. I token e i pincode completi dei clienti non vengono mai registrati. Quando il file raggiunge 5 MB, viene spostato in vfd_dlv_debug.old.log.php e si avvia un nuovo log.

Log: mostra la dimensione e le ultime voci del log. Clicca su Clear log per svuotarlo.

Remove data on uninstall: quando è attivo, la disinstallazione dell'estensione elimina le impostazioni Delhivery, le tariffe in cache e il log. Quando è disattivo (predefinito), vengono conservati per una reinstallazione. I dati degli ordini (modalità, origine del prezzo, numeri AWB) non vengono mai eliminati.

Importa / Esporta

Export: clicca su Download JSON per salvare le impostazioni in un file JSON. Il token API non viene esportato.

Import: incolla un JSON esportato in precedenza e clicca su Import per ripristinare le impostazioni, ad esempio su un altro negozio. I valori vengono controllati come in un normale salvataggio. Il token API salvato non viene modificato.

Come funziona al checkout

Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo Delhivery. Se è impostata una Geo zone (e Ignore zones è disattivo) e l'indirizzo è fuori da essa, Delhivery non viene offerta. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non sono inclusi nel subtotale. Poi l'estensione verifica i paesi (se Ignore zones è attivo), il peso del carrello e Show from subtotal. Il subtotale è il prezzo dei prodotti che richiedono spedizione, dopo lo sconto del coupon e prima delle imposte. Buoni regalo, punti fedeltà e credito del negozio non vengono considerati. Se si applica la spedizione gratuita, il prezzo è 0 e nessuna richiesta viene inviata a Delhivery.

Per un indirizzo indiano con un pincode valido a 6 cifre (il codice postale dell'indirizzo), l'estensione invia a Delhivery i pincode 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 negozio, arrotondato alle sue cifre decimali e mostrato al cliente nella sua valuta con l'imposta della Tax class selezionata. 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 nessuno dei due è impostato, il metodo viene nascosto. Il cliente non vede mai un errore dell'API. Il motivo viene scritto nel log.

L'estensione calcola le tariffe e fornisce ai clienti un link di tracciamento. Non crea spedizioni né lettere di vettura, non stampa etichette, non richiede ritiri né manifesti, non verifica la copertura dei pincode, non stima le date di consegna, non sincronizza gli stati di tracciamento e non quota tariffe internazionali Delhivery. Fuori dall'India vengono usati solo i prezzi fissi.

Su OpenCart 4 il cliente clicca su Choose nel blocco del metodo di spedizione della pagina di checkout e sceglie Delhivery nella finestra Shipping method options. Il metodo funziona come su OpenCart 3.

Ordini e tracciamento

Quando un ordine viene effettuato con Delhivery, l'estensione salva con l'ordine la modalità di spedizione e l'origine del prezzo. Apri l'ordine in Sales > Orders: il pannello Delhivery sopra lo storico dell'ordine 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.

Su OpenCart 4 il checkout mantiene un solo ordine e lo aggiorna ogni volta che il cliente conferma di nuovo. Con esso vengono aggiornati anche la modalità e l'origine del prezzo. Se il cliente passa a un altro metodo di spedizione prima che venga inserito un AWB, il pannello Delhivery non viene più mostrato per quell'ordine.

Crea la spedizione in Delhivery One, poi inserisci il suo AWB nel pannello e clicca su Save. La pagina non viene ricaricata. Lettere, cifre e trattini vengono mantenuti (fino a 64 caratteri). Salva un campo vuoto per rimuovere l'AWB. Con un AWB, il pannello mostra un link Track on delhivery.com. Salvare l'AWB richiede il permesso di modificare gli ordini. Senza di esso, il pannello è di sola lettura.

Un cliente registrato vede Delhivery tracking: con l'AWB come link alla pagina di tracciamento Delhivery nella pagina dell'ordine del suo account. Quando aggiungi una voce allo storico dell'ordine e notifichi il cliente, l'email di stato dell'ordine riceve la stessa riga con il link. L'email di nuovo ordine non contiene un link di tracciamento, perché l'AWB viene inserito in seguito. Il pannello e il link di tracciamento funzionano anche per gli ordini precedenti quando l'estensione è disattivata.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox Delhivery è il primo blocco della pagina Extensions > Extensions > Shipping > VibeFox Delhivery > Edit, sopra le impostazioni. Incolla la chiave in License key e clicca su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (ad 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 di essi ci sono la riga Product: opencart-shipping-delhivery 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 spiega il motivo, ad esempio Key not found, This key belongs to another product, Domain limit reached oppure License expired on seguito da una data. Dopo aver cambiato l'indirizzo del negozio o dopo aver liberato uno slot di dominio nel tuo account, clicca 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 dominio: l'indirizzo del negozio dalla 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, il metodo di spedizione Delhivery non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Un amministratore che ha effettuato l'accesso all'area 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 dell'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 supporto richiedono un rinnovo. Lo stato viene ricontrollato automaticamente quando apri la Dashboard dell'amministrazione o la pagina Edit: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta a settimana. Non serve alcun cron job. La disinstallazione dell'estensione 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 attivo. Controlla Geo zone, oppure Ignore zones e Countries, i limiti di peso e Show from subtotal. Senza una tariffa in tempo reale serve un prezzo per paese o un Fallback price. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.

Le tariffe in tempo reale non compaiono: controlla il token API, un Origin pincode valido e, se la tua valuta predefinita non è INR, il tasso di cambio. Il cliente deve inserire come codice postale un pincode indiano valido a 6 cifre. Attiva il Debug log, ricarica il checkout e guarda il campo Log nella pagina dell'estensione. Mostra il motivo, ad esempio un pincode 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 Tax class su No tax.

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

Le tariffe sembrano non aggiornate dopo una modifica: clicca su Save nella pagina dell'estensione. Questo cancella le tariffe Delhivery in cache.

Non è possibile salvare l'AWB: il messaggio You do not have permission to modify orders. significa che il tuo gruppo utenti amministratori ha bisogno del permesso di modifica per sale/order in System > Users > User Groups.

La pagina dice "Warning: You do not have permission to modify VibeFox Delhivery!": il tuo gruppo utenti amministratori potrebbe poter solo visualizzare le impostazioni. Assegna al gruppo il permesso di modifica per extension/shipping/vfd_delhivery (OpenCart 3) oppure extension/vfd_delhivery/shipping/vfd_delhivery (OpenCart 4) in System > Users > User Groups.

Per gli sviluppatori: l'estensione attiva gli eventi OpenCart catalog/vfd_delhivery/api_url e catalog/vfd_delhivery/api_timeout, che possono cambiare l'indirizzo dell'API e il timeout.

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox Delhivery. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart ripristina sempre Enable Delhivery, Sort order, Tax class e Geo zone. Le tariffe in cache e gli eventi dell'estensione vengono sempre rimossi. Se Remove data on uninstall è attivo, vengono eliminati anche le impostazioni Delhivery e il log di debug. Se è disattivo, le altre impostazioni vengono mantenute e riutilizzate quando reinstalli l'estensione. I dati Delhivery degli ordini (modalità, origine del prezzo e numeri AWB) non vengono mai eliminati. Gli ordini esistenti conservano il loro metodo di spedizione e costo.

Su OpenCart 4, per rimuovere anche i file dell'estensione, vai su Extensions > Installer dopo la disinstallazione e clicca su Uninstall (il pulsante arancione −) accanto a VibeFox Delhivery nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per rimuovere il pacchetto caricato.

Delhivery è un marchio di proprietà del rispettivo titolare. Questa estensione non è affiliata a Delhivery né approvata da Delhivery.