VibeFox Servientrega for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les anciennes versions de PHP.

Compte Servientrega (pour les tarifs en temps réel uniquement) : les tarifs en temps réel utilisent le Cotizador Corporativo de Servientrega (API de devis corporate). Vous avez besoin d'un compte entreprise (crédit) Servientrega qui y donne accès. Il vous faut trois valeurs : l'utilisateur, le mot de passe et le code de facturation (código de facturación, qui commence généralement par SER). Ce sont vos identifiants SISCLINET, délivrés par votre conseiller commercial Servientrega. Si vous n'utilisez que des tarifs fixes, vous n'avez pas besoin de compte Servientrega.

Accès serveur (pour les tarifs en temps réel uniquement) : votre serveur doit pouvoir joindre web.servientrega.com en HTTP sur le port 8058 (API de devis) et le port 8081 (service web de chiffrement des mots de passe).

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un seul domaine.

Installation

1. Dans le back-office, allez dans Modules > Module Manager et cliquez sur Upload a module. Choisissez le fichier ZIP du module.

2. Une fois le téléversement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Servientrega dans la liste des modules et cliquez sur Configure.

3. Saisissez votre clé de licence VibeFox dans License key, dans le bloc de licence en haut de la page Configure, puis cliquez sur Activate (voir Clé de licence).

4. Pour les tarifs en temps réel, saisissez l'utilisateur, le mot de passe et le code de facturation, choisissez le produit Servientrega, saisissez le code DANE d'origine et, si la devise de votre boutique n'est pas le COP, le taux de conversion de devise. Cliquez sur Add Colombian departments si votre boutique n'en a pas encore (voir Configuration).

5. Facultatif : ajoutez des tarifs fixes par pays et par poids ainsi qu'un coût de repli, puis cliquez sur Save.

À l'installation, le module crée le transporteur Servientrega avec le texte de délai de livraison Servientrega courier delivery. Le transporteur est affecté à toutes les zones et à tous les groupes de clients. Vous pouvez modifier les zones, les groupes de clients, le délai de livraison, le logo et les limites de taille dans Shipping > Carriers. Ne définissez pas de prix à cet endroit : le prix provient toujours du module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Servientrega > Configure. Ils s'appliquent à toutes les zones. Chaque section dispose de son propre bouton Save, qui enregistre la page entière. Chaque enregistrement vide les devis Servientrega en cache et le jeton de connexion.

Si les tarifs en temps réel ne peuvent pas fonctionner avec les réglages enregistrés, un avertissement au-dessus du formulaire indique la raison : utilisateur, mot de passe ou code de facturation manquant, taux de conversion manquant ou code DANE d'origine manquant. Un avertissement apparaît aussi si l'unité de poids ou de dimensions de votre boutique (International > Localization, Local units) n'est pas reconnue par le module ; les poids sont alors lus en kg et les dimensions en cm. Lors de l'enregistrement, une valeur qui n'est pas un nombre, un nombre négatif, un taux de conversion de 0, un poids minimum supérieur au poids maximum, un prix incorrect dans le tableau ou un titre de méthode de plus de 64 caractères est refusé avec une erreur, et rien n'est enregistré.

Général

Enable Servientrega : active ou désactive le transporteur dans toutes les zones à la fois. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers.

Method title : le nom du transporteur affiché au client dans le panier et au moment du paiement. Par défaut : Servientrega. Obligatoire, 64 caractères maximum.

API Servientrega (tarifs en temps réel pour la Colombie) (facultatif ; sans identifiants, seuls les tarifs fixes sont utilisés)

User (login) : votre utilisateur Servientrega / SISCLINET. Le vider supprime aussi le mot de passe enregistré.

Password : votre mot de passe Servientrega / SISCLINET, tel que vous le saisissez. Le module le fait chiffrer par le service web de Servientrega avant la connexion. Après l'enregistrement, le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que si vous voulez la modifier.

Billing code : le código de facturación de votre compte Servientrega, affiché dans SISCLINET. Il commence généralement par SER.

Les trois champs sont nécessaires pour les tarifs en temps réel. Les tarifs en temps réel ne sont demandés que pour les destinations en Colombie. Les autres pays utilisent les tarifs fixes.

Servientrega product : le service de votre contrat Servientrega qui est coté.

Le poids facturé est le plus élevé entre le poids réel et le poids volumétrique.

Currency conversion rate : Servientrega établit ses tarifs en COP. Si la devise par défaut de votre boutique n'est pas le COP, saisissez la valeur de 1 COP dans la devise de votre boutique, par exemple 0.00023. La valeur déclarée du colis est convertie en COP de la même manière. Laissez vide si la devise de votre boutique est le COP. Si votre boutique utilise une autre devise et que ce champ est vide, les tarifs en temps réel ne sont pas utilisés et les tarifs fixes s'appliquent. Le module ne récupère pas les taux de change. Le point et la virgule sont tous deux acceptés comme séparateur décimal.

Colombian departments : le département permet de distinguer les municipalités portant le même nom. PrestaShop n'a pas de départements colombiens par défaut ; sans eux, seuls les noms de ville uniques en Colombie sont reconnus. Cliquez sur Add Colombian departments pour ajouter les 33 départements comme états de Colombie (codes ISO ANT, DC…), activez Contains states pour la Colombie et ajoutez le champ département au formulaire d'adresse colombien. Les départements déjà existants ne sont pas ajoutés en double. Une fois tout en place, le champ indique le nombre de départements dont disposent les adresses colombiennes.

Expédition depuis (utilisé pour les tarifs en temps réel)

Origin city (DANE code) : le code DANE à 8 chiffres de la municipalité d'où vous expédiez, par exemple 11001000 Bogotá, 05001000 Medellín, 76001000 Cali ou 08001000 Barranquilla. Un code de municipalité à 5 chiffres est aussi accepté. Si ce champ est vide et que l'adresse de votre boutique dans Shop Parameters > Contact > Stores est en Colombie, la municipalité de l'adresse de la boutique est utilisée.

Tarifs fixes (utilisés lorsqu'il n'y a pas de tarif en temps réel : pas d'identifiants, destination hors Colombie, municipalité inconnue, taux de conversion manquant, erreur de l'API ou absence de couverture pour l'itinéraire)

Price per country : un tableau de pays et de prix dans la devise par défaut de votre boutique, hors taxes. Cliquez sur Add country pour ajouter une ligne et sur l'icône de corbeille pour en supprimer une. Price s'applique à tout poids. Les colonnes de poids XS ≤1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg et XL >5 kg le remplacent pour ce poids lorsqu'elles sont supérieures à 0. La ligne * Default s'applique à tous les pays qui n'ont pas leur propre ligne. Une ligne sans aucun prix n'est pas enregistrée.

Fallback cost : utilisé lorsqu'il n'y a pas de tarif en temps réel et qu'aucune ligne du tableau ne correspond. Laissez vide pour masquer le transporteur dans ce cas.

Fixed price applies : la manière dont les tarifs fixes sont facturés.

Les tarifs Servientrega en temps réel sont toujours calculés par envoi.

Conditions

Minimum weight : masque le transporteur lorsque le panier pèse moins, en kg. 0 signifie aucune limite.

Maximum weight : masque le transporteur lorsque le panier pèse plus, en kg. Par défaut : 50. 0 signifie aucune limite.

Minimum order amount : n'affiche le transporteur que lorsque le sous-total du panier (après remises, avant taxes) atteint ce montant. Laissez vide pour l'afficher en permanence.

Free shipping from : la livraison est gratuite lorsque le sous-total du panier (après remises, avant taxes) atteint ce montant, et aucune requête n'est envoyée à Servientrega. Cela s'applique à toutes les destinations où le transporteur est proposé, y compris aux pays sans ligne dans le tableau des prix. Laissez vide pour ne jamais proposer la livraison gratuite.

Tax : la règle de taxe du transporteur, ou No tax. Les devis Servientrega (ValorTotal) incluent déjà les frais du transporteur. Choisissez No tax si vous ne voulez pas ajouter de taxe en plus.

Disponibilité sans zones de livraison

Normalement, le transporteur est proposé dans les zones qui lui sont affectées dans Shipping > Carriers.

Ignore shipping zones : propose Servientrega pour les pays indiqués ci-dessous, même si le transporteur n'est pas affecté à leur zone. Le transporteur est alors affecté à toutes les zones, y compris aux zones que vous créerez plus tard. Désactiver l'option rend au transporteur ses zones précédentes.

Countries : les pays de destination pour ce mode. Laissez vide pour utiliser tous les pays actifs de votre boutique. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.

Avancé

Debug log : écrit les calculs de tarifs et les erreurs de l'API dans logs/vfd_svtg_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les identifiants, les jetons et les adresses des clients ne sont pas journalisés. Lorsque le journal est désactivé, rien n'est écrit, erreurs de l'API comprises. Désactivez le journal une fois terminé.

Log : affiche la taille et les dernières entrées du journal de débogage. Cliquez sur Clear log pour le vider.

Remove data on uninstall : lorsqu'elle est activée, la désinstallation du module supprime tous les réglages Servientrega, le transporteur, les devis en cache et les journaux. Les commandes passées conservent leur transporteur. Lorsqu'elle est désactivée, tout est conservé pour une réinstallation.

Fonctionnement au moment du paiement

À l'étape de livraison, PrestaShop demande au module le prix Servientrega. Seuls les produits physiques comptent : les produits virtuels n'ajoutent aucun poids et ne sont pas inclus dans le montant de la commande. Le module vérifie d'abord les conditions : le pays de livraison (avec Ignore shipping zones), le poids du panier et le montant minimum de commande. Si la livraison gratuite s'applique, le prix est de 0 et aucune requête n'est envoyée à Servientrega. Il cherche ensuite un prix : le tarif Servientrega en temps réel, puis le tableau des prix, puis le coût de repli. S'il n'y a pas de prix, le transporteur est masqué pour ce panier.

Pour une destination en Colombie avec des identifiants renseignés, le module trouve le code DANE de la municipalité du client. Il utilise un code DANE saisi comme code postal ou dans le champ ville, ou fait correspondre le département et la ville avec le tableau intégré d'environ 1 130 municipalités. Les accents et « D.C. » sont ignorés. Un nom de ville qui n'existe que dans un seul département est trouvé même sans le département.

Le module envoie ensuite à Servientrega un colis par commande : le poids total converti de l'unité de votre boutique en kg, et une boîte dont la longueur et la largeur correspondent à l'article le plus grand et dont le volume total est celui de l'ensemble des articles, converti en cm. Les produits sans dimensions comptent comme 10 × 10 × 10 cm. La valeur déclarée est le sous-total du panier converti en COP, avec un minimum de 6 000 COP. Servientrega renvoie le total en COP. Le module le convertit dans la devise par défaut de votre boutique, et le client le voit dans la devise de son panier.

Le jeton de connexion est conservé jusqu'à son expiration, au maximum 4 jours. Un jeton refusé est renouvelé automatiquement une fois. Chaque devis est mis en cache pendant 1 heure par itinéraire et par colis, afin que le même panier ne déclenche pas une nouvelle requête. Une requête échouée (chiffrement, connexion ou devis) est mise en cache pendant 10 minutes, afin que le paiement n'attende pas Servientrega à chaque rafraîchissement. Le délai d'attente est de 10 secondes par requête.

Le client ne voit jamais d'erreur de l'API. La raison est écrite dans le journal de débogage lorsqu'il est activé.

Si vous modifiez le transporteur dans Shipping > Carriers alors qu'il a déjà des commandes, PrestaShop l'enregistre comme une nouvelle version du transporteur. Le module suit automatiquement la nouvelle version.

Le module ne calcule que les tarifs. Il ne crée ni guides (guías), ni étiquettes ou autocollants, ne demande pas d'enlèvements, ne suit ni n'annule les envois, et ne permet pas aux clients de choisir un bureau Servientrega (Centro de Soluciones). Créez la guía dans SISCLINET ou dans votre portail Servientrega. Le paiement à la livraison (logística de recaudo) n'est pas coté. Les devis en temps réel ne concernent que les envois nationaux en Colombie. Les autres pays utilisent les tarifs fixes.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Servientrega est le premier bloc de Modules > Module Manager > VibeFox Servientrega > Configure, au-dessus des réglages. Saisissez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, le statut (par exemple la date jusqu'à laquelle la licence est active et votre domaine) ainsi que les boutons Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour retirer la clé de cette boutique. En dessous figurent la ligne Product: presta-shipping-servientrega et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de l'autorisation Configure pour le module peuvent modifier la clé. Les textes du bloc suivent la langue du back office (l'anglais et le russe sont inclus).

Si la clé n'est pas acceptée, le bloc indique la raison, par exemple Key not found, This key belongs to another product, Domain limit reached ou License expired on suivi d'une date. Après un changement d'adresse de la boutique, ou après avoir libéré un emplacement de domaine dans votre compte, cliquez sur Check now. Si le serveur de licences est injoignable, le module continue de fonctionner avec le dernier statut connu.

Une clé fonctionne pour un domaine : le domaine de la boutique principale, y compris dans une configuration multiboutique. Retirer la clé de la boutique ne libère pas son emplacement de domaine. Libérez-le dans votre compte vibefox.net.

Sans clé active, le transporteur Servientrega n'est pas affiché aux clients au moment du paiement, et aucun tarif n'est demandé ni calculé. La partie boutique de PrestaShop ne sait pas que vous êtes connecté au back office : le transporteur est donc aussi masqué pour vous. Vous pouvez configurer le module avant d'acheter une clé, mais ne pas le tester au moment du paiement. Un rappel apparaît dans Modules > Module Manager, sous l'onglet Alerts. Les commandes existantes ne sont pas affectées.

Lorsqu'une licence expire, le module continue de fonctionner, mais les mises à jour et l'assistance nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement pendant votre travail dans le back office : une fois par jour pendant les 14 premiers jours après la saisie de la clé, puis une fois par semaine. Aucune tâche cron n'est nécessaire. La désinstallation ou la réinitialisation du module supprime toujours la clé de licence et le statut de la licence.

Dépannage

Servientrega n'apparaît pas au moment du paiement : vérifiez que la licence est active et que Enable Servientrega est activé. Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone du pays du client et le groupe de clients, ou activez Ignore shipping zones et vérifiez Countries. Contrôlez les limites de poids et le Minimum order amount. Sans tarif en temps réel, vérifiez que le pays ou la ligne * Default a un prix, ou que Fallback cost est défini. Les produits peuvent aussi être limités à certains transporteurs sur leur page produit.

Les tarifs en temps réel n'apparaissent pas : activez le Debug log, rechargez la page de paiement et consultez le champ Log sur la page du module. Causes fréquentes : un taux de conversion manquant (la devise de la boutique n'est pas le COP), aucun code DANE d'origine, le département ou la ville du client n'est pas encore saisi ou n'est pas une municipalité connue, des identifiants incorrects, ou une absence de couverture pour l'itinéraire. Les tarifs fixes couvrent ces cas si vous les avez définis.

La connexion échoue : vérifiez l'utilisateur, le mot de passe et le code de facturation auprès de votre conseiller commercial Servientrega. Après une connexion échouée, le module attend 10 minutes avant le nouvel essai. Enregistrez les réglages pour réessayer immédiatement.

La ville du client n'est pas reconnue : cliquez sur Add Colombian departments pour que les clients puissent choisir leur département. Pour les graphies rares, le client peut saisir le code DANE à 8 chiffres comme code postal.

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page du module. Cela vide les devis Servientrega en cache et le jeton.

La page indique que le transporteur Servientrega est introuvable : le transporteur a été supprimé dans Shipping > Carriers. Réinitialisez le module dans Modules > Module Manager pour le recréer.

Pour les développeurs : les hooks actionVfdSvtgDaneCode et actionVfdSvtgQuoteRequest vous permettent de modifier le code DANE de destination et la requête de devis.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Servientrega et choisissez Uninstall. La clé de licence et le statut de la licence sont toujours supprimés. Les devis en cache, les jetons et le mot de passe chiffré sont toujours supprimés. Si Remove data on uninstall est activé, le transporteur est supprimé (les commandes conservent leur historique) et les réglages et le journal sont supprimés. S'il est désactivé, le transporteur est seulement désactivé et tous les réglages sont conservés. Réinstaller le module, ou utiliser Reset, rend au transporteur le statut qu'il avait auparavant.

Servientrega est une marque de son propriétaire respectif. Ce module n'est pas affilié à Servientrega et n'est pas approuvé par Servientrega.