VibeFox Estafeta for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur avec l'extension cURL. Le module refuse de s'installer sur les anciennes versions de PHP ou sans cURL.

Compte DrEnvio (uniquement pour les tarifs en temps réel) : les tarifs Estafeta en temps réel proviennent de DrEnvio, partenaire d'Estafeta au Mexique. Créez un compte sur drenvio.com, activez Estafeta, configurez-y votre adresse d'enlèvement et copiez la clé API depuis votre panneau DrEnvio. C'est la même clé que celle qu'utilise le module officiel DrEnvio. Si vous utilisez uniquement vos propres tarifs, vous n'avez pas besoin de compte DrEnvio.

Produits : les produits doivent avoir un poids pour les tarifs en temps réel.

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 VibeFox Estafeta plus tard 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 DrEnvio API key et, facultativement, le Origin postcode. Si la devise par défaut de votre boutique n'est pas le MXN, saisissez le MXN exchange rate. Définissez un tarif par pays pour MX ou un Fallback cost si le transporteur doit rester visible lorsque DrEnvio n'a pas de tarif. Cliquez sur Save.

À l'installation, le module crée le transporteur Estafeta avec le texte de délai de livraison Estafeta courier (Mexico). 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. N'y définissez pas de prix : le prix vient toujours du module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Estafeta > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Chaque enregistrement vide aussi le cache des tarifs DrEnvio.

En haut de la page, le module affiche des avertissements : aucune clé API DrEnvio ; une devise par défaut autre que le MXN sans taux de change ; aucun tarif par pays pour MX et aucun coût de repli (le transporteur est alors masqué lorsqu'il n'y a pas de tarif en temps réel, ou n'apparaît jamais sans clé API) ; ou une unité de poids de la boutique que le module ne connaît pas (les poids des produits sont alors pris en kg ; définissez l'unité dans International > Localization, Local units). Les champs numériques acceptent le point ou la virgule comme séparateur décimal. Une valeur qui n'est pas un nombre valide est effacée et signalée lors de l'enregistrement ; les autres réglages sont tout de même enregistrés.

Général

Les zones, les groupes de clients et les limites de taille du transporteur se définissent dans Shipping > Carriers. Ces réglages s'appliquent à toutes les zones.

Enable/Disable : active ou désactive la livraison Estafeta. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers.

Name : le nom du transporteur affiché au client lors du paiement. Par défaut : Estafeta. Obligatoire. Un nom invalide est signalé et l'ancien nom est conservé.

Tax : la règle de taxe du transporteur, ou No tax. La boutique ajoute cette taxe au coût de livraison. Le fait que les tarifs DrEnvio incluent l'IVA dépend de votre compte DrEnvio. S'ils incluent déjà l'IVA, choisissez No tax.

Tarifs en temps réel (API DrEnvio)

Le service Estafeta le moins cher pour l'adresse est proposé. Sans clé, les prix de la section suivante sont utilisés.

DrEnvio API key : la clé API de votre panneau DrEnvio. 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. Mettez-le sur Yes et enregistrez pour supprimer la clé. Seuls les Country prices et le Fallback cost sont alors utilisés. Une clé saisie dans le champ ci-dessus remplace celle qui est enregistrée.

Origin country : le code pays à deux lettres de l'adresse d'enlèvement. Par défaut : MX. Envoyé uniquement avec le code postal d'origine.

Origin postcode : le code postal à 5 chiffres de l'adresse d'enlèvement. Laissez-le vide pour utiliser l'adresse d'origine enregistrée dans votre compte DrEnvio. Un code postal qui ne comporte pas 5 chiffres est effacé et signalé lors de l'enregistrement.

MXN exchange rate : DrEnvio établit ses devis en pesos mexicains. Nécessaire uniquement si la devise par défaut de votre boutique n'est pas le MXN : la valeur de 1 MXN dans votre devise par défaut, par exemple 0.05. Sans lui, les tarifs en temps réel ne sont pas utilisés.

Tarifs sans tarif en temps réel

Utilisés lorsqu'il n'y a pas de clé API ou que DrEnvio ne renvoie aucun tarif Estafeta (API indisponible, code postal inconnu, code postal pas encore saisi). Les prix sont exprimés dans la devise par défaut de votre boutique, hors taxes.

Country prices : un pays de destination par ligne, au format CC:PRICE, par exemple MX:150. Utilisez le point ou la virgule comme séparateur décimal, sans séparateur de milliers. Les parties dans un autre format sont ignorées et signalées lors de l'enregistrement.

Fallback cost : le prix lorsqu'il n'y a ni tarif en temps réel ni tarif par pays. Laissez-le vide pour masquer le transporteur ; 0 signifie livraison gratuite.

Calculation type : Per order facture le prix une seule fois. Per item (price x number of items) le multiplie par le nombre d'articles du panier. Cela s'applique aux Country prices et au Fallback cost. Un tarif DrEnvio en temps réel correspond toujours au prix de l'ensemble du colis.

Conditions

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

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

Min weight : le poids minimum du panier, en kg, pour que le transporteur apparaisse. 0 signifie aucune limite.

Max weight : le poids maximum du panier, en kg. Le transporteur est masqué si ce poids est dépassé. Par défaut : 30. 0 signifie aucune limite.

Si Min weight est supérieur à Max weight, l'enregistrement affiche une erreur et les deux poids restent inchangés. Les poids des produits sont convertis de l'unité de poids de votre boutique en kg.

Disponibilité sans zones de livraison

Ignore shipping zones : propose le transporteur pour les pays indiqués sans configurer de zones pour lui. Tant que l'option est active, le transporteur reçoit toutes les zones, y compris celles que vous créerez plus tard. La désactiver redonne au transporteur ses propres zones.

Countries : les pays de destination pour ce mode, choisis parmi les pays actifs de votre boutique. Laissez vide pour tous les pays. Utilisé uniquement lorsque Ignore shipping zones est activé.

Avancé

Debug log : écrit les requêtes API et les calculs de tarifs dans logs/vfd_est_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs de l'API sont toujours journalisées. La clé API et les adresses des clients ne sont jamais journalisées. Désactivez le journal 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 : si activé, la désinstallation du module supprime tous les réglages du module, le transporteur, les services Estafeta enregistrés des commandes et le journal. Si désactivé, tout est conservé pour une réinstallation.

Fonctionnement au paiement

À l'étape de livraison, PrestaShop demande au module le prix Estafeta. Seuls les produits physiques comptent : les produits virtuels n'ajoutent aucun poids et ne sont pas inclus dans le sous-total. Le module vérifie d'abord les conditions : la liste Countries (lorsque Ignore shipping zones est activé), le poids du panier et le sous-total minimum. Si la livraison gratuite s'applique, le prix est de 0 et aucune requête n'est envoyée à DrEnvio.

Sinon, le module envoie à DrEnvio le pays et le code postal de destination, le poids du panier, le nombre d'articles et le sous-total en MXN, ainsi que le code postal d'origine si vous en avez défini un. Les codes postaux mexicains doivent comporter 5 chiffres ; tant que le client n'a pas saisi une adresse de livraison qui en comporte 5, aucune requête n'est envoyée. DrEnvio renvoie les devis de tous les transporteurs de votre compte. Le module n'utilise que les devis Estafeta, ignore les prix nuls, retient le moins cher et le convertit dans votre devise par défaut. Le prix est ensuite affiché dans la devise du panier du client.

Chaque réponse est mise en cache pendant 1 heure. Une requête échouée ou un trajet sans tarif Estafeta est mémorisé pendant 5 minutes, afin qu'une API lente ou défaillante ne ralentisse jamais chaque mise à jour du paiement. Le délai d'attente de l'API est de 12 secondes. Dans ces cas, le client ne voit aucune erreur : le tarif par pays ou le coût de repli est utilisé, ou le transporteur est masqué si aucun des deux n'est défini. La raison est consignée dans le journal.

Si vous modifiez le transporteur dans Shipping > Carriers après qu'il a reçu 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 pas d'envois, n'imprime pas d'étiquettes (guías) et ne suit pas les colis ; créez l'envoi dans votre compte DrEnvio ou Estafeta. Le client ne peut pas choisir un service Estafeta précis ni un bureau Estafeta, et les taux de change ne sont pas mis à jour automatiquement.

Commandes

Lorsqu'une commande avec le transporteur Estafeta est passée, le module conserve le tarif calculé pour son panier. Les recalculs ultérieurs, par exemple sur la page de commande du back office, ne le modifient pas.

La page des commandes dans Orders > Orders affiche un bloc Estafeta :

Estafeta service : le service Estafeta du devis DrEnvio et son délai de livraison. Affiché uniquement pour les tarifs en temps réel.

Price source : Live DrEnvio rate, Country price (no live rate), Fallback cost (no live rate) ou Free shipping threshold.

Calculated price (excl. tax) : le prix de livraison dans votre devise par défaut.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Estafeta est le premier bloc de Modules > Module Manager > VibeFox Estafeta > 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) et 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. Plus bas figurent la ligne Product: presta-shipping-estafeta 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-le dans votre compte vibefox.net.

Sans clé active, le transporteur Estafeta n'est pas affiché aux clients au moment du 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é aussi pour vous : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au paiement. Un rappel apparaît dans Modules > Module Manager, sur 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é 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

Estafeta n'apparaît pas au paiement : vérifiez que la licence est active et que Enable/Disable est activé. Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone du pays du client et le groupe du client (ou que Ignore shipping zones est activé et que le pays est autorisé). Consultez les avertissements en haut de la page du module, les limites de poids et le Minimum subtotal. Sans clé API, ou lorsque DrEnvio n'a pas de tarif Estafeta, le transporteur a besoin d'un tarif par pays pour la destination ou d'un coût de repli. Les produits peuvent aussi être limités à certains transporteurs sur la page du 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. Il indique la raison : aucune clé API ; aucun taux de change pour une boutique dont la devise par défaut n'est pas le MXN ; un code postal absent ou invalide ; une clé API rejetée (DrEnvio HTTP 401 ou 403, vérifiez la clé API) ; aucun tarif Estafeta pour le trajet (le journal liste les transporteurs renvoyés par DrEnvio) ; ou un tarif dans une devise autre que le MXN.

Le prix inclut-il l'IVA ? Cela dépend de votre compte DrEnvio. Si les tarifs DrEnvio incluent déjà l'IVA, 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 le cache des tarifs DrEnvio.

La page indique que le transporteur Estafeta est introuvable : le transporteur a été supprimé dans Shipping > Carriers. Réinitialisez le module dans Modules > Module Manager pour le recréer. Il en va de même pour le message The settings were saved, but the carrier could not be updated.

La page de commande n'a pas de bloc Estafeta : le bloc n'est affiché que pour les commandes passées avec le transporteur Estafeta pendant que le module était installé. Désinstaller avec Remove data on uninstall activé supprime les services enregistrés.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Estafeta et choisissez Uninstall. La clé de licence et le statut de la licence sont toujours supprimés. Les tarifs en cache sont toujours supprimés. Si Remove data on uninstall est activé, le transporteur est supprimé (les commandes conservent leur historique), et les réglages, les services Estafeta enregistrés des commandes et le journal sont supprimés. S'il est désactivé, le transporteur est seulement désactivé, et les réglages et les services enregistrés des commandes sont conservés. Réinstaller le module rend au transporteur le statut qu'il avait avant la désinstallation.

Estafeta et DrEnvio sont des marques de leurs propriétaires respectifs. Ce module n'est ni affilié ni approuvé par Estafeta ou DrEnvio.