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

Account Servientrega (solo per le tariffe in tempo reale): le tariffe in tempo reale usano il Cotizador Corporativo di Servientrega (API di preventivazione aziendale). Ti serve un account aziendale (di credito) Servientrega con accesso ad esso. Servono tre dati: l'utente, la password e il codice di fatturazione (código de facturación, di solito inizia con SER). Sono le tue credenziali SISCLINET e le rilascia il tuo consulente commerciale Servientrega. Se usi solo tariffe fisse, non ti serve un account Servientrega.

Accesso al server (solo per le tariffe in tempo reale): il tuo server deve poter raggiungere web.servientrega.com via HTTP sulla porta 8058 (API di preventivazione) e sulla porta 8081 (servizio web di cifratura delle password).

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_servientrega in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Shipping > VibeFox Servientrega, 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 cima alla pagina e fai clic su Activate.

5. Per le tariffe in tempo reale, inserisci utente, password e codice di fatturazione, scegli il prodotto Servientrega, inserisci il codice DANE di origine e, se la valuta del negozio non è COP, il tasso di conversione valutaria (vedi Configurazione).

6. Facoltativamente, aggiungi tariffe fisse per paese e peso e un costo di ripiego.

7. Aggiungi VibeFox Servientrega a una zona di spedizione 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 Servientrega. Si applicano a 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 globale.

Ogni volta che salvi le impostazioni, i preventivi Servientrega in cache e il token di accesso vengono cancellati. Se le tariffe in tempo reale non possono funzionare con le impostazioni salvate, un avviso sopra le impostazioni ne indica il motivo: utente, password o codice di fatturazione mancanti, tasso di conversione mancante o codice DANE di origine mancante.

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: Servientrega.

API Servientrega (tariffe in tempo reale per la Colombia) (facoltativo; senza credenziali si usano solo le tariffe fisse)

User (login): il tuo utente Servientrega / SISCLINET.

Password: la tua password Servientrega / SISCLINET, così come la digiti. Il plugin la fa cifrare dal servizio web di Servientrega prima dell'accesso, come fa il client ufficiale di Servientrega.

Billing code: il código de facturación del tuo account Servientrega, mostrato in SISCLINET. Di solito inizia con SER.

Tutti e tre i campi sono necessari per le tariffe in tempo reale. Le tariffe in tempo reale sono richieste solo per destinazioni in Colombia. Gli altri paesi usano le tariffe fisse.

Servientrega product: il servizio del tuo contratto Servientrega per cui viene richiesto il preventivo.

Il peso fatturato è il maggiore tra peso reale e peso volumetrico.

Currency conversion rate: Servientrega quota in COP. Se la valuta del tuo negozio non è COP, inserisci il valore di 1 COP nella valuta del negozio, per esempio 0.00023. Il valore dichiarato del pacco viene convertito in COP allo stesso modo. Lascialo vuoto se la valuta del negozio è COP. Se il negozio usa un'altra valuta e il campo è vuoto, le tariffe in tempo reale non vengono usate e si applicano le tariffe fisse. Il plugin non recupera i tassi di cambio. Sono accettati sia il punto sia la virgola come separatore decimale.

Spedisci da (usato per le tariffe in tempo reale)

Origin city (DANE code): il codice DANE a 8 cifre del comune da cui spedisci, per esempio 11001000 Bogotá, 05001000 Medellín, 76001000 Cali o 08001000 Barranquilla. È accettato anche un codice comunale a 5 cifre. Se è vuoto e l'indirizzo del negozio in WooCommerce > Settings > General è in Colombia, si usa il comune dell'indirizzo del negozio.

Tariffe fisse (usate quando non c'è una tariffa in tempo reale: senza credenziali, destinazione fuori dalla Colombia, comune sconosciuto, tasso di conversione mancante, oppure errore dell'API o assenza di copertura per la tratta)

Price per country: una tabella di paesi e prezzi nella valuta del negozio. Fai clic su + Add country per aggiungere una riga e sulla croce per rimuoverne una. Price vale per qualsiasi peso. Le colonne di peso XS ≤1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg e XL >5 kg sostituiscono Price per quel peso quando sono superiori a 0. La riga * Default vale per tutti i paesi senza una riga propria.

Fallback cost: usato quando non c'è una tariffa in tempo reale e nessuna riga della tabella corrisponde. Lascialo vuoto per nascondere il metodo in quel caso.

Fixed price applies: come vengono addebitate le tariffe fisse.

Le tariffe Servientrega in tempo reale si applicano sempre per spedizione.

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: 50. 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: la spedizione è gratuita quando il subtotale del carrello (dopo gli sconti, prima delle tasse) raggiunge questo importo. Vale solo dove il metodo ha un prezzo: un prezzo della tabella o il costo di ripiego (allora non viene inviata nessuna richiesta a Servientrega), oppure una tariffa in tempo reale. Lascialo vuoto per non offrire mai la spedizione gratuita.

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

Tax status: Taxable aggiunge l'imposta WooCommerce al costo di spedizione, None non la aggiunge. I preventivi Servientrega (ValorTotal) includono già i costi del vettore. Scegli None se non vuoi aggiungere tasse sopra.

Disponibilità senza zone di spedizione

Ignore shipping zones: offre Servientrega 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 in cui spedisci. Questo campo è usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: scrive i calcoli delle tariffe e gli errori dell'API nel log di WooCommerce: WooCommerce > Status > Logs, origine vfd_servientrega. Credenziali, token e indirizzi dei clienti non vengono registrati. Disattiva il log quando hai finito.

Remove data on uninstall: se attivo, eliminando il plugin vengono rimosse tutte le impostazioni Servientrega, i metodi di zona e i preventivi in cache. Disattivare il plugin non elimina mai nulla.

Come funziona al checkout

Quando il cliente inserisce un indirizzo di consegna, WooCommerce chiede al plugin una tariffa. Il plugin controlla prima le condizioni: paese di consegna, peso del carrello, importo minimo dell'ordine e classi di spedizione escluse. Poi cerca un prezzo: la tariffa Servientrega in tempo reale, poi la tabella dei prezzi e infine il costo di ripiego. Se non c'è un prezzo, il metodo viene nascosto. Se si applica la spedizione gratuita, il metodo viene mostrato con prezzo 0.

Per una destinazione in Colombia con credenziali impostate, il plugin trova il codice DANE del comune del cliente. Usa un codice DANE digitato come CAP o nel campo città, oppure abbina dipartimento e città con la tabella integrata di circa 1.130 comuni. Accenti e "D.C." vengono ignorati. Un nome di città che esiste in un solo dipartimento viene trovato anche senza indicare il dipartimento.

Il plugin invia poi a Servientrega un solo pacco per ordine: il peso totale convertito dall'unità del negozio in kg, e una scatola con lunghezza e larghezza dell'articolo più grande e il volume totale di tutti gli articoli, convertito in cm. I prodotti senza dimensioni contano come 10 × 10 × 10 cm. Il valore dichiarato è il subtotale del carrello convertito in COP, con un minimo di 6.000 COP. Servientrega restituisce il totale in COP e il plugin lo converte nella valuta del negozio.

Il token di accesso viene conservato fino alla scadenza, al massimo 4 giorni. Un token rifiutato viene rinnovato automaticamente una volta. Ogni preventivo è memorizzato nella cache per 1 ora per tratta e pacco, così lo stesso carrello non genera una nuova richiesta. Una richiesta non riuscita (cifratura, accesso o preventivo) è memorizzata nella cache per 10 minuti, così il checkout non attende Servientrega a ogni aggiornamento. Il timeout è di 10 secondi per richiesta.

Se non c'è una tariffa in tempo reale, il prezzo viene dalla tabella delle tariffe fisse, poi dal Fallback cost. Se nessuno dei due si applica, il metodo viene nascosto. Il cliente non vede mai un errore dell'API. Il motivo viene scritto nel log di debug.

Il metodo funziona sul checkout classico e sui blocchi Carrello e Checkout. È compatibile con WooCommerce High-Performance Order Storage (HPOS). Sono incluse le traduzioni in spagnolo (Colombia, Spagna).

Il plugin calcola solo le tariffe. Non crea guide (guías), etichette o adesivi, non richiede ritiri, non traccia né annulla spedizioni e non permette ai clienti di scegliere un ufficio Servientrega (Centro de Soluciones). Crea la guida in SISCLINET o nel tuo portale Servientrega. Il contrassegno (logística de recaudo) non viene quotato. I preventivi in tempo reale riguardano solo le spedizioni nazionali all'interno della Colombia. Ecuador, Perù, Panama e le spedizioni internazionali usano le tariffe fisse.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza si trova in cima a WooCommerce > Settings > Shipping > VibeFox Servientrega. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, per esempio la data fino alla quale la licenza è attiva e il tuo dominio. Usa Check now per ricontrollare 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 il suo posto per il dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, Servientrega non viene mostrato ai clienti al checkout. I gestori del negozio con accesso lo vedono ancora, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e testare 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 ricontrollato automaticamente in background.

Risoluzione dei problemi

Servientrega 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 ed Excluded shipping classes. Senza una tariffa in tempo reale, controlla che il paese o * Default abbia un prezzo, oppure che Fallback cost sia impostato.

Le tariffe in tempo reale non compaiono: attiva il Debug log, ricarica il checkout e apri WooCommerce > Status > Logs, origine vfd_servientrega. Cause frequenti: tasso di conversione mancante (la valuta del negozio non è COP), nessun codice DANE di origine, dipartimento o città del cliente non ancora inseriti o non riconosciuti come comune noto, credenziali errate oppure assenza di copertura per la tratta. Le tariffe fisse coprono questi casi se le hai impostate.

Il login non riesce: verifica utente, password e codice di fatturazione con il tuo consulente commerciale Servientrega. Dopo un login non riuscito, il plugin attende 10 minuti prima del tentativo successivo. Salva le impostazioni per riprovare subito.

La città del cliente non viene riconosciuta: dipartimento e città vengono confrontati con la tabella DANE integrata. Per grafie rare, il cliente può digitare il codice DANE a 8 cifre come CAP. Gli sviluppatori possono associarlo con il filtro vfd_svtg_dane_code.

Le tariffe sembrano obsolete dopo una modifica: salva la pagina delle impostazioni. Questo cancella i preventivi Servientrega in cache e il token.

Per sviluppatori: i filtri vfd_svtg_quote_request e vfd_svtg_default_dimensions modificano la richiesta di preventivo e le dimensioni dei prodotti che ne sono privi. vfd_svtg_api_base e vfd_svtg_soap_url cambiano gli endpoint, per esempio se Servientrega ti fornisce un altro server.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera un posto 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 tutti i dati. Per rimuoverlo, disattivalo ed eliminalo dalla pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi. Impostazioni, metodi di zona, preventivi in cache e token vengono rimossi solo se Remove data on uninstall era attivo. Altrimenti restano per una reinstallazione successiva. Gli ordini esistenti mantengono le loro righe di spedizione.

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