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

Account Servientrega (solo per le tariffe in tempo reale): le tariffe in tempo reale usano il Cotizador Corporativo di Servientrega (API aziendale per i preventivi). 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 dei preventivi) e sulla porta 8081 (servizio web di cifratura della password).

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 Servientrega nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la chiave di licenza VibeFox in License key nel blocco licenza in alto nella pagina Configure e fai clic su Activate (vedi Chiave di licenza).

4. 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 tuo negozio non è il COP, il tasso di conversione della valuta. Fai clic su Add Colombian departments se il tuo negozio non ne ha ancora (vedi Configurazione).

5. Facoltativamente aggiungi tariffe fisse per paese e peso e un costo di ripiego, poi fai clic su Save.

All'installazione il modulo crea il corriere Servientrega con il testo dei tempi di consegna Servientrega courier delivery. Il corriere è assegnato a tutte le zone e a tutti i gruppi di clienti. Puoi cambiare zone, gruppi di clienti, tempi 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 Servientrega > Configure. Valgono per tutte le zone. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Ogni salvataggio svuota i preventivi Servientrega in cache e il token di accesso.

Se le tariffe in tempo reale non possono funzionare con le impostazioni salvate, un avviso sopra il modulo ti indica il motivo: utente, password o codice di fatturazione mancanti, tasso di conversione mancante o codice DANE di origine mancante. Un avviso compare anche se l'unità di peso o di dimensioni del tuo negozio (International > Localization, Local units) non è riconosciuta dal modulo; in tal caso i pesi sono letti in kg e le dimensioni in cm. Al salvataggio, un valore che non è un numero, un numero negativo, un tasso di conversione pari a 0, un peso minimo superiore al peso massimo, un prezzo errato nella tabella o un titolo del metodo più lungo di 64 caratteri viene rifiutato con un errore, e non viene salvato nulla.

Generale

Enable Servientrega: attiva o disattiva il corriere in tutte le zone contemporaneamente. È 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: Servientrega. Obbligatorio, massimo 64 caratteri.

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. Svuotarlo rimuove anche la password salvata.

Password: la tua password Servientrega / SISCLINET, come la digiti. Il modulo la fa cifrare dal servizio web di Servientrega prima dell'accesso. Dopo il salvataggio il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per cambiarla.

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 servono per le tariffe in tempo reale. Le tariffe in tempo reale vengono richieste solo per destinazioni in Colombia. Gli altri paesi usano le tariffe fisse.

Servientrega product: il servizio del tuo contratto Servientrega che viene quotato.

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

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

Colombian departments: il dipartimento aiuta a distinguere i comuni con lo stesso nome. PrestaShop non ha dipartimenti colombiani di default; senza di essi vengono riconosciuti solo i nomi di città unici in Colombia. Fai clic su Add Colombian departments per aggiungere i 33 dipartimenti come stati della Colombia (codici ISO ANT, DC…), attiva Contains states per la Colombia e aggiungi il campo dipartimento al modulo indirizzo colombiano. I dipartimenti già presenti non vengono aggiunti due volte. Quando tutto è pronto, il campo mostra quanti dipartimenti hanno gli indirizzi colombiani.

Spedizione 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 Shop Parameters > Contact > Stores si trova in Colombia, si usa il comune dell'indirizzo del negozio.

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

Price per country: una tabella di paesi e prezzi nella valuta predefinita del negozio, IVA esclusa. Fai clic su Add country per aggiungere una riga e sull'icona del cestino 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 la sostituiscono per quel peso quando sono superiori a 0. La riga * Default vale per tutti i paesi senza una propria riga. Una riga senza alcun prezzo non viene salvata.

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

Fixed price applies: come vengono addebitate le tariffe fisse.

Le tariffe Servientrega in tempo reale sono sempre per spedizione.

Condizioni

Minimum weight: nasconde il corriere quando il carrello pesa meno, in kg. 0 significa nessun limite.

Maximum weight: nasconde il corriere quando il carrello pesa di più, in kg. Predefinito: 50. 0 significa nessun limite.

Minimum order amount: mostra il corriere solo quando il subtotale del carrello (dopo sconti, IVA esclusa) raggiunge questo importo. Lascia vuoto per mostrarlo sempre.

Free shipping from: la spedizione è gratuita quando il subtotale del carrello (dopo sconti, IVA esclusa) raggiunge questo importo, e non viene inviata alcuna richiesta a Servientrega. Vale per ogni destinazione in cui il corriere è offerto, anche per i paesi senza una riga nella tabella dei prezzi. Lascia vuoto per non offrire mai la spedizione gratuita.

Tax: la regola fiscale del corriere, oppure No tax. I preventivi Servientrega (ValorTotal) includono già i costi del corriere. Scegli No tax se non vuoi aggiungere IVA sopra.

Disponibilità senza zone di spedizione

Normalmente il corriere è offerto nelle zone assegnate in Shipping > Carriers.

Ignore shipping zones: offre Servientrega per i paesi indicati sotto, anche se il corriere non è assegnato alla loro zona. Il corriere viene allora assegnato a tutte le zone, anche a quelle che creerai in seguito. Disattivando l'opzione, il corriere torna alle sue zone precedenti.

Countries: i paesi di destinazione per quella modalità. Lascia vuoto per usare tutti i paesi attivi del negozio. Questo campo è usato solo quando Ignore shipping zones è attivo.

Avanzate

Debug log: scrive i calcoli delle tariffe e gli errori dell'API in logs/vfd_svtg_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Credenziali, token e indirizzi dei clienti non vengono registrati. Con il log disattivato non viene scritto nulla, errori dell'API compresi. Disattiva il log 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 tutte le impostazioni Servientrega, il corriere, i preventivi in cache e i log. Gli ordini passati mantengono il loro corriere. Se disattivo, tutto viene conservato per una reinstallazione.

Come funziona al checkout

Nel passaggio della spedizione PrestaShop chiede al modulo il prezzo Servientrega. 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: il paese di consegna (con Ignore shipping zones), 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 Servientrega. Poi cerca un prezzo: la tariffa Servientrega in tempo reale, poi la tabella dei prezzi, poi il costo di ripiego. Se non c'è alcun prezzo, il corriere viene nascosto per quel carrello.

Per una destinazione in Colombia con le credenziali impostate, il modulo trova il codice DANE del comune del cliente. Usa un codice DANE digitato come codice postale o nel campo città, oppure fa corrispondere dipartimento e città con la tabella integrata di circa 1.130 comuni. Accenti e «D.C.» vengono ignorati. Un nome di città presente in un solo dipartimento viene trovato anche senza il dipartimento.

Il modulo invia poi a Servientrega un collo per ordine: il peso totale convertito dall'unità del tuo negozio in kg, e una scatola con la lunghezza e la 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. Il modulo lo converte nella valuta predefinita del negozio, e il cliente lo vede nella valuta del carrello.

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 collo, così lo stesso carrello non genera una nuova richiesta. Una richiesta non riuscita (cifratura, accesso o preventivo) viene memorizzata nella cache per 10 minuti, così il checkout non attende Servientrega a ogni aggiornamento. Il timeout è di 10 secondi per richiesta.

Il cliente non vede mai un errore dell'API. Il motivo viene scritto nel log di debug quando è attivo.

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

Il modulo 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 guía in SISCLINET o nel tuo portale Servientrega. Il contrassegno (logística de recaudo) non viene quotato. Le quotazioni in tempo reale riguardano solo le spedizioni nazionali all'interno della Colombia. Gli altri paesi usano le tariffe fisse.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox ottenuta su vibefox.net. Il blocco licenza License — VibeFox Servientrega è il primo blocco di Modules > Module Manager > VibeFox Servientrega > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopo di che il blocco mostra la chiave mascherata, lo stato (ad 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-servientrega 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 cambiare 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, ad esempio Key not found, This key belongs to another product, Domain limit reached o License expired on seguito da una data. Dopo un cambio dell'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 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 Servientrega non viene mostrato ai clienti al checkout e non viene richiesta né calcolata alcuna tariffa. Lo storefront di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il corriere viene nascosto anche a te: puoi configurare il modulo prima di acquistare una chiave, ma non 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 supporto richiedono un 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. La disinstallazione o il ripristino del modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Servientrega non compare al checkout: verifica che la licenza sia attiva e che Enable Servientrega 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 il Minimum order amount. Senza una tariffa in tempo reale, verifica che il paese o la riga * Default abbia un prezzo, oppure che Fallback cost sia impostato. I prodotti possono anche essere limitati a determinati corrieri nella pagina del prodotto.

Le tariffe in tempo reale non compaiono: attiva il Debug log, ricarica il checkout e guarda il campo Log nella pagina del modulo. Motivi comuni: un tasso di conversione mancante (la valuta del negozio non è il COP), nessun codice DANE di origine, il dipartimento o la città del cliente non sono ancora inseriti o non sono un comune noto, credenziali errate o nessuna 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 fallito il modulo attende 10 minuti prima del tentativo successivo. Salva le impostazioni per riprovare subito.

La città del cliente non viene riconosciuta: fai clic su Add Colombian departments in modo che i clienti possano scegliere il dipartimento. Per le grafie rare, il cliente può digitare il codice DANE a 8 cifre come codice postale.

Le tariffe sembrano obsolete dopo una modifica: fai clic su Save nella pagina del modulo. Questo svuota i preventivi Servientrega in cache e il token.

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

Per gli sviluppatori: gli hook actionVfdSvtgDaneCode e actionVfdSvtgQuoteRequest permettono di modificare il codice DANE di destinazione e la richiesta di preventivo.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Servientrega e scegli Uninstall. La chiave di licenza e lo stato della licenza vengono sempre rimossi. I preventivi in cache, i token e la password cifrata vengono sempre rimossi. Se Remove data on uninstall è attivo, il corriere viene eliminato (gli ordini conservano la cronologia) e le impostazioni e il log vengono rimossi. Se è disattivo, il corriere viene solo disattivato e tutte le impostazioni vengono conservate. Reinstallare il modulo, oppure usare Reset, restituisce al corriere lo stato che aveva prima.

Servientrega è un marchio di proprietà del rispettivo titolare. Questo modulo non è affiliato né approvato da Servientrega.