VibeFox Envioclick for OpenCart — Aide

Prérequis

OpenCart : 3.0.x (testé avec 3.0.5.0) ou 4.0.2 et ultérieur (testé avec 4.1.0.3).

PHP : 8.0 ou ultérieur.

Compte Envioclick (uniquement pour les tarifs en direct) : un compte Envioclick au Mexique ou en Colombie, avec accès à l'API. La clé API se trouve dans votre compte Envioclick, sous Mi cuenta (en haut à droite) > Información del API. Si vous n'utilisez que des tarifs 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

Le téléchargement est un seul fichier zip contenant les paquets pour les deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 vfd_envioclick-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_envioclick.ocmod.zip. N'installez que le paquet de votre version d'OpenCart. La clé de licence est la même pour les deux versions.

OpenCart 3

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_envioclick-oc3-(version).ocmod.zip. L'extension n'ajoute aucune modification OCMOD : vous n'avez donc pas à actualiser Extensions > Modifications. Au lieu de l'installateur, vous pouvez aussi copier le contenu du dossier upload de ce paquet dans le dossier racine de votre boutique.

2. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox Envioclick et cliquez sur Install (le bouton vert +).

3. Cliquez sur Edit (le bouton en forme de crayon) pour ouvrir la page des paramètres.

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

5. Saisissez la clé API, choisissez le pays de l'API, saisissez le User-Agent (Mexique), le code postal d'origine ou le code DANE 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. Vous pouvez éventuellement ajouter des tarifs fixes par pays et un coût de repli. Activez Enable Envioclick et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_envioclick.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 prend le code de l'extension dans le nom du fichier, et un paquet renommé ne fonctionne pas.

2. Le paquet apparaît dans la liste des extensions installées, sur la même page. Cliquez sur Install (le bouton vert +) à côté.

3. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox Envioclick, cliquez sur Install (le bouton vert +), puis sur Edit (le bouton en forme de crayon).

4. Saisissez la clé de licence et les paramètres comme aux étapes 4 et 5 pour OpenCart 3. La page des paramètres et ses champs sont identiques dans les deux versions.

Après l'installation, la méthode reste désactivée tant que vous n'avez pas activé Enable Envioclick et enregistré. Si vous réinstallez l'extension après une désinstallation, les paramètres Envioclick que vous avez conservés sont de nouveau utilisés.

Configuration

Tous les paramètres se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox Envioclick > Edit. Les sections sont listées à gauche. Un bouton Save en bas enregistre la page entière sans la recharger. Chaque enregistrement vide également les tarifs Envioclick en cache. Les champs numériques acceptent aussi bien le point que la virgule comme séparateur décimal. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les paramètres.

La section General affiche des avertissements lorsque les tarifs en direct ne peuvent pas fonctionner avec les paramètres enregistrés : 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. Elle avertit également si l'unité de poids ou de longueur de la boutique n'est pas reconnue ; ajoutez alors une classe de poids avec l'unité kg dans System > Localisation > Weight Classes, ou une classe de longueur avec l'unité cm dans System > Localisation > Length Classes. À l'enregistrement, l'extension vérifie que Method title compte de 1 à 64 caractères, que les champs numériques contiennent des nombres non négatifs, que Currency conversion rate est supérieur à 0, que Minimum weight (kg) n'est pas supérieur à Maximum weight (kg), que le code d'origine compte 5 chiffres pour le Mexique ou 8 chiffres (ou le code de commune à 5 chiffres) pour la Colombie, que chaque ligne de Price per country comporte un pays valide et un prix, et que Sort order est un nombre entier. Si une vérification échoue, rien n'est enregistré et la page liste les erreurs.

Général

Le client voit un seul tarif Envioclick, celui du transporteur le moins cher ou le plus rapide. Vous pouvez limiter la méthode à une zone géographique ou à des pays dans Availability.

Enable Envioclick : affiche ou masque Envioclick au paiement. Par défaut : désactivé.

Method title : le nom du mode de livraison affiché au client dans le panier et au paiement, 64 caractères maximum. Par défaut : Envioclick Shipping. Obligatoire.

Carrier in the title : ajoute au titre le transporteur Envioclick et le délai de livraison estimé d'un tarif en direct, par exemple « Envioclick Shipping (Estafeta Express, 1 day) ». OpenCart enregistre ce titre avec la commande, il apparaît donc aussi dans les e-mails de commande et les pages de commande. Le transporteur est de toute façon enregistré dans la commande. Par défaut : activé.

Sort order : la position d'Envioclick parmi les modes de livraison au paiement. Un nombre entier.

API Envioclick (tarifs en direct)

Facultatif. Sans clé API, seuls les tarifs fixes sont utilisés. La section renvoie vers la documentation de l'API Envioclick pour le Mexique et la Colombie. Les tarifs en direct ne sont demandés que pour les destinations du pays de l'API. L'expédition vers les autres pays utilise les tarifs fixes.

API key : votre clé API Envioclick, disponible dans Mi cuenta > Información del API. Elle est envoyée dans l'en-tête « Authorization » et n'est jamais affichée aux clients ni écrite dans le journal. Après l'enregistrement, le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier.

Remove the saved API key : activez cette option et enregistrez pour supprimer la clé enregistrée ; seuls les tarifs fixes sont alors utilisés. Une clé saisie dans API key remplace celle qui est enregistrée. L'interrupteur se désactive automatiquement après l'enregistrement.

API country : le pays de votre compte Envioclick.

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

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

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

Currency conversion rate : Envioclick établit les tarifs 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 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 ce champ vide si la devise de la boutique est MXN ou COP. Sans ce taux, les tarifs en direct ne sont pas utilisés dans une autre devise.

Expédition depuis

Utilisé pour les tarifs en direct. OpenCart ne dispose pas du code postal, de la ville ni de la rue de votre boutique : saisissez-les ici.

Origin postcode / DANE code : Mexique : le code postal à 5 chiffres. Colombie : le code DANE à 8 chiffres de la commune, par exemple 11001000 pour Bogotá ; un code de commune à 5 chiffres (11001) est complété par 000.

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

Tarifs fixes

Utilisés lorsqu'il n'existe pas de tarif en direct : pas de clé API, destination hors du pays de l'API, erreur de l'API ou absence de transporteur pour le trajet.

Price per country : une liste 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 le bouton × pour en supprimer une. Choisissez * All other countries pour un prix appliqué à chaque pays qui n'a pas sa propre ligne.

Fallback cost : utilisé lorsqu'il n'existe pas de tarif en direct et qu'aucune ligne du tableau ne correspond. Laissez ce champ vide pour masquer la méthode dans ce cas.

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

Conditions

Minimum weight (kg) : masque la méthode en dessous de ce poids de panier. 0 signifie aucune limite (par défaut).

Maximum weight (kg) : masque la méthode au-dessus de ce poids de panier. Par défaut : 25. 0 signifie aucune limite.

Minimum order amount : affiche la méthode seulement si le sous-total des produits à expédier (après le coupon, avant la taxe) atteint au moins ce montant. Laissez ce champ vide pour toujours l'afficher.

Free shipping from : livraison gratuite lorsque le sous-total des produits à expédier (après le coupon, avant la taxe) atteint ce montant. Aucune requête n'est alors envoyée à l'API. Laissez ce champ vide pour ne jamais offrir la livraison gratuite.

Tax class : la classe de taxe du coût de livraison, ou No tax (par défaut). Les tarifs Envioclick incluent déjà les taxes des transporteurs : choisissez donc No tax pour éviter de facturer deux fois la taxe sur la livraison.

Disponibilité

En général, la méthode est proposée pour les adresses de la zone géographique sélectionnée, ou partout.

Geo zone : proposer Envioclick uniquement pour les adresses de cette zone géographique. All zones (par défaut) signifie aucune limite. Les zones géographiques se gèrent dans System > Localisation > Geo Zones. Elle n'est pas vérifiée lorsque Ignore shipping zones est activé.

Ignore shipping zones : ne vérifie pas la zone géographique ; c'est la liste de pays ci-dessous qui décide. Par défaut : désactivé.

Countries : les pays de destination pour ce mode. Laissez ce champ vide pour autoriser tous les pays. Utilisé uniquement lorsque Ignore shipping zones est activé.

Avancé

Debug log : consigne les calculs de tarifs et les erreurs de l'API dans storage/logs/vfd_evc_debug.log.php (sur OpenCart 4, system/storage/logs/vfd_evc_debug.log.php). Le fichier ne peut pas être lu depuis le web. La clé API et les adresses des clients ne sont pas consignées. Rien n'est écrit tant que le journal est désactivé, pas même les erreurs de l'API. Désactivez-le lorsque vous avez terminé. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_evc_debug.old.log.php et un nouveau journal est démarré.

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 : lorsque cette option est activée, la désinstallation de l'extension supprime les paramètres Envioclick, les tarifs en cache et le journal. Lorsqu'elle est désactivée (par défaut), ils sont conservés pour une réinstallation. Les données Envioclick des commandes passées sont toujours conservées.

Import / Export

Export : cliquez sur Download JSON pour enregistrer les paramètres dans un fichier JSON. La clé API n'est pas exportée.

Import : collez un JSON exporté précédemment et cliquez sur Import pour restaurer les paramètres, par exemple sur une autre boutique. Les valeurs sont vérifiées comme lors d'un enregistrement normal. La clé API enregistrée est conservée.

Fonctionnement au paiement

Lorsqu'OpenCart affiche les modes de livraison, il demande à l'extension le prix Envioclick. Si une Geo zone est définie (et que Ignore shipping zones est désactivé) et que l'adresse se trouve en dehors, Envioclick n'est pas proposé. Seuls les produits dont Requires Shipping est réglé sur Yes comptent : les autres produits n'ajoutent pas de poids et ne sont pas inclus dans le montant de la commande. L'extension vérifie ensuite les conditions : les pays de Ignore shipping zones, le poids du panier et le montant minimum de commande. Le montant de la commande correspond au prix des produits à expédier, après déduction du coupon et avant taxes. Les cartes cadeaux, les points de fidélité et les avoirs de la boutique ne sont pas pris en compte. Si la livraison gratuite s'applique, le prix est de 0 et aucune requête n'est envoyée à Envioclick.

Si une clé API est définie et que la destination se trouve dans le pays de l'API, l'extension demande des tarifs à Envioclick. Au Mexique, la requête est envoyée une fois que le client a saisi un code postal à 5 chiffres. En Colombie, elle est envoyée une fois que la commune est reconnue à partir d'un code DANE à 8 chiffres dans le champ du code postal, ou à partir du département (la région de l'adresse OpenCart) et de la ville ; un nom de ville unique en Colombie est reconnu sans le département. Les accents et la casse n'ont pas d'importance. L'extension retient le tarif le moins cher ou le plus rapide qui ne soit pas un paiement à la livraison, puis le convertit dans la devise par défaut de votre boutique. Le prix est arrondi aux décimales de cette devise et affiché au client dans sa devise, avec la taxe de la Tax class sélectionnée.

Le colis est toujours un seul carton : le poids total converti en kg à partir des classes de poids des produits, et une taille de carton déduite des dimensions des produits converties en cm. Les produits sans dimensions comptent pour 10 × 10 × 10 cm. Un panier sans aucun poids est envoyé comme 0,5 kg. La valeur déclarée est le montant de la commande.

Chaque tarif est mis en cache pendant 1 heure pour le même trajet et le même colis. Une requête en échec est mise en cache pendant 10 minutes, afin qu'une API indisponible ne ralentisse pas chaque mise à jour du paiement. Si Envioclick renvoie une erreur ou aucun transporteur pour le trajet, le client ne voit aucune erreur : le prix fixe ou le coût de repli est utilisé, ou la méthode est masquée. La raison est consignée dans le journal de débogage lorsque celui-ci est activé.

L'extension ne calcule que des tarifs. Elle ne crée ni bordereaux ni étiquettes, ne demande pas d'enlèvement et ne suit ni n'annule d'expéditions. Elle propose un seul tarif, et non un choix entre transporteurs, et n'utilise ni services à paiement à la livraison ni tarifs multi-colis. Les tarifs en direct ne concernent que les envois nationaux.

Sur OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison de la page de paiement et choisit Envioclick dans la fenêtre Shipping method options. La méthode fonctionne de la même façon que sur OpenCart 3.

Commandes

Lorsqu'une commande est passée avec Envioclick, le tarif calculé au paiement est enregistré avec la commande et ne change plus. Dans Sales > Orders, la page de commande affiche le panneau Envioclick shipping avec Envioclick carrier, Estimated delivery et Envioclick rate ID (pour un tarif en direct), Price source (Envioclick live rate, Fixed price per country, Fallback cost ou Free shipping threshold) et Calculated price (excl. tax). Le panneau reste affiché même après la désactivation de la méthode.

Sur OpenCart 4, le paiement conserve une seule commande et la met à jour à chaque fois que le client confirme à nouveau. Le tarif enregistré est alors remplacé par le dernier tarif du paiement. Si le client passe à un autre mode de livraison, le panneau n'est plus affiché pour cette commande. Les modifications de la commande dans l'administration ne changent pas le tarif enregistré.

Si Carrier in the title est activé, le transporteur fait partie du nom du mode de livraison de la commande. S'il est désactivé, une ligne Shipping carrier: indiquant le transporteur d'un tarif en direct est ajoutée à l'e-mail de nouvelle commande et à la page de commande dans le compte du client, tant que l'extension est activée. Créez le bordereau dans votre compte Envioclick. Les commandes passées à prix fixe n'ont pas de transporteur Envioclick.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Envioclick est le premier bloc de Extensions > Extensions > Shipping > VibeFox Envioclick > Edit, au-dessus des paramètres. Saisissez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, le statut (par exemple la date de fin de validité de la licence 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 supprimer la clé de cette boutique. En dessous se trouvent la ligne Product: opencart-shipping-envioclick et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les administrateurs disposant de l'autorisation Modify pour l'extension peuvent modifier la clé. Les textes du bloc suivent la langue de l'administration (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, l'extension continue de fonctionner avec le dernier statut connu.

Une clé fonctionne sur un seul domaine : l'adresse de la boutique issue de la configuration d'OpenCart. 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, Envioclick n'est pas affiché aux clients au paiement et aucun tarif n'est calculé. Un utilisateur administrateur connecté à l'administration dans le même navigateur voit toujours la méthode dans la boutique, marquée (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Sur OpenCart 4, cet aperçu n'est pas disponible : la boutique ne voit pas la connexion à l'administration, donc sans clé active la méthode est masquée pour tout le monde. Une fois la page Edit ouverte une fois, un rappel apparaît sur le Dashboard de l'administration. Fermez-le avec × pour le masquer pendant 7 jours. Les commandes existantes ne sont pas affectées.

Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement lorsque vous ouvrez le Dashboard de l'administration ou la page Edit : 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 de l'extension 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é. Vérifiez Geo zone, ou Ignore shipping zones et Countries, les limites de poids et Minimum order amount. Sans tarif en direct, la méthode nécessite un prix fixe pour le pays, une ligne * All other countries ou un Fallback cost. Vérifiez que les produits ont Requires Shipping réglé sur Yes.

Les tarifs en direct n'apparaissent pas : lisez les avertissements de la section General, puis activez Debug log, rechargez le paiement et consultez le champ Log sur la page de l'extension. Causes fréquentes : pas de taux de conversion (la devise de la boutique n'est ni 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 le trajet.

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

Colombie : la ville n'est pas reconnue : vérifiez que le client sélectionne le département comme région de l'adresse et qu'il saisit correctement le nom de la commune. Un code DANE à 8 chiffres saisi comme code postal fonctionne également.

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

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page de l'extension. Cela vide les tarifs en cache.

La page affiche « Warning: You do not have permission to modify VibeFox Envioclick! » : votre groupe d'utilisateurs administrateurs ne peut que consulter les paramètres. Accordez à ce groupe l'autorisation de modification pour extension/shipping/vfd_envioclick (OpenCart 3) ou extension/vfd_envioclick/shipping/vfd_envioclick (OpenCart 4) dans System > Users > User Groups.

Pour les développeurs : l'adresse de l'API de cotation d'Envioclick peut être remplacée par le paramètre vfd_evc_api_url (pour les tests) ; il n'existe pas de champ pour lui sur la page des paramètres.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox Envioclick. OpenCart réinitialise toujours Enable Envioclick, Sort order, Tax class et Geo zone. Les tarifs en cache sont toujours supprimés. Si Remove data on uninstall est activé, les paramètres Envioclick et le journal de débogage sont également supprimés. Si l'option est désactivée, les autres paramètres sont conservés et réutilisés lors d'une nouvelle installation de l'extension. Les données Envioclick des commandes passées sont conservées dans les deux cas, et les commandes gardent leur mode de livraison et leur coût.

Pour supprimer aussi les fichiers de l'extension sur OpenCart 4, allez dans Extensions > Installer après la désinstallation, cliquez sur Uninstall (le bouton orange −) à côté de VibeFox Envioclick dans la liste des extensions installées, puis sur Delete (le bouton rouge en forme de corbeille) pour supprimer le paquet envoyé.

Envioclick est une marque déposée de son propriétaire. Cette extension n'est pas affiliée à Envioclick et n'est pas approuvée par Envioclick.