VibeFox Jadlog 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.

Contratto Jadlog (per i prezzi in tempo reale e i punti Pickup): i prezzi in tempo reale e l'elenco dei punti Pickup provengono 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. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e fai clic su Install Now. Puoi anche caricare la cartella vfd_jadlog in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

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

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

5. Incolla il token dell'API, inserisci CNPJ, conto corrente, numero di contratto e CEP di origine, scegli il servizio Jadlog e, se la valuta del tuo negozio non è BRL, inserisci il tasso di cambio BRL. Aggiungi prezzi fissi o un costo di riserva se li vuoi (vedi Configurazione).

6. Aggiungi VibeFox Jadlog a una zona di spedizione per il Brasile in WooCommerce > Settings > Shipping > Shipping zones, oppure attiva Ignore shipping zones e scegli i paesi. Per offrire anche i punti Jadlog Pickup, aggiungi il metodo una seconda volta alla zona e scegli Pickup (40) come servizio.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Shipping > VibeFox Jadlog. Si applicano a tutte le zone di spedizione. Quando aggiungi il metodo a una zona, la finestra della zona ha due campi:

Title (zone): il nome che i clienti vedono per questa zona. Lascia vuoto per usare il Method title globale.

Jadlog service (zone): il servizio di questo metodo di zona. Same as the global setting usa il servizio della pagina delle impostazioni principale. Aggiungi il metodo due volte per offrire, ad esempio, consegna a domicilio (.Package) e punti Jadlog Pickup nella stessa zona.

Quando il titolo della zona è vuoto e il servizio è Pickup, alla parola "Pickup" viene aggiunto il titolo globale, così i due metodi hanno nomi diversi.

In cima alla pagina delle impostazioni il plugin mostra avvisi per una configurazione incompleta: nessun token API, nessun CNPJ o conto corrente, nessun CEP di origine oppure nessun tasso di cambio BRL per un negozio che non vende in BRL. Ogni volta che salvi le impostazioni, vengono cancellati i prezzi Jadlog e gli elenchi dei punti Pickup in cache.

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. Predefinito: Jadlog. Una zona può sostituirlo.

Prezzi Jadlog in tempo reale

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". Lascia vuoto per usare solo i prezzi fissi.

CNPJ: il CNPJ (14 cifre) o il CPF (11 cifre) del mittente registrato nel contratto Jadlog. Sono consentiti punti, barre e trattini. Il plugin ti avvisa se il numero di cifre è errato.

Current account (conta corrente): il numero del tuo conto corrente Jadlog. Senza di esso e senza il CNPJ, Jadlog non può fornire un preventivo e vengono usati solo i prezzi fissi.

Contract number: il numero del tuo contratto Jadlog, se la tua franchigia te lo ha assegnato.

Origin CEP: il codice postale da cui vengono spediti i pacchi, di 8 cifre. Viene salvato nel formato 00000-000. Lascia vuoto per usare il codice postale del negozio indicato in WooCommerce > Settings > General, se l'indirizzo del negozio è in Brasile.

Jadlog service: il servizio (modalidade) del tuo contratto: .Package (3, predefinito), .Com (9), Expresso (0), Rodoviário (4), Econômico (5), Doc (6), Corporate (7), Internacional (10), Cargo (12), Emergencial (14) o Pickup (40). Pickup offre i punti Jadlog Pickup vicini al cliente. Un metodo di zona può usare un altro servizio.

Insurance type: Normal (N) (predefinito) oppure Own insurance policy (A — apólice), 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 del tuo negozio è il BRL, questo campo non serve. Altrimenti inserisci quanto vale 1 BRL nella valuta del tuo negozio, ad 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 i prezzi in tempo reale non vengono usati e si applicano solo i prezzi fissi. Sono accettati sia il punto sia la virgola come separatore decimale.

Delivery time: mostra il tempo di consegna restituito da Jadlog accanto al titolo del metodo, ad esempio "Jadlog (3 giorni lavorativi)". Attivo per impostazione predefinita. Il tempo di consegna viene sempre salvato nell'ordine.

Punti Jadlog Pickup (usati dal servizio Pickup (40); richiedono il token API)

Points to show: quanti punti Pickup offrire, da 1 a 10. Predefinito: 5.

Prezzi fissi (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 del tuo negozio. Fai clic su + Add country per aggiungere una riga e sulla croce per rimuoverne una. La colonna della taglia viene scelta 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 viene usato quando la colonna della taglia è vuota. Un prezzo di 0 significa spedizione gratuita per quel paese. Usa * Default come paese per tutti gli altri paesi. Le righe senza alcun prezzo vengono rimosse al salvataggio.

Fallback cost: viene usato quando né Jadlog né la tabella forniscono un prezzo. Lascia vuoto per nascondere il metodo in quel caso.

Fixed price applies: Per order addebita il prezzo una sola volta. Per item (price × quantity) lo moltiplica per il numero di articoli nel carrello. Questo vale solo per i prezzi fissi e per il costo di riserva. I prezzi Jadlog coprono già l'intero carrello.

Condizioni

Minimum weight (kg): nasconde il metodo quando il carrello pesa meno. 0 significa nessun limite.

Maximum weight (kg): nasconde il metodo quando il carrello pesa di più. Predefinito: 150. 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. Lascia vuoto per mostrarlo sempre.

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

Free shipping from: il subtotale del carrello (dopo gli sconti, prima delle tasse) a partire dal quale la spedizione è gratuita. Lascia vuoto per nessuna spedizione gratuita.

Tax status: Taxable aggiunge l'imposta di WooCommerce al costo di spedizione, None no. I prezzi Jadlog sono tariffe definitive del corriere. Scegli None se WooCommerce non deve applicarvi l'imposta.

Disponibilità senza zone di spedizione

Ignore shipping zones: offre Jadlog per i paesi sottoindicati anche se il metodo non è aggiunto a nessuna zona di spedizione. In questa modalità si usa il Jadlog service globale.

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

Avanzate

Debug log: registra ogni richiesta e risposta Jadlog in WooCommerce > Status > Logs, origine vfd-jadlog. Gli errori dell'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.

Remove data on uninstall: se attivo, eliminando il plugin vengono rimosse tutte le impostazioni Jadlog e i metodi di zona. Disattivare il plugin non elimina mai le impostazioni. I prezzi in cache vengono sempre rimossi.

Come funziona al checkout

Quando il cliente inserisce un indirizzo di consegna, WooCommerce chiede al plugin un prezzo. Il plugin verifica prima le condizioni: peso del carrello, importo minimo dell'ordine e classi di spedizione escluse. Se il subtotale del carrello raggiunge Free shipping from, la spedizione è 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 plugin 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, e mostra il prezzo restituito nella valuta del tuo negozio. 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 Jadlog), il plugin usa la tabella Price per country e poi il Fallback cost. Se nessuno dei due fornisce un prezzo, il metodo 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 non riuscita viene memorizzata 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 dell'API. Il motivo viene scritto nel log.

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

Il plugin calcola solo i prezzi ed elenca i punti Pickup. Non crea spedizioni Jadlog, non stampa etichette, non richiede ritiri, non annulla spedizioni e non traccia i pacchi. Non mostra una mappa dei punti Pickup e non richiede a Jadlog quotazioni internazionali. Per gli altri paesi usa i prezzi fissi.

Punti Pickup

Un metodo con il servizio Pickup (40) viene offerto solo per indirizzi in Brasile. Quando il cliente ha inserito un CEP completo di 8 cifre, il plugin chiede a Jadlog i punti Pickup attivi più vicini e offre fino a Points to show punti. Ogni punto è un'opzione di spedizione separata con il proprio prezzo, ad esempio "Jadlog Pickup: nome del punto — indirizzo". Il cliente sceglie un punto selezionando l'opzione di spedizione, sia nel checkout classico sia nei blocchi Carrello e Checkout.

Il prezzo per ogni 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.

Senza token API, senza un CEP di 8 cifre, quando Jadlog non è disponibile o quando non ci sono punti attivi nelle vicinanze, il metodo Pickup viene nascosto. Un ordine senza punto non potrebbe essere spedito.

Ordini

La riga di spedizione dell'ordine conserva il servizio Jadlog e, quando Jadlog l'ha restituito, il tempo di consegna in giorni lavorativi. Per un ordine Pickup il nome della riga di spedizione contiene il nome e l'indirizzo del punto, e l'ordine salva anche nome, indirizzo e ID del punto Pickup. Li vedi sotto la riga di spedizione nella schermata dell'ordine dell'amministrazione. Il cliente vede il punto scelto nella pagina di ringraziamento e nelle email dell'ordine.

Prenota tu la spedizione nel sistema Jadlog. L'ordine mostra il servizio e l'ID del punto Pickup di cui hai bisogno per farlo.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in alto in WooCommerce > Settings > Shipping > VibeFox Jadlog. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, ad esempio la data fino alla quale 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. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, Jadlog non viene mostrato ai clienti al checkout. I gestori del negozio che hanno effettuato l'accesso lo vedono ancora, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugins e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati.

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

Jadlog 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 gli avvisi in cima alla pagina delle impostazioni, i limiti di peso, Minimum order amount e Excluded shipping classes. Se il cliente non ha ancora inserito un CEP completo di 8 cifre, si possono usare solo i prezzi fissi, quindi aggiungi una riga in Price per country o un Fallback cost.

Vengono mostrati solo prezzi fissi: attiva il Debug log, ricarica il checkout e apri WooCommerce > Status > Logs, origine vfd-jadlog. Mostra il motivo: nessun CNPJ o conto corrente, nessun CEP di origine, CEP di destinazione incompleto, nessun tasso di cambio BRL o il messaggio di errore di Jadlog.

HTTP 401 o 403 nel log: Jadlog ha rifiutato il token API. Verificalo con la tua franchigia Jadlog. L'API viene sospesa per 10 minuti dopo questo errore. Il salvataggio delle impostazioni annulla la sospensione, quindi puoi riprovare subito.

I punti Pickup non compaiono: il metodo Pickup richiede il token API e un CEP completo di 8 cifre in Brasile. Se Jadlog non ha punti attivi vicino al CEP, il metodo 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 del tuo negozio).

I prezzi sembrano troppo bassi o troppo alti: inserisci i pesi e le dimensioni dei prodotti. I carrelli senza peso vengono quotati come 0,1 kg, e il peso volumetrico richiede le dimensioni.

I prezzi sembrano non aggiornati dopo una modifica: salva la pagina delle impostazioni. Questo cancella i prezzi Jadlog e gli elenchi dei punti Pickup in cache.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Ad 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

Disattivare il plugin conserva tutte le impostazioni e i metodi di zona. Vengono cancellati solo i prezzi in cache e gli elenchi dei punti Pickup. Per rimuovere il plugin, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato di licenza di questo plugin e i prezzi in cache vengono sempre rimossi. Le impostazioni e i metodi di zona vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano per una successiva reinstallazione. Gli ordini esistenti mantengono le righe di spedizione con il servizio Jadlog e il punto Pickup.

Jadlog è un marchio registrato del rispettivo titolare. Questo plugin non è affiliato né approvato da Jadlog.