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

Tariffario Ninja Van: le tariffe del tuo account mittente Ninja Van o fornite dal team commerciale di Ninja Van, inserite nella tabella dei prezzi. Non servono chiavi API. Le tariffe facoltative in tempo reale all'interno dell'Indonesia usano l'API Ninja Van Tariff, pubblica e senza necessità di autenticazione.

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un solo 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 Ninja Van nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la tua 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 le tue tariffe Ninja Van nella tabella dei prezzi. Per l'Indonesia, se vuoi puoi attivare Live rates (vedi Configurazione). Fai clic su Save.

All'installazione il modulo crea il corriere Ninja Van con il testo dei tempi di consegna Courier delivery. Il corriere è attivo, assegnato a tutte le zone e a tutti i gruppi di clienti, e non ha una regola fiscale. Puoi modificare zone, gruppi di clienti, tempi di consegna, logo e limiti di dimensione 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 Ninja Van > Configure. Si applicano a tutte le zone del corriere. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Non viene salvato nulla e compare un errore quando un campo numerico contiene testo o un numero negativo, IDR conversion rate è 0, Minimum weight (kg) è maggiore di Maximum weight (kg), oppure Method title supera 64 caratteri. Se l'unità di peso del tuo negozio non è tra quelle riconosciute dal modulo, dopo il salvataggio compare un avviso che indica che i pesi dei prodotti sono considerati in chilogrammi.

Generale

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

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

Tax: la regola fiscale del corriere, oppure No tax (predefinito). Scegli No tax se i prezzi della tabella includono già le imposte (GST, SST, VAT).

Prezzi (nella valuta predefinita del tuo negozio, tasse escluse)

Inserisci i prezzi del tuo tariffario Ninja Van nella valuta predefinita del tuo 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 un prezzo in tempo reale non è disponibile.

Price table: una riga per paese di destinazione. Fai clic su Add country per aggiungere una riga e sull'icona del cestino per rimuoverla. 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 uguale a 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 nessuna riga *), oppure quando la riga non ha un prezzo per quel peso. Lascialo vuoto per nascondere il corriere in quel caso. 0 significa spedizione gratuita.

Price applies: il modo in cui vengono calcolati i prezzi. Questo vale anche per i prezzi in tempo reale.

Tariffe in tempo reale (API) — Indonesia

L'API Ninja Van Tariff 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 partenza, un tasso di conversione mancante e l'ultima risposta dell'API Tariff (ambiente, orario ed esito).

Live rates: ottieni le tariffe Ninja Van in tempo reale per le consegne all'interno dell'Indonesia. Predefinito: disattivato. Senza questa opzione, al 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, per esempio ID_A00007_01 e ID_B00069_01, tratti dalla mappatura dei codici di zona di Ninja Van (CSV) il cui indirizzo è mostrato sotto il campo. Inserisci entrambi, oppure lasciali vuoti per rilevarli dall'indirizzo del negozio in Shop Parameters > Contact > Stores: Indonesia, provincia (state), città e, se la città ha più zone, il distretto (Kecamatan) nella riga dell'indirizzo. Un codice in 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 i prezzi in tempo reale non vengono richiesti.

IDR conversion rate: l'API Tariff restituisce la tariffa in rupie indonesiane (IDR). Se la valuta predefinita del tuo negozio è IDR, lascia il campo vuoto. Altrimenti indica quanto vale 1 IDR nella valuta del tuo negozio, per esempio 0.000058. Deve essere maggiore di 0. Senza questo valore i prezzi in tempo reale non vengono usati e viene usata la tabella.

Condizioni

Minimum weight (kg): nasconde il corriere quando il carrello pesa meno. I pesi dei prodotti vengono convertiti dall'unità di peso del negozio in chilogrammi. 0 significa nessun limite.

Maximum weight (kg): nasconde il corriere quando il carrello pesa di più. Predefinito: 30. 0 significa nessun limite. Non può essere inferiore a Minimum weight (kg).

Minimum order amount: mostra il corriere solo quando il subtotale del carrello (prodotti che richiedono spedizione, dopo sconti, prima delle imposte) raggiunge questo importo. Lascia vuoto per mostrarlo sempre.

Free shipping from: il subtotale del carrello (prodotti che richiedono spedizione, dopo sconti, prima delle imposte) a partire dal quale la spedizione Ninja Van è gratuita. Lascia vuoto per nessuna spedizione gratuita.

Disponibilità senza zone di spedizione

Ignore shipping zones: offre Ninja Van per i paesi indicati di seguito anche se il corriere non è collegato alla loro zona. Quando è attivo, il corriere viene collegato a tutte le zone attive, comprese quelle che creerai in seguito. Quando lo disattivi, il corriere riprende le zone che aveva prima.

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

Avanzate

Debug log: registra i calcoli delle tariffe in logs/vfd_njvn_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Gli indirizzi dei clienti non vengono registrati. Le richieste API Tariff non riuscite vengono registrate anche quando l'opzione è disattivata. Disattivala quando hai finito.

Log: mostra la dimensione e le ultime voci del log di debug. Fai clic su Clear log per svuotarlo.

Remove data on uninstall: se attivo, disinstallando il modulo vengono eliminate le sue impostazioni, il corriere, i prezzi in cache e il log. Se disattivo, tutto viene conservato per una reinstallazione.

Come funziona al checkout

Nel passaggio di spedizione PrestaShop chiede al modulo il prezzo Ninja Van. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nell'importo dell'ordine. Il modulo verifica prima le condizioni: l'elenco dei paesi di Ignore shipping zones (se attivo), il peso del carrello e l'importo minimo dell'ordine. Se si applica la spedizione gratuita, il prezzo è 0 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. Se non c'è un prezzo, il corriere viene nascosto per quel carrello. Il prezzo viene calcolato nella valuta predefinita del negozio e poi mostrato nella valuta del carrello del cliente.

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

L'API Tariff consente 20 richieste al minuto, quindi le risposte sono memorizzate nella cache per 6 ore, gli errori per 5 minuti e «nessun prezzo per questa tratta» per 1 ora. Il modulo 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 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.

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

Il modulo calcola solo i prezzi. 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 la Ninja Van Dashboard. Non c'è un selettore dei punti di ritiro (Ninja Points): il corriere è una consegna porta a porta. Le tariffe in tempo reale non sono disponibili al di fuori dell'Indonesia.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox acquistata su vibefox.net. Il blocco licenza License — VibeFox Ninja Van è il primo blocco in Modules > Module Manager > VibeFox Ninja Van > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopodiché 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-ninja-van 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 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, 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: il dominio del negozio principale, anche in una configurazione multistore. 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 corriere Ninja Van non viene mostrato ai clienti al checkout e non viene calcolata alcuna tariffa. Il front office 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 puoi 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 assistenza richiedono il rinnovo. Lo stato viene ricontrollato automaticamente mentre lavori nel back office: una volta al giorno nei primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve alcun cron job. Disinstallare o reimpostare il modulo 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. In Shipping > Carriers verifica che il corriere copra la zona del paese del cliente e il gruppo del cliente (oppure attiva Ignore shipping zones e controlla Countries). Controlla 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. I prodotti possono anche essere limitati a determinati corrieri nella pagina del prodotto.

Per alcuni indirizzi il prezzo in tempo reale non viene usato: la destinazione deve corrispondere a una zona Ninja Van: Indonesia, provincia (state), città o reggenza e, per le città con più zone, il distretto (Kecamatan) in una riga dell'indirizzo. Altrimenti viene usato il prezzo della tabella. Attiva Debug log, ricarica il checkout e controlla il campo Log nella pagina del modulo.

Le tariffe in tempo reale non vengono richieste affatto: le righe di stato sotto Tariffe in tempo reale (API) — Indonesia indicano il motivo: l'indirizzo del negozio non è in Indonesia o la zona di partenza non è stata rilevata (inserisci entrambi i codici di zona), è stato inserito solo uno dei due codici, i codici inseriti non formano una coppia nella mappatura delle zone, oppure manca IDR conversion rate.

Limite di richieste raggiunto (HTTP 429): le richieste in tempo reale vengono sospese per un'ora e nel frattempo viene usata la tabella dei prezzi.

Valuta dei prezzi: la tabella e le condizioni sono nella valuta predefinita del tuo negozio. Le tariffe in tempo reale sono in rupie (IDR) e vengono convertite con IDR conversion rate, a meno che la valuta del negozio sia IDR.

La pagina indica che il corriere Ninja Van non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Ripristina il modulo in Modules > Module Manager per ricrearlo.

Sviluppatori: un negozio con un proprio campo distretto (Kecamatan) può fornire i codici di zona tramite l'hook actionVfdNjvnTariffZone.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Ninja Van e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. I prezzi in cache vengono sempre rimossi. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini mantengono la cronologia) e vengono rimosse le impostazioni, l'ultimo stato dell'API Tariff e il log. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni vengono mantenute. Reinstallando il modulo, al corriere salvato viene restituito lo stato che aveva prima della disinstallazione.

Ninja Van è un marchio del rispettivo proprietario. Questo modulo non è affiliato né approvato da Ninja Van.