VibeFox Envioclick 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 Envioclick (pour les tarifs en temps réel uniquement) : un compte Envioclick au Mexique ou en Colombie avec accès à l'API. La clé d'API se trouve dans votre compte Envioclick, sous Mi cuenta (en haut à droite) > Información del API. Si vous utilisez uniquement des prix fixes, vous n'avez pas besoin de compte Envioclick.

User-Agent (Mexique uniquement) : Envioclick Mexique exige une valeur User-Agent pour chaque requête API. Demandez-la au support d'Envioclick (soporte.tecnico@envioclick.com).

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échargement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Envioclick 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. Saisissez la clé d'API, choisissez le pays de l'API, saisissez le User-Agent (Mexique), le code postal ou le code DANE d'origine et l'adresse d'origine. Si la devise par défaut de votre boutique n'est ni MXN ni COP, saisissez le taux de conversion de devise. Pour la Colombie, cliquez sur Add Colombian departments si la page le propose.

5. Vous pouvez ensuite ajouter des prix fixes par pays et un coût de secours, puis cliquer sur Save.

À l'installation, le module crée le transporteur Envioclick Shipping avec le texte de délai de livraison Courier delivery by the best Envioclick carrier. 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 Envioclick > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Chaque enregistrement vide aussi les tarifs Envioclick en cache. Les champs numériques acceptent aussi bien le point que la virgule comme séparateur décimal.

Lorsqu'une clé d'API est définie, la page affiche en haut des avertissements si les tarifs en temps réel ne peuvent pas fonctionner : pas de taux de conversion pour une devise de boutique autre que MXN ou COP, pas de User-Agent pour le Mexique, pas de code postal ou de code DANE d'origine, ou pas d'adresse d'origine pour la Colombie. La page avertit aussi si l'unité de poids ou de dimensions de votre boutique n'est pas reconnue ; définissez kg, g, lb ou oz et cm, mm, m ou in dans International > Localization (Local units). Lors de l'enregistrement, le module vérifie que Method title est un nom de transporteur valide, que les champs numériques contiennent des nombres non négatifs, que Currency conversion rate est supérieur à 0, que Minimum weight n'est pas supérieur à Maximum weight, et que le code d'origine comporte 5 chiffres pour le Mexique ou 8 chiffres (ou le code de commune à 5 chiffres) pour la Colombie. Si une vérification échoue, une erreur s'affiche et rien n'est enregistré.

Général

Les zones, les groupes de clients et les limites de taille du transporteur se définissent dans Shipping > Carriers (ou utilisez Ignore shipping zones ci-dessous). Les réglages de cette page s'appliquent à toutes les zones.

Enable Envioclick : active ou désactive le transporteur. 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 : Envioclick Shipping. Obligatoire.

Carrier in the title : affiche le transporteur Envioclick et le délai de livraison estimé d'un tarif en temps réel sous le transporteur au moment du paiement, par exemple « Estafeta Express, 1 day ». Le transporteur est enregistré avec la commande et affiché sur les pages de commande dans tous les cas. Par défaut : activé.

API Envioclick (tarifs en temps réel)

Facultatif. Sans clé d'API, seuls les prix fixes sont utilisés. La section renvoie à la documentation de l'API Envioclick pour le Mexique et la Colombie. Les tarifs en temps réel ne sont demandés que pour les destinations du pays de l'API. Les envois vers les autres pays utilisent les prix fixes.

API key : votre clé d'API Envioclick, à récupérer dans Mi cuenta > Información del API. Elle est envoyée dans l'en-tête « Authorization ». Après l'enregistrement, le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier.

Remove the saved API key : affiché uniquement lorsqu'une clé est enregistrée. Choisissez Yes et enregistrez pour supprimer la clé ; seuls les prix fixes sont alors utilisés. Une clé saisie dans API key remplace celle qui est enregistrée.

API country : le pays de votre compte Envioclick.

Colombian departments : Colombie uniquement. PrestaShop ne contient pas de départements colombiens par défaut. Sans eux, seuls les noms de villes uniques en Colombie sont reconnus ; le département permet de distinguer les communes portant le même nom. Le bouton Add Colombian departments ajoute les 33 départements comme états de la Colombie (codes ISO ANT, DC, etc.), active « Contains states » pour la Colombie et ajoute le champ département au formulaire d'adresse colombien. Les départements déjà existants ne sont pas ajoutés une seconde fois. Une fois tout en place, le champ indique le nombre de départements dont disposent les adresses colombiennes.

User-Agent (Mexique) : la valeur fournie par le support d'Envioclick (soporte.tecnico@envioclick.com), par exemple EcUserAgent-2/123456. Obligatoire pour le Mexique ; sans elle, les tarifs en temps réel ne sont pas demandés pour le Mexique. Facultatif pour la Colombie.

Choix du transporteur : Cheapest (par défaut) ou Fastest (then cheapest). Envioclick renvoie des tarifs de plusieurs transporteurs et le client reçoit un seul tarif.

Tarifs de retrait en point relais : prend aussi en compte les tarifs « Ocurre », pour lesquels le client récupère le colis dans un point relais du transporteur. Lorsque l'option est désactivée, seuls les tarifs de livraison à domicile sont utilisés. Les services de paiement à la livraison (COD) ne sont jamais utilisés. Par défaut : désactivé.

Taux de conversion de devise : Envioclick cote en MXN (Mexique) ou en COP (Colombie). Si la devise par défaut de votre boutique est différente, saisissez la valeur de 1 MXN ou de 1 COP dans la devise de votre boutique, par exemple 0.05. La valeur déclarée du colis est convertie de la même façon. Laissez le champ vide si la devise de la boutique est MXN ou COP. Sans ce taux, les tarifs en temps réel ne sont pas utilisés dans une autre devise.

Expédition depuis

Utilisé pour les tarifs en temps réel. Les champs vides sont repris depuis l'adresse de la boutique dans Shop Parameters > Contact > Stores si la boutique se trouve dans le pays de l'API.

Origin postcode / DANE code : Mexique : le code postal à 5 chiffres. Colombie : le code DANE à 8 chiffres de la commune, par exemple 11001000 pour Bogotá ; le code de commune à 5 chiffres (11001) fonctionne aussi.

Origin address : la rue et le numéro de l'adresse d'enlèvement. Obligatoire pour la Colombie, facultative pour le Mexique.

Prix fixes

Utilisés en l'absence de tarif en temps réel : pas de clé d'API, destination en dehors du pays de l'API, erreur de l'API ou aucun transporteur pour l'itinéraire.

Price per country : un tableau de codes pays à 2 lettres et de prix dans la devise par défaut de votre boutique, hors taxes. Cliquez sur Add row pour ajouter un pays, et sur l'icône de corbeille pour en supprimer un. Utilisez * comme code pays pour tous les pays sans ligne propre.

Fallback cost : utilisé en l'absence de tarif en temps réel et lorsqu'aucune ligne du tableau ne correspond. Laissez le champ vide pour masquer le transporteur dans ce cas.

Fixed price applies : Per order facture le prix une seule fois. Per item (price × quantity) le multiplie par le nombre d'articles du panier. Les tarifs Envioclick en temps réel sont toujours calculés par envoi.

Conditions

Minimum weight : masque le transporteur en dessous de ce poids du panier, en kg. 0 signifie aucune limite.

Maximum weight : masque le transporteur au-dessus de ce poids du panier, en kg. Par défaut : 25. 0 signifie aucune limite.

Minimum order amount : affiche le transporteur uniquement lorsque le sous-total du panier (après remises, avant taxes) atteint au moins ce montant. Laissez le champ vide pour l'afficher toujours.

Free shipping from : livraison gratuite lorsque le sous-total du panier (après remises, avant taxes) atteint ce montant. Aucune requête n'est alors envoyée à Envioclick. Laissez le champ vide pour ne jamais proposer la livraison gratuite.

Tax : la règle de taxe du transporteur, ou No tax. Les tarifs Envioclick incluent déjà les taxes des transporteurs ; choisissez donc No tax pour ne pas facturer la taxe deux fois sur la livraison.

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 Envioclick pour les pays indiqués ci-dessous, même si le transporteur n'est pas affecté à leur zone. Lorsque vous activez l'option, le transporteur est affecté à toutes les zones, y compris celles créées ultérieurement. Lorsque vous la désactivez, le transporteur retrouve ses anciennes zones.

Countries : les pays de destination pour ce mode. Laissez le champ vide pour utiliser tous les pays vers lesquels vous expédiez (pays actifs). Utilisé uniquement lorsque Ignore shipping zones est activé.

Avancé

Debug log : enregistre les calculs de tarifs et les erreurs de l'API dans logs/vfd_evc_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. La clé d'API et les adresses des clients ne sont pas enregistrées. Rien n'est écrit tant que le journal est désactivé. Désactivez-le lorsque vous avez 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 les réglages Envioclick, le transporteur, les tarifs en cache et les journaux. Le transporteur enregistré avec les anciennes commandes est conservé. 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 Envioclick. 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 : les pays de 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 à Envioclick.

Si une clé d'API est définie et que la destination se trouve dans le pays de l'API, le module demande à Envioclick des tarifs. Au Mexique, la requête est envoyée dès que le client a saisi un code postal à 5 chiffres. En Colombie, elle est envoyée dès que le département et la commune sont reconnus (les accents et la casse n'ont pas d'importance). Le module retient le tarif le moins cher ou le plus rapide qui n'est pas un paiement à la livraison, et le convertit dans la devise par défaut de votre boutique. Le prix s'affiche ensuite dans la devise du panier du client.

Le colis est toujours un seul carton : le poids total converti en kg, et la longueur et la largeur du plus grand article, avec une hauteur qui conserve le volume total de tous les articles. Les produits sans dimensions comptent pour 10 × 10 × 10 cm. Un panier sans poids est envoyé comme 0,5 kg. La valeur déclarée est le sous-total du panier.

Chaque tarif est mis en cache pendant 1 heure pour le même itinéraire et le même colis. Une requête échouée est mise en cache pendant 10 minutes, afin qu'une API indisponible ne ralentisse pas chaque mise à jour du paiement. Le délai d'attente de l'API est de 10 secondes. Si Envioclick renvoie une erreur ou aucun transporteur pour l'itinéraire, le client ne voit aucune erreur : le prix fixe est utilisé, ou le transporteur est masqué. La raison est écrite dans le journal de débogage.

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 des tarifs. Il ne crée ni bordereaux ni étiquettes, ne demande pas d'enlèvements et ne suit ni n'annule les envois. Il propose un seul tarif, et non un choix entre transporteurs, et n'utilise ni services de paiement à la livraison ni devis multi-colis. Les tarifs en temps réel ne concernent que les envois nationaux.

Commandes

Lorsqu'une commande est passée avec le transporteur Envioclick, le tarif calculé pour son panier est enregistré avec la commande et ne change plus. La page de commande de l'administration affiche le bloc Envioclick shipping avec Envioclick carrier, Estimated delivery et Envioclick rate ID (pour un tarif en temps réel), Price source (Envioclick live rate, Fixed price per country, Fallback cost ou Free shipping threshold) et Calculated price (excl. tax). Pour un tarif en temps réel, la page de commande du client affiche Shipping carrier. Créez le bordereau dans votre compte Envioclick.

Les commandes passées avec un prix fixe n'ont pas de transporteur Envioclick.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Envioclick est le premier bloc de Modules > Module Manager > VibeFox Envioclick > 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-envioclick 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 sur un seul domaine : celui 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 l'emplacement dans votre compte vibefox.net.

Sans clé active, le transporteur Envioclick n'est pas affiché aux clients à l'étape de paiement et aucun tarif n'est calculé. La vitrine PrestaShop ne sait pas que vous êtes connecté au back-office, donc le transporteur est masqué pour vous aussi : vous pouvez configurer le module avant d'acheter une clé, mais non le tester au paiement. Un rappel apparaît dans Modules > Module Manager, dans 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 le support nécessitent un renouvellement. Le statut est vérifié 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. Désinstaller ou réinitialiser le module supprime toujours la clé de licence et le statut de la licence.

Dépannage

Envioclick n'apparaît pas au paiement : vérifiez que la licence est active et que Enable Envioclick est activé. Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone du pays du client et le groupe du client, 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, le transporteur a besoin d'un prix fixe pour le pays, d'une ligne * ou d'un Fallback cost. Les produits peuvent aussi être limités à certains transporteurs sur la fiche produit.

Les tarifs en temps réel n'apparaissent pas : lisez les avertissements en haut de la page du module, activez ensuite le Debug log, rechargez le paiement et consultez le champ Log sur la page du module. Causes fréquentes : pas de taux de conversion (la devise de la boutique n'est pas MXN ni COP), pas de User-Agent (Mexique), pas de code postal ou de code DANE d'origine, code postal du client (Mexique) ou ville (Colombie) pas encore saisi, destination hors du pays de l'API, ou aucun transporteur pour l'itinéraire.

Pourquoi un taux de conversion ? Envioclick renvoie des prix uniquement en pesos mexicains ou colombiens. Le module n'affiche jamais un montant en pesos comme s'il s'agissait d'une autre devise.

Colombie : la ville n'est pas reconnue : cliquez sur Add Colombian departments sur la page du module pour que les clients puissent choisir le département, et vérifiez que le nom de la commune est correctement saisi. Un code DANE à 8 chiffres saisi comme code postal fonctionne aussi.

La taxe est facturée deux fois sur la livraison : les tarifs Envioclick incluent déjà les taxes des transporteurs. Réglez Tax sur No tax.

Les tarifs semblent périmés après une modification : cliquez sur Save sur la page du module. Cela vide les tarifs en cache.

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

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Envioclick et choisissez Uninstall. La clé de licence et le statut de la licence sont toujours supprimés. Les tarifs en cache et les tarifs enregistrés des paniers sans commande sont toujours supprimés. Si Remove data on uninstall est activée, le transporteur est supprimé (les commandes conservent leur historique) et les réglages ainsi que le journal sont supprimés. Si elle est désactivée, le transporteur est seulement désactivé et tous les réglages sont conservés. Réinstaller le module rend au transporteur enregistré son statut précédent. Les données Envioclick des commandes passées sont conservées dans les deux cas.

Envioclick est une marque déposée de son propriétaire. Ce module n'est ni affilié à Envioclick ni approuvé par Envioclick.