VibeFox EasyPost 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 sans elles.

Compte EasyPost (pour les tarifs en temps réel uniquement) : créez un compte sur le site d'EasyPost, connectez vos comptes transporteurs (USPS, UPS, FedEx et d'autres) dans le tableau de bord EasyPost et copiez la clé d'API depuis EasyPost Dashboard > Account Settings > API Keys. EasyPost facture les étiquettes achetées, et non les demandes de tarifs. Si vous n'utilisez que les tarifs de secours, vous n'avez pas besoin de compte EasyPost.

Produits : les produits doivent avoir un poids et, idéalement, des dimensions.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne pour 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 EasyPost plus tard dans la liste des modules et cliquez sur Configure.

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

4. Collez votre clé d'API EasyPost et remplissez l'adresse Ship from. Le code postal est obligatoire pour les tarifs en temps réel.

5. Si la devise par défaut de votre boutique n'est pas l'USD, saisissez le USD exchange rate. Vous pouvez aussi saisir des tarifs de secours (voir Configuration). Cliquez sur Save.

À l'installation, le module crée le transporteur EasyPost Shipping avec le texte de délai de livraison Live carrier rate (EasyPost). 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 EasyPost > Configure. Chaque section possède son propre bouton Save, qui enregistre la page entière. Chaque enregistrement vide aussi les tarifs EasyPost mis en cache.

En haut de la page, le module affiche des avertissements lorsque les tarifs en temps réel ne peuvent pas être utilisés : pas de clé d'API (avec ou sans tarifs de secours), pas de code postal ou de pays d'expédition, ou une devise par défaut autre que l'USD sans taux de change. Une note apparaît également lorsqu'une clé d'API de test est définie, une erreur lorsque le transporteur du module a été supprimé, et un avertissement lorsque l'unité de poids ou de dimensions de votre boutique (International > Localization) n'est pas une unité connue du module (kg, g, lb, oz ; cm, mm, m, in).

Lors de l'enregistrement, une valeur qui n'est pas un nombre (ou qui est négative) n'est pas enregistrée : un avertissement indique le champ concerné et la valeur précédente est conservée. Il en va de même lorsque le USD exchange rate est égal à 0, ou lorsque le Minimum weight est supérieur au Maximum weight.

Général

Enable EasyPost shipping : active ou désactive le transporteur. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers. Par défaut : on.

Name : le nom du transporteur affiché au client lors du paiement, de 64 caractères maximum (un nom plus long est refusé et rien n'est enregistré). Par défaut : EasyPost Shipping. Si le nom est vide ou contient des caractères que PrestaShop n'accepte pas dans le nom d'un transporteur, le nom par défaut est utilisé.

Compte EasyPost

API key : votre clé d'API EasyPost, à récupérer dans EasyPost Dashboard > Account Settings > API Keys. Une clé de production (qui commence par EZAK) renvoie de vrais tarifs. Une clé de test (qui commence par EZTK) renvoie des tarifs de test EasyPost ; ne l'utilisez que pour vos essais. Après l'enregistrement, le champ reste vide et affiche la clé enregistrée masquée, par exemple EZAK******abcd. Laissez le champ vide pour la conserver. Saisissez une nouvelle valeur uniquement pour la modifier.

Remove the saved API key : cochez cette case et cliquez sur Save pour supprimer la clé enregistrée.

Allowed carriers / services : facultatif, séparés par des virgules. Saisissez un transporteur (USPS) ou un transporteur et un service (USPS:Priority, UPS:Ground) tels qu'EasyPost les nomme. Le tarif autorisé le moins cher est affiché. Laissez vide pour afficher le tarif le moins cher de tous les transporteurs.

Expédition depuis

L'adresse depuis laquelle vos colis sont expédiés. Si le Country est le pays de votre boutique, les champs vides sont repris de l'adresse de la boutique dans Shop Parameters > Contact > Stores (et le nom de l'expéditeur du nom de la boutique).

Sender name / company : le nom de l'expéditeur ou de la société.

Street address : la rue de l'adresse d'expédition.

City : la ville de l'adresse d'expédition.

State : le code de l'État sur deux lettres, par exemple CA ou NY.

ZIP code : le code postal de l'adresse d'expédition. Obligatoire pour les tarifs en temps réel.

Country : le pays depuis lequel vous expédiez. Par défaut : United States.

Tarifs

Parcels : la manière dont le panier est envoyé à EasyPost.

One parcel per order (the cart is packed into one box) : toutes les unités sont empilées dans un seul carton et tarifées une fois. C'est la valeur par défaut.

One parcel per item (every unit ships in its own box) : chaque produit est tarifé comme un colis distinct, et le tarif est facturé pour chaque unité. Les tarifs de secours sont également facturés par unité.

Les poids sont convertis de l'unité de votre boutique en onces (minimum 1 oz) et les dimensions en pouces. Si un produit n'a pas de dimensions, le colis est tarifé uniquement au poids.

USD exchange rate : les tarifs EasyPost sont en USD. Saisissez le prix de 1 USD dans votre devise par défaut, par exemple 0.92. Sans ce taux, les tarifs en temps réel ne sont pas utilisés, seulement les tarifs de secours. Il n'est pas nécessaire si la devise par défaut est l'USD. Les boutiques en USD et en CAD demandent à EasyPost de tarifer dans leur propre devise. Le point et la virgule sont tous deux acceptés comme séparateur décimal.

Tax : la règle de taxe du transporteur, ou No tax. Les tarifs EasyPost n'incluent pas la taxe de vente. Choisissez les règles de taxe qui s'appliquent à la livraison.

Tarifs de secours

Utilisés lorsqu'il n'existe aucun tarif en temps réel : pas de clé d'API, EasyPost est injoignable, la clé est refusée, ou aucun transporteur n'a de tarif pour l'adresse. Les prix sont exprimés dans votre devise par défaut, hors taxes. Laissez les deux champs vides pour masquer le transporteur dans ce cas.

Country prices : une ligne par pays : code pays à deux lettres, deux-points et le prix, par exemple US:9.99. Les lignes d'un autre format sont ignorées et listées dans un avertissement à l'enregistrement.

Other countries : le prix pour les pays qui ne figurent pas dans la liste ci-dessus. Laissez vide pour masquer le transporteur pour ces pays.

Conditions

Free shipping from : le sous-total du panier (produits à expédier, après remises, avant taxes, dans votre devise par défaut) à partir duquel la livraison est gratuite. Aucune requête n'est envoyée à EasyPost dans ce cas. Laissez vide pour désactiver cette option.

Minimum subtotal : affiche le transporteur seulement si le sous-total du panier (produits à expédier, après remises, avant taxes) atteint au moins ce montant. Laissez vide pour toujours l'afficher.

Minimum weight : masque le transporteur lorsque le panier pèse moins, dans l'unité de poids de votre boutique (indiquée dans le libellé du champ). 0 signifie aucune limite.

Maximum weight : masque le transporteur lorsque le panier pèse plus, dans l'unité de poids de votre boutique. 0 signifie aucune limite.

Disponibilité sans zones de livraison

Normalement, le transporteur est proposé dans les zones qui lui sont affectées dans Shipping > Carriers. Il peut aussi être proposé par pays, indépendamment des zones.

Ignore shipping zones : propose le transporteur pour les pays indiqués ci-dessous, que leur zone soit ou non affectée au transporteur. Lorsque vous enregistrez avec cette option activée, le transporteur est affecté à toutes les zones, y compris les zones créées ultérieurement. Lorsque vous la désactivez, le transporteur retrouve ses zones précédentes.

Countries : les pays de destination pour ce mode. Utilisez Ctrl+clic pour en sélectionner plusieurs. 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 requêtes EasyPost dans modules/vfd_easypost/logs/vfd_ep.log.php. Le fichier ne peut pas être ouvert depuis le web et il est archivé à 5 Mo. Les erreurs de l'API sont toujours journalisées, même lorsque cette option est désactivée. La clé d'API et les adresses des clients ne sont jamais journalisées.

Remove data on uninstall : lorsque cette option est activée, la désinstallation du module supprime ses réglages, ses tables et son journal. La désactivation du module ne supprime jamais les réglages.

Log : le panneau situé sous les réglages affiche les 100 dernières lignes du journal. Cliquez sur Clear log pour le vider.

Fonctionnement lors du paiement

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

Sinon, le module envoie à EasyPost l'adresse d'expédition, l'adresse de livraison et le colis, et reçoit les tarifs de tous vos comptes transporteurs. Il retient le tarif autorisé le moins cher, le convertit dans votre devise par défaut et l'affiche dans la devise du panier du client. Pour les pays qui exigent un code postal, la requête n'est envoyée que lorsque l'adresse de livraison en contient un. Avant que le client ait saisi une adresse, seul le pays du visiteur est connu ; les pays qui exigent un code postal reçoivent donc le tarif de secours jusqu'à la saisie de l'adresse.

Chaque réponse est mise en cache pendant 1 heure pour la même adresse et le même colis. Une adresse sans tarif utilisable est mémorisée pendant 10 minutes. Après un délai d'attente dépassé, une clé refusée, une limite de débit ou une erreur serveur d'EasyPost, aucune requête n'est envoyée pendant 5 minutes. Le délai d'attente de l'API est de 10 secondes. Dans tous ces cas, le client ne voit aucune erreur : le tarif de secours est utilisé, ou le transporteur est masqué s'il n'existe pas de tarif de secours. La raison est écrite 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 calcule uniquement les tarifs. Il n'achète pas d'étiquettes, ne suit pas les colis, ne valide pas les adresses, ne propose pas de points de retrait ou de dépôt, et n'ajoute pas d'options d'assurance ou de signature. Il affiche une seule option (le tarif autorisé le moins cher), et non une liste de services. Il n'y a pas d'emballage en cartons au-delà du regroupement des articles dans un seul colis, ni de majoration de tarif ni de frais de traitement.

Commandes

Lorsqu'une commande avec le transporteur EasyPost est passée, le tarif affiché au paiement est conservé avec la commande. La page de commande du back office affiche le bloc EasyPost shipping :

Carrier / service : le transporteur et le service EasyPost du tarif, par exemple USPS Priority. En mode un colis par article, tous les services utilisés sont listés.

Estimated delivery days : le nombre de jours de livraison renvoyé par EasyPost (uniquement en mode un colis par commande, lorsque EasyPost les renvoie).

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

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

Les modifications ultérieures du panier dans le back office ne changent pas ces valeurs. Utilisez-les pour acheter l'étiquette dans votre compte EasyPost. Les tarifs des paniers abandonnés sont supprimés après 30 jours.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox EasyPost est le premier bloc de Modules > Module Manager > VibeFox EasyPost > 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-easypost 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 EasyPost n'est pas affiché aux clients lors 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 aussi masqué pour vous : vous pouvez configurer le module avant d'acheter une clé, mais ne pouvez 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 le support 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

EasyPost n'apparaît pas au paiement : vérifiez que la licence est active et que Enable EasyPost shipping est activé. Dans Shipping > Carriers, vérifiez que le transporteur est activé et couvre la zone du pays du client ainsi que le groupe du client (ou que Ignore shipping zones est activé et que le pays est sélectionné). Contrôlez les limites de poids et le Minimum subtotal. Sans tarif en temps réel, le transporteur a besoin d'un tarif de secours pour le pays ou pour Other countries. Des produits peuvent aussi être limités à certains transporteurs sur la page produit.

Les tarifs en temps réel n'apparaissent pas : lisez les avertissements en haut de la page du module, puis activez le Debug log, rechargez le paiement et consultez le panneau Log. Causes fréquentes : pas de clé d'API ni de code postal d'expédition, une boutique non USD sans USD exchange rate, l'adresse de livraison n'a pas encore de code postal, aucun transporteur de votre compte EasyPost ne dessert l'adresse, ou les Allowed carriers / services filtrent tous les tarifs.

Les tarifs ressemblent à des prix de test : une clé de test (EZTK...) est définie. Utilisez une clé de production (EZAK...) sur la boutique en ligne.

Les tarifs ont été interrompus pendant quelques minutes : après un délai d'attente dépassé, une clé refusée ou une erreur serveur d'EasyPost, le module suspend les requêtes pendant 5 minutes et utilise les tarifs de secours. Vérifiez la clé d'API et le journal.

La taxe est-elle incluse ? Les tarifs EasyPost n'incluent pas la taxe de vente. Choisissez la règle de taxe dans Tax pour ajouter la taxe sur la livraison.

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page du module. Cela vide les tarifs EasyPost mis en cache.

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

Hooks pour développeurs : les hooks actionVfdEpShipmentRequest (corps de la requête), actionVfdEpSelectedRate (tarif choisi) et actionVfdEpApiUrl (URL de base de l'API) permettent d'adapter le module.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox EasyPost et choisissez Uninstall. La clé de licence et le statut de la licence sont toujours supprimés. Le transporteur est retiré du paiement (les commandes conservent leur historique), et les tarifs mis en cache sont toujours supprimés. Si Remove data on uninstall est activé, les réglages, les tarifs enregistrés des commandes et le journal sont également supprimés. S'il est désactivé, les réglages et les données EasyPost des commandes passées sont conservés pour une réinstallation. L'installation ou la réinitialisation du module crée un nouveau transporteur. Si les réglages ont été conservés, il reprend le statut (activé ou désactivé) de l'ancien transporteur.

EasyPost est une marque de son propriétaire respectif. Ce module n'est ni affilié à EasyPost ni approuvé par EasyPost.