VibeFox Ninja Van 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.

Tariffario Ninja Van: i prezzi del tuo account mittente Ninja Van oppure forniti dal team commerciale Ninja Van, inseriti nella tabella dei prezzi. Non servono chiavi API. Le tariffe in tempo reale facoltative in Indonesia usano l'API Ninja Van Tariff, che è pubblica e non richiede autenticazione.

Chiave di licenza VibeFox: si acquista 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. In alternativa puoi caricare la cartella vfd_ninja_van in /wp-content/plugins/ tramite FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox Ninja Van, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugins.

4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in alto nella pagina e fai clic su Activate.

5. Inserisci le tue tariffe Ninja Van nella tabella dei prezzi. Per l'Indonesia, puoi facoltativamente attivare Live rates (vedi Configurazione).

6. Aggiungi VibeFox Ninja Van a una zona di spedizione (per esempio "Singapore") in WooCommerce > Settings > Shipping > Shipping zones, oppure attiva Ignore shipping zones e scegli i paesi.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox Ninja Van. Valgono per 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 i clienti vedono per questa zona. Lascialo vuoto per usare il Method title generale.

Generale

Enable/Disable: attiva o disattiva il metodo in tutte le zone contemporaneamente.

Method title: il nome del metodo di spedizione mostrato nel carrello e al checkout. Una zona può sostituirlo. Predefinito: Ninja Van.

Prezzi (nella valuta del tuo negozio)

Inserisci le tariffe del tuo tariffario Ninja Van nella valuta del negozio. Se il tuo tariffario è in SGD, MYR, IDR, PHP, THB o VND, convertilo prima. Questa tabella viene usata per tutte le destinazioni fuori dall'Indonesia e ogni volta che una tariffa in tempo reale non è disponibile.

Price table: una riga per paese di destinazione. Fai clic su + Add country per aggiungere una riga e sulla croce per rimuoverne una. Scegli * All other countries per tutti i paesi che non hanno una riga propria. Ogni riga ha un Base price 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.

Price for countries not in the table: si usa quando la tabella non ha una riga per il paese di destinazione (e nessuna riga *), oppure la riga non ha un prezzo per quel peso. Lascialo vuoto per nascondere il metodo in quel caso.

Price applies: il modo in cui vengono calcolati i prezzi. Vale anche per le tariffe in tempo reale.

Tariffe in tempo reale (API) — Indonesia

L'API Ninja Van Tariff restituisce la tariffa di consegna standard, senza supplementi e 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 in questa sezione mostrano la zona di partenza, un tasso di conversione mancante e l'ultima risposta dell'API Tariff.

Live rates: ottiene le tariffe Ninja Van in tempo reale per le consegne in 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 richiesta la tariffa: Standard (predefinito), Express, Same day oppure Next day. Se Ninja Van non ha una tariffa per il percorso e il servizio, si usa 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, per esempio ID_A00007_01 e ID_B00069_01, dalla mappatura dei codici di zona Ninja Van (CSV) collegata nella pagina delle impostazioni. Inserisci entrambi, oppure lasciali vuoti per rilevarli dall'indirizzo del negozio in WooCommerce > Settings > General: Indonesia, provincia, città e, se la città ha più zone, il distretto (Kecamatan) nella riga dell'indirizzo. Un codice con formato errato viene cancellato e viene mostrato un errore.

IDR conversion rate: l'API Tariff restituisce la tariffa in rupie indonesiane (IDR). Se la valuta del tuo negozio è IDR, lascialo vuoto. Altrimenti indica quanto vale 1 IDR nella valuta del tuo negozio, per esempio 0.000058. Senza questo valore 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 di meno. 0 significa nessun limite.

Maximum weight (kg): nasconde il metodo quando il carrello pesa di più. Predefinito: 30. 0 significa nessun limite.

Minimum order amount: mostra il metodo solo quando il subtotale del carrello (dopo gli sconti, prima delle tasse) raggiunge questo importo. Lascialo vuoto per mostrarlo sempre.

Free shipping from: il subtotale del carrello (dopo gli sconti, prima delle tasse) da cui la consegna con Ninja Van è gratuita. Lascialo vuoto se non c'è spedizione gratuita.

Excluded shipping classes: nasconde il metodo quando il carrello contiene un prodotto appartenente a una di queste classi di spedizione di WooCommerce.

Tax status: Taxable aggiunge l'imposta di WooCommerce al costo di spedizione, None non l'aggiunge. Scegli None se le tariffe nella tabella includono già le imposte (GST, SST, IVA).

Disponibilità senza zone di spedizione

Ignore shipping zones: offre Ninja Van per i paesi indicati di seguito, anche se il metodo non è aggiunto a nessuna zona di spedizione.

Countries: i paesi di destinazione per questa modalità. Lascialo vuoto per usare tutti i paesi verso cui spedisci. Questo campo viene usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: registra i calcoli delle tariffe in WooCommerce > Status > Logs (origine vfd_ninja_van). Non vengono registrati indirizzi dei clienti. Le richieste all'API Tariff non riuscite vengono registrate anche quando questa opzione è disattivata. Disattivala quando hai finito.

Remove data on uninstall: se attiva, eliminando il plugin vengono rimosse tutte le impostazioni di Ninja Van e i metodi di zona. La disattivazione del plugin non elimina mai nulla.

Come funziona al checkout

Quando il cliente inserisce un indirizzo di consegna, WooCommerce chiede una tariffa al plugin. Il plugin controlla per prima cosa le condizioni: paese di consegna, peso del carrello, importo minimo dell'ordine e classi di spedizione escluse. Se si applica la spedizione gratuita, il cliente vede il metodo senza costi e non viene inviata alcuna richiesta a Ninja Van.

Il prezzo proviene dalla riga del paese (o dalla riga *): la colonna di peso, altrimenti il prezzo base, altrimenti Price for countries not in the table. I pesi dei prodotti vengono convertiti dall'unità di peso del negozio in chilogrammi. Se non c'è un prezzo, il metodo viene nascosto.

Con Live rates attivo, una consegna in Indonesia viene tariffata prima da Ninja Van. Il plugin converte gli indirizzi di partenza e di consegna in codici di zona Ninja Van: provincia, città o reggenza e, per le città con più zone, il distretto (Kecamatan) indicato in una riga dell'indirizzo. Invia i codici, il peso e il livello di servizio, e converte la tariffa da IDR alla valuta del negozio. Con Per item, viene inviata una richiesta per ogni peso di articolo distinto, fino a 5 per carrello.

L'API Tariff consente 20 richieste al minuto, quindi le risposte vengono memorizzate nella cache per 6 ore, gli errori per 5 minuti e "nessuna tariffa per questo percorso" per 1 ora. Il plugin 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, risponde con un errore, non ha una tariffa per il percorso oppure l'indirizzo non può essere associato, si usa il prezzo della tabella. Gli errori vanno nel log e non vengono mai mostrati al cliente.

Il metodo funziona con il checkout classico e con i blocchi Cart e Checkout. È compatibile con WooCommerce High-Performance Order Storage (HPOS).

Il plugin calcola solo le tariffe. Non crea ordini Ninja Van, non stampa lettere di vettura aeree (AWB), non prenota ritiri, non traccia i pacchi e non gestisce il contrassegno (COD). Per questo usa il Ninja Van Dashboard. Non c'è un selettore dei punti di ritiro (Ninja Points): il metodo è una consegna a domicilio. Le tariffe in tempo reale non sono disponibili al di fuori dell'Indonesia.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox acquistata su vibefox.net. Il blocco licenza si trova in alto in WooCommerce > Settings > Shipping > VibeFox Ninja Van. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, per esempio la data fino a cui la licenza è attiva, e il tuo dominio. Usa Check now per controllare 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 solo dominio. Rimuovere la chiave da un sito non libera lo slot del dominio. Liberalo dal tuo account vibefox.net.

Senza una chiave attiva, Ninja Van non viene mostrato ai clienti al checkout. I gestori del negozio che hanno effettuato l'accesso lo vedono comunque, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Nella pagina Plugins e nelle pagine di WooCommerce compare un promemoria. Gli ordini esistenti non vengono modificati.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene controllato di nuovo automaticamente in background.

Risoluzione dei problemi

Ninja Van 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 shipping zones sia attivo e il paese sia consentito). Controlla i limiti di peso, Minimum order amount e Excluded shipping classes, e che il paese, la riga * o Price for countries not in the table abbiano un prezzo.

Per alcuni indirizzi non viene usata la tariffa in tempo reale: la destinazione deve essere associata a una zona Ninja Van: Indonesia, provincia, città o reggenza e, per le città con più zone, il distretto (Kecamatan) in una riga dell'indirizzo. Altrimenti si usa il prezzo della tabella. Attiva Debug log per vedere il motivo e controlla le righe di stato in Tariffe in tempo reale (API) — Indonesia.

Le tariffe in tempo reale non vengono richieste affatto: le righe di stato mostrano il motivo: l'indirizzo del negozio non è in Indonesia oppure la zona di partenza non è stata rilevata (inserisci entrambi i codici di zona), oppure manca l'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.

In quale valuta sono i prezzi: la tabella è nella valuta del tuo 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.

Sviluppatori: un sito con un proprio campo distretto (Kecamatan) al checkout può fornire i codici di zona con il filtro vfd_njvn_tariff_zone.

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

La disattivazione del plugin mantiene 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, l'ultimo stato dell'API Tariff e le tariffe in tempo reale in cache vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano disponibili per una reinstallazione successiva. Gli ordini esistenti mantengono le loro righe di spedizione.

Ninja Van è un marchio del suo rispettivo titolare. Questo plugin non è affiliato a Ninja Van né approvato da Ninja Van.