VibeFox Ninja Van for OpenCart — Guida
Requisiti
OpenCart: 3.0.x (testato con la 3.0.5.0) o 4.0.2 e successivi (testato con la 4.1.0.3).
PHP: 8.0 o successivo.
Tariffario Ninja Van: i prezzi del tuo account mittente Ninja Van o quelli forniti dal team commerciale di Ninja Van, inseriti nella tabella dei prezzi. Non servono chiavi API. Le tariffe facoltative in tempo reale all'interno dell'Indonesia usano la Tariff API di Ninja Van, pubblica e senza autenticazione.
Chiave di licenza VibeFox: acquistata 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_ninja_van-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 vfd_ninja_van.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. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_ninja_van-oc3-(version).ocmod.zip. L'estensione non aggiunge modifiche OCMOD, quindi non devi 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 Ninja Van 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 in License key nel blocco di licenza in cima alla pagina Edit e clicca su Activate (vedi Chiave di licenza).
5. Inserisci i tuoi prezzi Ninja Van nella tabella dei prezzi. Per l'Indonesia, se vuoi, attiva Live rates (vedi Configurazione). Attiva Enable Ninja Van e clicca su Save.
OpenCart 4
1. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file vfd_ninja_van.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 a esso.
3. Vai su Extensions > Extensions e scegli il tipo di estensione Shipping. Trova VibeFox Ninja Van, 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 nelle due versioni.
Dopo l'installazione il metodo resta disattivato finché non attivi Enable Ninja Van e salvi. Se reinstalli l'estensione dopo una disinstallazione, vengono riutilizzate le impostazioni Ninja Van che avevi conservato.
Configurazione
Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Shipping > VibeFox Ninja Van > Edit. Le sezioni sono elencate a sinistra. Un pulsante Save in fondo salva l'intera pagina senza ricaricarla. Non viene salvato nulla e compare un errore quando Method title è vuoto, supera 64 caratteri o contiene < > ; = # { }, quando un campo numerico contiene testo o un numero negativo, quando IDR conversion rate è 0, quando Minimum weight (kg) è maggiore di Maximum weight (kg) o quando Sort order non è un numero intero. Se il negozio non ha una classe di peso con unità kg e l'unità della classe di peso predefinita non è riconosciuta dall'estensione, un avviso segnala che i pesi dei prodotti vengono considerati in chilogrammi: aggiungi una classe di peso kg in System > Localisation > Weight Classes. Solo gli utenti amministratori con il permesso di modifica per questa estensione possono salvare le impostazioni.
Generali
Le impostazioni si applicano a tutte le zone geografiche. Puoi limitare il metodo a una zona geografica in Conditions, oppure usare Ignore shipping zones.
Enable Ninja Van: mostra o nasconde Ninja Van al checkout. Predefinito: disattivato.
Method title: il nome del metodo di spedizione mostrato al cliente nel carrello e al checkout. Predefinito: Ninja Van. Obbligatorio, massimo 64 caratteri.
Tax class: la classe fiscale del costo di spedizione, oppure No tax (predefinito). Scegli No tax se i prezzi in tabella includono già le imposte (GST, SST, VAT).
Sort order: la posizione di Ninja Van tra i metodi di spedizione al checkout. Un numero intero.
Prezzi (nella valuta predefinita del tuo negozio, imposte escluse)
Inserisci i prezzi del tuo tariffario Ninja Van nella valuta predefinita del negozio. Se il tuo tariffario è in SGD, MYR, IDR o un'altra valuta, convertilo prima. Questa tabella viene usata per ogni destinazione fuori dall'Indonesia e ogni volta che una tariffa in tempo reale non è disponibile.
Price table: una riga per paese di destinazione. Clicca su Add country per aggiungere una riga e sul pulsante × per rimuoverla. Scegli * All other countries per tutti i paesi senza una riga propria. Ogni riga ha un prezzo Base e colonne di peso: XS fino a 1 kg, S fino a 2 kg, M fino a 3 kg, L fino a 5 kg e XL oltre 5 kg. Una colonna di peso vuota (o con 0) usa il prezzo base. Un prezzo base di 0 significa spedizione gratuita verso quel paese. Sono accettati sia "9.99" sia "9,99". Le righe senza prezzi vengono eliminate al salvataggio, e per ogni paese viene mantenuta solo la prima riga.
Price for countries not in the table: usato quando la tabella non ha una riga per il paese di destinazione (e nemmeno una riga *), oppure quando la riga non ha un prezzo per quel peso. Lascialo vuoto per nascondere il metodo in questo caso. 0 significa spedizione gratuita.
Price applies: il modo in cui vengono calcolati i prezzi. Vale anche per le tariffe in tempo reale.
Tariffe in tempo reale (API) — Indonesia
La Tariff API di Ninja Van restituisce la tariffa di consegna standard, senza supplementi né sconti, per i pacchi spediti all'interno dell'Indonesia. Ninja Van la offre solo per l'Indonesia. Quando Live rates è attivo, le righe di stato sotto il titolo della sezione mostrano la zona di spedizione, un tasso di conversione mancante e l'ultima risposta della Tariff API (ambiente, ora e risultato). Vengono aggiornate dopo ogni salvataggio.
Live rates: ottieni le tariffe Ninja Van in tempo reale per le consegne all'interno dell'Indonesia. Predefinito: disattivato. Senza questa opzione, durante il checkout non viene inviato nulla a Ninja Van.
Environment: Production (api.ninjavan.co) (predefinito) oppure Sandbox — testing only (api-sandbox.ninjavan.co).
Service level: il servizio per cui viene richiesto il prezzo: Standard (predefinito), Express, Same day o Next day. Se Ninja Van non ha un prezzo per la tratta e il servizio, viene usata la tabella dei prezzi.
Ship-from zone code L1 e Ship-from zone code L2: i codici di livello L1 e L2 del distretto da cui spedisci, ad esempio ID_A00007_01 e ID_B00069_01, dal mapping dei codici di zona di Ninja Van (CSV) il cui indirizzo è mostrato sotto il campo. Inseriscili entrambi: l'indirizzo del negozio in OpenCart non ha città e via separate, quindi la zona di spedizione non può essere rilevata da esso. I codici vengono convertiti in maiuscolo. Un codice in un formato errato viene cancellato con un avviso. Se è inserito un solo codice, un avviso chiede di inserirli entrambi e una riga di stato indica che non vengono richieste tariffe in tempo reale. Una riga di stato avvisa anche quando i due codici non formano una coppia nel mapping dei codici di zona.
IDR conversion rate: la Tariff API restituisce la tariffa in rupie indonesiane (IDR). Se la valuta predefinita del tuo negozio è IDR, lascialo vuoto. Altrimenti inserisci quanto vale 1 IDR nella valuta del tuo negozio, ad esempio 0.000058. Deve essere maggiore di 0. Senza di esso le tariffe in tempo reale non vengono usate e si usa la tabella dei prezzi.
Condizioni
Minimum weight (kg): nasconde il metodo quando il carrello pesa meno. I pesi dei prodotti vengono convertiti dalla loro classe di peso OpenCart in chilogrammi. 0 significa nessun limite (predefinito).
Maximum weight (kg): nasconde il metodo quando il carrello pesa di più. Predefinito: 30. 0 o un campo vuoto significano nessun limite. Non può essere inferiore a Minimum weight (kg).
Minimum order amount: mostra il metodo solo quando il subtotale dei prodotti che richiedono spedizione (dopo il coupon, prima delle imposte) raggiunge questo importo. Lascialo vuoto per mostrarlo sempre.
Free shipping from: il subtotale dei prodotti che richiedono spedizione (dopo il coupon, prima delle imposte) a partire dal quale la spedizione Ninja Van è gratuita. Lascialo vuoto se non vuoi la spedizione gratuita.
Geo zone: offri Ninja Van solo per indirizzi in 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.
Disponibilità senza zone di spedizione
Ignore shipping zones: offri Ninja Van per i paesi sotto indicati, indipendentemente dalla Geo zone. Quando è disattivato (predefinito), decide la zona geografica e l'elenco dei paesi non viene usato.
Countries: i paesi di destinazione per quella modalità. Lascialo vuoto per consentire tutti i paesi. Questo campo viene usato solo quando Ignore shipping zones è attivo.
Avanzate
Debug log: scrive i calcoli delle tariffe in storage/logs/vfd_njvn_debug.log.php (su OpenCart 4 system/storage/logs/vfd_njvn_debug.log.php). Il file non è leggibile dal web. Non vengono registrati indirizzi dei clienti né codici di zona. Le richieste non riuscite alla Tariff API vengono registrate anche quando questa opzione è disattivata. Disattivala quando hai finito. Quando il file raggiunge 5 MB, viene spostato in vfd_njvn_debug.old.log.php e ne viene avviato uno nuovo.
Log: mostra la dimensione e le ultime voci del log di debug. Clicca su Clear log per svuotarlo.
Remove data on uninstall: se attivo, disinstallando l'estensione vengono eliminate le impostazioni Ninja Van e il log. Se disattivato (predefinito), vengono conservate per una reinstallazione. Le tariffe memorizzate nella cache vengono sempre eliminate.
Importa / Esporta
Export: clicca su Download JSON per salvare le impostazioni in un file JSON. L'estensione non ha chiavi segrete, quindi viene esportato tutto.
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.
Come funziona al checkout
Quando OpenCart mostra i metodi di spedizione, chiede all'estensione il prezzo di Ninja Van. Se è impostata una Geo zone (e Ignore shipping zones è disattivato) e l'indirizzo è al di fuori di essa, Ninja Van non viene offerto. Contano solo i prodotti con Requires Shipping impostato su Yes: gli altri non aggiungono peso e non sono inclusi nell'importo dell'ordine. L'estensione controlla poi le condizioni: l'elenco dei paesi di Ignore shipping zones (se attivo), il peso del carrello e l'importo minimo dell'ordine. L'importo dell'ordine è 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 non viene inviata alcuna richiesta a Ninja Van.
Il prezzo deriva dalla riga del paese (o dalla riga *): prima la colonna di peso, altrimenti il prezzo base, altrimenti Price for countries not in the table. Se non c'è alcun prezzo, il metodo viene nascosto per quel carrello. Il prezzo viene calcolato nella valuta predefinita del negozio, arrotondato alle sue cifre decimali e mostrato al cliente nella sua valuta con l'imposta della Tax class selezionata.
Con Live rates attivo, una consegna all'interno dell'Indonesia viene prezzata prima da Ninja Van. L'estensione trasforma l'indirizzo di consegna in codici di zona Ninja Van: la regione (provincia) dell'indirizzo, il campo City (città o reggenza) e, per le città con più zone, il distretto (Kecamatan) indicato in Address 1 o Address 2. Invia i tuoi codici di spedizione, i codici di consegna, il peso e il livello di servizio, e converte la tariffa da IDR nella valuta del negozio. Con Per item, viene inviata una richiesta per ogni peso diverso di articolo, fino a 5 per carrello. Con più pesi diversi si usa la tabella dei prezzi.
La Tariff API consente 20 richieste al minuto, quindi le risposte vengono memorizzate nella cache in una tabella dell'estensione: i prezzi per 6 ore, "nessun prezzo per questa tratta" per 1 ora e gli errori per 5 minuti. Salvare le impostazioni non svuota questa cache. L'estensione non invia mai più di 18 richieste al minuto e, dopo una risposta HTTP 429, si ferma per un'ora. Il timeout dell'API è di 12 secondi. Se Ninja Van non risponde, restituisce un errore, non ha un prezzo per la tratta o l'indirizzo non può essere abbinato, viene usato il prezzo della tabella. Gli errori vanno nel log, mai al cliente.
Su OpenCart 4 il cliente fa clic su Choose nel blocco del metodo di spedizione della pagina di checkout e sceglie Ninja Van nella finestra Shipping method options. Il metodo funziona come su OpenCart 3.
L'estensione calcola solo i prezzi. Non crea ordini Ninja Van, non stampa lettere di vettura aerea (AWB), non prenota ritiri, non traccia i pacchi e non gestisce il contrassegno (COD). Per questo usa il Dashboard di Ninja Van. Non c'è un selettore dei punti di ritiro (Ninja Points): il metodo è la consegna a domicilio. Non aggiunge nulla agli ordini: l'ordine mostra il titolo del metodo e il costo di spedizione come qualsiasi altro metodo di spedizione OpenCart. Le tariffe in tempo reale non sono disponibili al di fuori dell'Indonesia.
Chiave di licenza
L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza License — VibeFox Ninja Van è il primo blocco di Extensions > Extensions > Shipping > VibeFox Ninja Van > Edit, sopra le impostazioni. Inserisci 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 compaiono la riga Product: opencart-shipping-ninja-van e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo gli utenti amministratori con il permesso di modifica 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 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, Ninja Van non viene mostrato ai clienti al 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
Ninja Van non compare al checkout: verifica che la licenza sia attiva e che Enable Ninja Van sia attivo. Controlla Geo zone (o Ignore shipping zones e Countries), i limiti di peso e Minimum order amount, e che il paese, la riga * o Price for countries not in the table abbiano un prezzo. Verifica che i prodotti abbiano Requires Shipping impostato su Yes.
Il prezzo in tempo reale non viene usato per alcuni indirizzi: la destinazione deve corrispondere a una zona Ninja Van: Indonesia, regione (provincia), città o reggenza in City e, per le città con più zone, il distretto (Kecamatan) in una riga di indirizzo. Altrimenti si usa il prezzo della tabella. Attiva il Debug log, ricarica il checkout e controlla il campo Log nella pagina dell'estensione.
Le tariffe in tempo reale non vengono richieste affatto: le righe di stato sotto Tariffe in tempo reale (API) — Indonesia mostrano il motivo: mancano i codici di zona di spedizione, è inserito solo uno dei due codici, i codici inseriti non formano una coppia nel mapping dei codici di zona, oppure manca IDR conversion rate.
Limite di richieste raggiunto (HTTP 429): le richieste in tempo reale vengono sospese per un'ora e nel frattempo si usa la tabella dei prezzi. Salvare le impostazioni non interrompe la pausa.
In quale valuta sono i prezzi: la tabella e le condizioni sono nella valuta predefinita del negozio. Le tariffe in tempo reale sono in rupie (IDR), convertite con IDR conversion rate a meno che la valuta del negozio non sia IDR.
La pagina mostra "Warning: You do not have permission to modify VibeFox Ninja Van!": il gruppo utenti amministratori può solo visualizzare le impostazioni. Concedi al gruppo il permesso di modifica per extension/shipping/vfd_ninja_van (OpenCart 3) o extension/vfd_ninja_van/shipping/vfd_ninja_van (OpenCart 4) in System > Users > User Groups.
Per gli sviluppatori: un negozio con un proprio campo distretto (Kecamatan) può fornire i codici di zona tramite l'evento OpenCart vfd_ninja_van/tariff_zone (trigger catalog/vfd_ninja_van/tariff_zone), anche per la zona di spedizione. L'indirizzo della Tariff API può essere sostituito con l'impostazione vfd_njvn_api_url (per i test); non ha un campo nella pagina delle impostazioni.
Disinstallazione
Vai su Extensions > Extensions, scegli il tipo Shipping e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox Ninja Van. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart reimposta sempre Enable Ninja Van, Sort order, Tax class e Geo zone. Le tariffe memorizzate nella cache vengono sempre eliminate. Se Remove data on uninstall è attivo, vengono eliminate anche le impostazioni Ninja Van, l'ultimo stato della Tariff API e il log di debug. Se è disattivato, le altre impostazioni vengono conservate e riutilizzate quando reinstalli l'estensione. Gli ordini esistenti mantengono il loro metodo di spedizione e il loro costo.
Su OpenCart 4, per rimuovere anche i file dell'estensione, dopo la disinstallazione vai su Extensions > Installer e clicca su Uninstall (il pulsante arancione −) accanto a VibeFox Ninja Van nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per eliminare il pacchetto caricato.
Ninja Van è un marchio del rispettivo proprietario. Questa estensione non è affiliata né approvata da Ninja Van.