VibeFox Jadlog for PrestaShop — Guida
Requisiti
PrestaShop: da 8.0 a 9.x.
PHP: 8.0 o successivo. Il modulo non si installa su versioni di PHP più vecchie.
Contratto Jadlog (per i prezzi in tempo reale e i punti Pickup): i prezzi in tempo reale e l'elenco dei punti Pickup arrivano dall'API Embarcador di Jadlog. La tua franchigia Jadlog rilascia l'accesso dopo la firma del contratto. Ti servono il token dell'API Embarcador, il CNPJ (o CPF) del mittente registrato nel contratto, il conto corrente (conta corrente) e, se ce l'hai, il numero di contratto. Se usi solo prezzi fissi, non ti serve un contratto Jadlog.
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 cerca VibeFox Jadlog più tardi 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, poi fai clic su Activate (vedi Chiave di licenza).
4. Incolla il token API, inserisci CNPJ, conto corrente, numero di contratto e CEP di origine, scegli il servizio Jadlog e, se la valuta predefinita del tuo negozio non è BRL, inserisci il tasso di cambio BRL. Aggiungi prezzi fissi o un costo di riserva se li vuoi (vedi Configurazione). Fai clic su Save.
5. Per offrire anche i punti Jadlog Pickup, attiva Enable Jadlog Pickup e fai clic su Save.
All'installazione il modulo crea due corrieri: Jadlog (consegna a domicilio, attivo, testo del tempo di consegna Jadlog delivery to your address) e Jadlog Pickup (disattivato, testo del tempo di consegna Pickup at a Jadlog Pickup point). Entrambi sono collegati alla zona Brasile e a tutti i gruppi di clienti. Puoi modificare zone, gruppi di clienti, tempo di consegna, logo e limiti di dimensione in Shipping > Carriers. Non impostare lì i prezzi: il prezzo arriva sempre dal modulo.
Configurazione
Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Jadlog > Configure. Valgono per entrambi i corrieri Jadlog. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio cancella anche i prezzi Jadlog e gli elenchi dei punti Pickup in cache.
In cima alla pagina il modulo mostra avvisi per una configurazione incompleta: nessun token API (si usano solo prezzi fissi e i punti Pickup non possono essere elencati), nessun token API e nessun prezzo fisso (il metodo non viene mai mostrato), nessun CNPJ o conto corrente, nessun CEP di origine, nessun tasso di cambio BRL per un negozio che non vende in BRL, un'unità di peso o di dimensione del negozio che il modulo non riconosce (in quel caso i pesi sono considerati in kg e le dimensioni in cm; imposta le unità in International > Localization, Local units), oppure un corriere Jadlog eliminato. Al salvataggio vengono segnalati i valori errati: un CEP senza 8 cifre, un CNPJ senza 14 cifre (o 11 per un CPF), un numero non valido, un peso minimo superiore al peso massimo (entrambi i pesi mantengono i valori salvati), un paese sconosciuto o un prezzo non valido nella tabella prezzi.
General
Enable/Disable: attiva o disattiva la consegna a domicilio Jadlog. È lo stesso interruttore dello stato del corriere in Shipping > Carriers.
Method title: il nome del corriere per la consegna a domicilio mostrato nel carrello e al checkout. Predefinito: Jadlog. Obbligatorio.
Tax status: None oppure Taxable con una delle tue regole fiscali. Viene salvato su entrambi i corrieri Jadlog. I prezzi Jadlog sono prezzi finali del corriere. Scegli None se PrestaShop non deve aggiungere imposte a questi prezzi.
Jadlog live prices
I prezzi in tempo reale vengono richiesti solo per indirizzi in Brasile con un CEP completo di 8 cifre.
API token: il token Embarcador di Jadlog. Puoi incollarlo con o senza la parola "Bearer". Lascialo vuoto per usare solo prezzi fissi. Dopo il salvataggio il campo resta vuoto e mostra Saved - leave empty to keep it. Inserisci un nuovo valore solo per modificarlo.
Remove the saved API token: seleziona la casella e fai clic su Save per eliminare il token salvato.
CNPJ: il CNPJ (14 cifre) o il CPF (11 cifre) del mittente registrato nel contratto Jadlog. Sono ammessi punti, barre e trattini.
Current account (conta corrente): il numero del tuo conto corrente Jadlog. Senza di esso e senza il CNPJ, Jadlog non può quotare e si usano solo prezzi fissi.
Contract number: il numero del tuo contratto Jadlog, se la tua franchigia te ne ha assegnato uno.
Origin CEP: il codice postale da cui vengono spediti i pacchi, di 8 cifre. Viene salvato nel formato 00000-000. Lascialo vuoto per usare il codice postale del negozio in Shop Parameters > Contact > Stores, se l'indirizzo del negozio è in Brasile.
Jadlog service: il servizio (modalidade) del tuo contratto per la consegna a domicilio: .Package (3, predefinito), .Com (9), Expresso (0), Rodoviário (4), Econômico (5), Doc (6), Corporate (7), Internacional (10), Cargo (12) o Emergencial (14). Jadlog Pickup (40) è il secondo corriere.
Insurance type: Normal (N) (predefinito) oppure Own insurance policy (A - apolice), come concordato nel tuo contratto Jadlog.
Volumetric weight: Jadlog addebita il maggiore tra peso reale e peso volumetrico.
BRL exchange rate: Jadlog quota in reais brasiliani. Se la valuta predefinita del tuo negozio è BRL, questo campo non serve. Altrimenti inserisci quanto vale 1 BRL nella valuta predefinita, per esempio 0.16. Il prezzo Jadlog viene moltiplicato per questo tasso, e il valore dichiarato dell'ordine inviato a Jadlog viene riconvertito in BRL. Senza il tasso non si usano prezzi in tempo reale e valgono solo i prezzi fissi. Sono accettati sia il punto sia la virgola come separatore decimale.
Delivery time: mostra al checkout il tempo di consegna restituito da Jadlog, sotto il corriere Jadlog e accanto a ciascun punto Pickup, per esempio "Delivery time: 3 business days". Attivo per impostazione predefinita. Il tempo di consegna viene sempre salvato con l'ordine.
Jadlog Pickup
Un secondo corriere con il servizio Jadlog Pickup (40). Richiede il token API. Senza punti, il corriere viene nascosto.
Enable Jadlog Pickup: attiva o disattiva il corriere Jadlog Pickup. È lo stesso interruttore del suo stato in Shipping > Carriers. Disattivato dopo l'installazione.
Jadlog Pickup carrier name: il nome di questa opzione al checkout. Predefinito: Jadlog Pickup. Obbligatorio.
Points to show: quanti punti Pickup offrire, da 1 a 10. Predefinito: 5.
Fixed prices (usati quando non c'è un token API, per i paesi che Jadlog non serve e ogni volta che Jadlog non restituisce un prezzo)
Price per country: una tabella con le colonne Country, Price, XS, S, M, L e XL, nella valuta predefinita del negozio. Fai clic su + Add country per aggiungere una riga e sull'icona del cestino per rimuoverne una. La colonna della dimensione si sceglie in base al peso del carrello: XS fino a 1 kg, S fino a 2 kg, M fino a 3 kg, L fino a 5 kg, XL oltre 5 kg. Price si usa quando la colonna della dimensione è vuota. Il prezzo 0 significa spedizione gratuita per quel paese. Usa * Default (other countries) per tutti gli altri paesi. Le righe senza alcun prezzo vengono rimosse al salvataggio.
Fallback cost: usato quando né Jadlog né la tabella forniscono un prezzo. Lascialo vuoto per nascondere il corriere in quel caso.
Fixed price applies: Per order addebita il prezzo una sola volta. Per item (price x quantity) lo moltiplica per il numero di articoli nel carrello. Vale solo per i prezzi fissi e per il costo di riserva. I prezzi Jadlog coprono già l'intero carrello.
Conditions
Minimum weight (kg): nasconde i corrieri quando il carrello pesa meno. 0 significa nessun limite.
Maximum weight (kg): nasconde i corrieri quando il carrello pesa di più. Predefinito: 150. 0 significa nessun limite.
Minimum order amount: mostra i corrieri solo quando il subtotale del carrello (prodotti che richiedono spedizione, dopo gli sconti, prima delle imposte) raggiunge questo importo. Lascialo vuoto per mostrarli sempre.
Free shipping from: il subtotale del carrello (dopo gli sconti, prima delle imposte) da cui la consegna è gratuita. Lascialo vuoto se non c'è spedizione gratuita.
Availability without shipping zones
Ignore shipping zones: offre Jadlog per i paesi indicati di seguito, anche se i suoi corrieri non sono collegati alla loro zona. Quando lo attivi, entrambi i corrieri vengono collegati a tutte le zone attive, e anche le zone create in seguito vengono collegate. Quando lo disattivi di nuovo, i corrieri tornano alle zone che avevano prima.
Countries: i paesi di destinazione per questa modalità, al di fuori delle zone proprie dei corrieri. Lascialo vuoto per consentire tutti i paesi. Questo campo viene usato solo quando Ignore shipping zones è attivo.
Advanced
Debug log: registra ogni richiesta e risposta Jadlog in logs/vfd_jdlg_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Gli errori API vengono sempre registrati, anche con questa opzione disattivata. Token, CNPJ e conto non vengono mai registrati, e il CEP del cliente viene abbreviato. Disattiva il log quando hai finito.
Log: mostra la dimensione e le ultime voci del log. Fai clic su Clear log per svuotarlo.
Remove data on uninstall: se attivo, disinstallando il modulo vengono eliminate tutte le impostazioni Jadlog e i suoi corrieri. Se disattivo, la disinstallazione disattiva soltanto i corrieri. I prezzi in cache vengono sempre eliminati. Gli ordini non vengono mai modificati.
Come funziona al checkout
Al passaggio di spedizione PrestaShop chiede al modulo il prezzo di ciascun corriere Jadlog. Contano solo i prodotti fisici: i prodotti virtuali non aggiungono peso e non sono inclusi nell'importo dell'ordine. Il modulo controlla prima le condizioni: peso del carrello e importo minimo dell'ordine e, con Ignore shipping zones, i paesi consentiti. Se il subtotale del carrello raggiunge Free shipping from, la consegna è gratuita e non viene inviata alcuna richiesta di prezzo a Jadlog.
Per un indirizzo di consegna in Brasile con un CEP completo di 8 cifre, il modulo invia a Jadlog il CEP di origine e di destinazione, il peso, il tuo CNPJ, il conto corrente, il contratto, il servizio, il tipo di assicurazione e il valore dichiarato dell'ordine. Il prezzo restituito viene convertito nella valuta predefinita del negozio e mostrato nella valuta del carrello del cliente. I carrelli senza peso vengono quotati come 0,1 kg. Se non c'è un prezzo in tempo reale (nessun token, indirizzo fuori dal Brasile, CEP incompleto, nessun tasso di cambio BRL, errore di Jadlog), il modulo usa la tabella Price per country, poi il Fallback cost. Se nessuno dei due fornisce un prezzo, il corriere viene nascosto per quel carrello.
Ogni prezzo viene memorizzato nella cache per 1 ora, così lo stesso carrello non genera una nuova richiesta. Una richiesta fallita viene memorizzata nella cache per 10 minuti. Se Jadlog non risponde, restituisce un errore del server o rifiuta il token, l'API non viene richiamata per 10 minuti. Il timeout dell'API è di 10 secondi. Il cliente non vede mai un errore API. Il motivo viene scritto nel log.
Se modifichi un 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 solo i prezzi ed elenca solo i punti Pickup. Non crea spedizioni Jadlog, non stampa etichette, non richiede ritiri, non annulla spedizioni né traccia i pacchi. Non mostra una mappa dei punti Pickup e non richiede a Jadlog quotazioni internazionali. Per gli altri paesi usa prezzi fissi.
Punti Pickup
Il corriere Jadlog Pickup viene offerto solo per indirizzi in Brasile, e solo quando il token API è salvato. Quando il cliente ha inserito un CEP completo di 8 cifre, il modulo chiede a Jadlog i punti Pickup attivi più vicini e mostra fino a Points to show punti sotto il corriere, ciascuno con il suo prezzo, per esempio "nome del punto — prezzo (3 business days) — indirizzo". Se l'elenco non è ancora in cache, viene caricato quando il cliente seleziona il corriere, così il passaggio di spedizione non attende Jadlog.
Il prezzo per ciascun punto viene richiesto a Jadlog. Se Jadlog non fornisce un prezzo per un punto, si usa il prezzo fisso, e un punto senza alcun prezzo viene escluso. Gli elenchi dei punti vengono memorizzati nella cache per 12 ore. Il prezzo del corriere è quello del punto scelto. Prima che un punto venga scelto, è il prezzo del punto più vicino che ha un prezzo. Un punto senza prezzo non nasconde il corriere finché altri punti hanno un prezzo. Dopo che il cliente ha scelto un punto, il passaggio di spedizione viene aggiornato con il nuovo prezzo.
Un punto è obbligatorio. Senza punto il cliente non può proseguire e vede Please select a Jadlog Pickup point. Il modulo verifica che il punto sia nell'elenco Jadlog per il CEP di consegna. Se non lo è, il cliente vede The selected Jadlog Pickup point is not in the Jadlog list for this CEP. Please choose the point again. Quando il CEP è incompleto, non ci sono punti vicini o Jadlog non è disponibile, sotto il corriere compare un messaggio.
Senza token API, senza CEP di 8 cifre, quando Jadlog non è disponibile o quando non ci sono punti attivi nelle vicinanze, il corriere Jadlog Pickup viene nascosto. Un ordine senza punto non potrebbe essere spedito.
Ordini
Quando un ordine viene effettuato con un corriere Jadlog, il modulo salva il servizio Jadlog e, se Jadlog lo ha restituito, il tempo di consegna in giorni lavorativi. Per un ordine Jadlog Pickup salva anche il nome, l'indirizzo e l'ID del punto Pickup.
La pagina dell'ordine nell'amministrazione mostra un blocco Jadlog con Jadlog service, Delivery time e, per Jadlog Pickup, Pickup point, Pickup point address e Pickup point ID. Il cliente vede il punto scelto nella pagina di conferma dell'ordine e nei dettagli dell'ordine. Il punto viene aggiunto al nome del corriere nell'e-mail di conferma dell'ordine. L'e-mail di nuovo ordine del negozio (se usi il modulo di avvisi e-mail) riporta anch'essa l'ID del punto.
Registra tu la spedizione nel sistema Jadlog. L'ordine mostra il servizio e l'ID del punto Pickup di cui hai bisogno.
Chiave di licenza
Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Jadlog è il primo blocco della pagina Modules > Module Manager > VibeFox Jadlog > 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 ci sono la riga Product: presta-shipping-jadlog 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 un posto per il 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 posto per il dominio. Libera il posto nel tuo account vibefox.net.
Senza una chiave attiva, i corrieri Jadlog non vengono mostrati ai clienti al checkout e non viene calcolata alcuna tariffa. La vetrina di PrestaShop non sa che hai effettuato l'accesso al back office, quindi i corrieri vengono nascosti anche a te: puoi configurare il modulo prima di acquistare una chiave, ma non puoi provarlo 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 a 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
Jadlog non compare al checkout: verifica che la licenza sia attiva e che Enable/Disable (o Enable Jadlog Pickup) 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. Controlla gli avvisi in cima alla pagina del modulo, i limiti di peso e il Minimum order amount. Se il cliente non ha ancora inserito un CEP completo di 8 cifre, si possono usare solo prezzi fissi, quindi aggiungi una riga in Price per country o un Fallback cost. Nella pagina del prodotto si possono anche limitare i prodotti a determinati corrieri.
Vengono mostrati solo prezzi fissi: attiva Debug log, ricarica il checkout e controlla il campo Log nella pagina del modulo. Mostra il motivo: nessun CNPJ o conto corrente, nessun CEP di origine, CEP di destinazione incompleto, nessun tasso di cambio BRL oppure il messaggio di errore di Jadlog.
HTTP 401 o 403 nel log: Jadlog ha rifiutato il token API. Verificalo con la tua franchigia Jadlog. Dopo questo errore l'API viene sospesa per 10 minuti. Salvare le impostazioni rimuove la sospensione, quindi puoi riprovare subito.
I punti Pickup non compaiono: il corriere Jadlog Pickup richiede Enable Jadlog Pickup, il token API e un CEP completo di 8 cifre in Brasile. Se Jadlog non ha punti attivi vicino al CEP, il corriere viene nascosto. Controlla il log per il motivo.
I prezzi sono in reais invece che nella mia valuta: inserisci il BRL exchange rate (quanto vale 1 BRL nella valuta predefinita del tuo negozio).
I prezzi sembrano troppo bassi o troppo alti: compila i pesi e le dimensioni dei prodotti. I carrelli senza peso vengono quotati come 0,1 kg, e il peso volumetrico richiede le dimensioni.
Alle tariffe Jadlog viene aggiunta l'imposta: imposta Tax status su None.
I prezzi sembrano non aggiornati dopo una modifica: fai clic su Save nella pagina del modulo. Questo cancella i prezzi Jadlog e gli elenchi dei punti Pickup in cache.
La pagina dice che un corriere Jadlog non è stato trovato: il corriere è stato eliminato in Shipping > Carriers. Reimposta il modulo in Modules > Module Manager per ricrearlo.
Disinstallazione
Vai su Modules > Module Manager, apri il menu accanto a VibeFox Jadlog e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. I prezzi in cache e gli elenchi dei punti Pickup vengono sempre eliminati. Se Remove data on uninstall è attivo, entrambi i corrieri vengono eliminati (gli ordini mantengono la cronologia) e vengono rimosse impostazioni e log. Se è disattivo, i corrieri vengono solo disattivati e tutte le impostazioni vengono conservate. Reinstallando il modulo, i corrieri riprendono lo stato che avevano. Il servizio Jadlog, il tempo di consegna e il punto Pickup salvati con gli ordini vengono sempre conservati.
Jadlog è un marchio del suo rispettivo proprietario. Questo modulo non è affiliato a Jadlog né approvato da Jadlog.