VibeFox Envioclick for WooCommerce — Aide

Prérequis

WordPress : 5.8 ou ultérieur.

WooCommerce : 5.0 ou ultérieur, installé et actif. Le plugin refuse de s'activer sans lui.

PHP : 8.0 ou ultérieur.

Compte Envioclick (uniquement pour les tarifs en temps réel) : 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 n'utilisez que 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 à l'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 WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP du plugin et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier vfd_envioclick dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox Envioclick, ou cliquez sur Settings sous le nom du plugin sur la page Plugins.

4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.

5. 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 de votre boutique n'est ni MXN ni COP, saisissez le taux de conversion.

6. Facultatif : ajoutez des prix fixes par pays et un coût de secours.

7. Ajoutez VibeFox Envioclick à une zone de livraison dans WooCommerce > Settings > Shipping > Shipping zones, ou activez Ignore shipping zones et choisissez les pays.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Shipping > VibeFox Envioclick. Ils s'appliquent à toutes les zones de livraison. Lorsque vous ajoutez la méthode à une zone, la fenêtre de la zone ne contient qu'un champ :

Title (zone) : le nom que voient les clients pour cette zone. Laissez vide pour utiliser le Method title global.

Lorsqu'une clé d'API est définie, le plugin affiche des avertissements en haut de la page 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. À chaque enregistrement des réglages, les tarifs en cache sont effacés. Les champs numériques acceptent aussi bien le point que la virgule comme séparateur décimal.

General

Enable/Disable : active ou désactive la méthode dans toutes les zones à la fois. Par défaut : activé.

Method title : le nom de la méthode de livraison affiché dans le panier et au moment du paiement. Une zone peut le remplacer. Par défaut : Envioclick Shipping.

Carrier in the title : affiche le transporteur et le délai de livraison estimé à côté du titre pour les tarifs en temps réel, par exemple « Envioclick Shipping (Estafeta Express, 1 day) ». Le transporteur est enregistré dans la commande et affiché dans les e-mails 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. 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, disponible dans Mi cuenta > Información del API.

API country : le pays de votre compte Envioclick.

User-Agent (Mexique) : la valeur fournie par le support d'Envioclick (soporte.tecnico@envioclick.com). Obligatoire pour le Mexique ; sans elle, aucun tarif en temps réel n'est demandé 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 une agence 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é.

Currency conversion rate : Envioclick cote en MXN (Mexique) ou en COP (Colombie). Si la devise 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 manière. Laissez vide si la devise de la boutique est MXN ou COP. Sans 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 de l'adresse de la boutique dans WooCommerce > Settings > General 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á.

Origin address : la rue et le numéro de l'adresse de retrait. 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 hors du pays de l'API, erreur de l'API ou aucun transporteur pour l'itinéraire.

Price per country : un tableau de pays et de prix dans la devise de votre boutique. Cliquez sur + Add country pour ajouter une ligne et sur la croix pour en supprimer une. La ligne * Default s'applique à tous les pays qui n'ont pas leur propre ligne.

Fallback cost : utilisé en l'absence de tarif en temps réel et lorsqu'aucune ligne du tableau ne correspond. Laissez vide pour masquer la méthode 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 en temps réel d'Envioclick 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.

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 : n'affiche la méthode que si le sous-total du panier (après remises, avant taxes) atteint au moins ce montant. Laissez vide pour toujours l'afficher.

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 à l'API. Laissez vide pour ne jamais offrir la livraison gratuite.

Excluded shipping classes : masque la méthode si le panier contient un produit appartenant à l'une de ces classes d'expédition WooCommerce.

Tax status : Taxable ajoute la taxe WooCommerce au coût de livraison, None ne l'ajoute pas. Les tarifs Envioclick incluent déjà les taxes des transporteurs ; choisissez donc None pour ne pas facturer la taxe sur la livraison deux fois.

Disponibilité sans zones de livraison

Ignore shipping zones : propose Envioclick pour les pays indiqués ci-dessous, même si la méthode n'est pas ajoutée à une zone de livraison.

Countries : les pays de destination pour ce mode. Laissez vide pour utiliser tous les pays vers lesquels vous livrez. Utilisé uniquement lorsque Ignore shipping zones est activé.

Avancé

Debug log : journalise les calculs de tarifs et les erreurs de l'API dans WooCommerce > Status > Logs, source vfd_envioclick. La clé d'API et les adresses des clients ne sont pas journalisées. Désactivez-le lorsque vous avez terminé.

Remove data on uninstall : lorsque l'option est activée, la suppression du plugin efface tous les réglages Envioclick, les méthodes de zone et les tarifs en cache. La désactivation du plugin ne supprime jamais les réglages.

Fonctionnement au moment du paiement

Lorsque le client saisit une adresse de livraison, WooCommerce demande au plugin un tarif. Le plugin vérifie d'abord le poids du panier, le montant minimum de commande et les classes d'expédition exclues. Si la livraison gratuite s'applique, la méthode s'affiche au prix de zéro 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 plugin demande à Envioclick des tarifs. 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 le département et la commune reconnus (les accents et la casse n'ont pas d'importance, « Bogotá D.C. » fonctionne). Le plugin retient le tarif de livraison à domicile le moins cher ou le plus rapide qui n'est pas un paiement à la livraison, et le convertit dans la devise de votre boutique.

Le colis est toujours un seul carton : le poids total converti en kg, et la longueur et la largeur de l'article le plus grand 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 la méthode est masquée. La raison est consignée dans le journal de débogage.

La méthode fonctionne sur le paiement classique ainsi que sur les blocs Panier et Paiement. Elle est compatible avec WooCommerce High-Performance Order Storage (HPOS).

Le plugin 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 assurance supplémentaire, ni tarifs multicolis. Les tarifs en temps réel ne concernent que les envois nationaux.

Commandes

Lorsqu'une commande est passée avec un tarif Envioclick en temps réel, le transporteur et le service sont enregistrés dans la commande. L'écran de commande de l'administration affiche Envioclick carrier avec le délai de livraison estimé sous l'adresse de livraison. La page de commande du client et les e-mails de commande (HTML et texte brut) affichent Shipping carrier. L'identifiant du tarif Envioclick de la cotation est enregistré avec la ligne de livraison de la commande sous forme de donnée masquée ; il n'apparaît pas sur l'écran de commande. Créez le bordereau dans votre compte Envioclick.

Les commandes passées au prix fixe n'ont pas de transporteur.

Clé de licence

Le plugin fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Shipping > VibeFox Envioclick. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche l'état, par exemple la date jusqu'à laquelle la licence est active, ainsi que votre domaine. Utilisez Check now pour vérifier à nouveau l'état, Change key pour saisir une autre clé et Remove key pour la retirer de ce site. Le lien Manage licenses and domains in your account ouvre votre compte vibefox.net.

Une clé fonctionne sur un seul domaine. Retirer la clé d'un site ne libère pas l'emplacement de domaine correspondant. Libérez-le dans votre compte vibefox.net.

Sans clé active, Envioclick n'est pas affiché aux clients au moment du paiement. Les gestionnaires de la boutique connectés le voient toujours, avec la mention (unlicensed — visible to admins only), afin que vous puissiez configurer et tester le plugin avant d'acheter une clé. Un rappel apparaît sur la page Plugins et sur les pages WooCommerce. Les commandes existantes ne sont pas affectées.

Lorsqu'une licence arrive à expiration, le plugin continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. L'état est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

Envioclick n'apparaît pas au moment du paiement : vérifiez que la licence est active, que Enable/Disable est activé et que la méthode est ajoutée à la zone du pays du client (ou que Ignore shipping zones est activé et que le pays est autorisé). Contrôlez les limites de poids, Minimum order amount et Excluded shipping classes. Sans tarif en temps réel, la méthode a besoin d'un prix fixe pour le pays, d'une ligne * Default ou d'un Fallback cost.

Les tarifs en temps réel n'apparaissent pas : lisez les avertissements en haut de la page de réglages, puis activez le Debug log, rechargez le paiement et ouvrez WooCommerce > Status > Logs, source vfd_envioclick. 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 l'itinéraire.

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

Colombie : la ville n'est pas reconnue : le client doit choisir le département et saisir le nom de la commune. Un code DANE à 8 chiffres saisi comme code postal fonctionne aussi. Les développeurs peuvent fournir un code DANE avec le filtre vfd_evc_dane_code.

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

Les tarifs semblent obsolètes après une modification : enregistrez la page de réglages. Cela vide les tarifs en cache.

Filtres pour développeurs : vfd_evc_quotation_request (corps de la requête), vfd_evc_api_url, vfd_evc_dane_code, vfd_evc_default_dimensions et vfd_evc_package_description.

Le bloc de licence affiche une erreur : suivez le message affiché dans le bloc. Par exemple, si la clé est déjà utilisée sur un autre domaine, libérez un emplacement dans votre compte vibefox.net et cliquez sur Check now. Si l'adresse du site a changé, cliquez sur Check now pour activer la clé pour le nouveau domaine. Si le serveur de licences est injoignable, le plugin continue de fonctionner avec le dernier état connu.

Désinstallation

La désactivation du plugin conserve tous les réglages et les méthodes de zone ; seuls les tarifs en cache sont effacés. Pour le supprimer, désactivez-le puis supprimez-le sur la page Plugins. La clé de licence et l'état de licence de ce plugin sont toujours supprimés. Les réglages, les méthodes de zone et les tarifs en cache ne sont supprimés que si Remove data on uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Le transporteur enregistré dans les anciennes commandes est conservé, et les commandes existantes gardent leurs lignes de livraison.

Envioclick est une marque appartenant à son titulaire respectif. Ce plugin n'est ni affilié à Envioclick ni approuvé par Envioclick.