VibeFox FedEx for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur avec l'extension cURL. Sans elles, le module refuse de s'installer.

Compte FedEx et clés d'API (pour les tarifs en temps réel uniquement) : sur le FedEx Developer Portal (developer.fedex.com), créez un projet avec la Rate API, associez votre compte d'expédition FedEx et copiez l'API Key et la Secret Key. Vous avez aussi besoin de votre numéro de compte FedEx à 9 chiffres. Les clés de test ne fonctionnent qu'avec Sandbox activé, et les clés de production uniquement avec celui-ci désactivé. Le module utilise l'API REST de FedEx avec OAuth 2.0 ; il n'a besoin ni de numéro de compteur ni de mot de passe des services web. Si vous n'utilisez que des prix fixes, vous n'avez pas besoin de clés FedEx.

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éversement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox FedEx 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 l'API Key, la Secret Key, le numéro de compte FedEx à 9 chiffres et l'adresse d'expédition Ship from (code postal et, pour les États-Unis et le Canada, le code d'état à 2 lettres). Désactivez Sandbox si vous utilisez des clés de production. Vous pouvez aussi saisir des prix fixes en solution de secours. Cliquez sur Save.

À l'installation, le module crée le transporteur FedEx avec le texte de délai de livraison FedEx delivery. 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 FedEx > Configure. Ils s'appliquent à toutes les zones du transporteur. Chaque section a son propre bouton Save, qui enregistre la page entière. Chaque enregistrement vide aussi le jeton FedEx et les tarifs mis en cache.

En haut de la page, le module affiche des avertissements : seules certaines des trois informations d'identification de l'API sont renseignées, aucune clé d'API ni aucun prix fixe (le transporteur n'est alors jamais affiché), aucun code postal d'expédition, aucun code d'état d'expédition pour les États-Unis ou le Canada, une devise de boutique différente de la devise du compte FedEx sans taux de change, une unité de poids de la boutique (ou, avec une taille de carton, une unité de dimension) que le module ne connaît pas, ou un transporteur supprimé. Les champs numériques acceptent un point ou une virgule décimale. Un nombre ou une taille de carton non valide, un taux de change de 0, une devise de compte qui n'est pas un code à 3 lettres et un nom de plus de 64 caractères ne sont pas enregistrés et sont signalés ; le champ conserve sa valeur précédente et les autres champs sont enregistrés. Un poids minimum supérieur au poids maximum est également signalé, et les deux poids conservent leurs valeurs précédentes.

Général

Enable/Disable : active ou désactive l'expédition par FedEx. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers.

Name : le nom du mode d'expédition affiché au client lors du paiement (le nom du transporteur). Par défaut : FedEx. Obligatoire.

Tax status : la règle de taxe du transporteur, ou No tax. Avec une règle de taxe (et des taxes activées dans la boutique), PrestaShop ajoute la taxe au coût de livraison ; c'est donc le montant FedEx hors taxes qui est utilisé. Avec No tax, le montant net FedEx est utilisé tel quel.

API FedEx (tarifs en temps réel)

Sans clés, les prix fixes ci-dessous sont utilisés. La section contient le bouton Clear cached FedEx token and rates.

Sandbox : utilise le sandbox de FedEx (apis-sandbox.fedex.com) avec des clés de test. Désactivez-le pour obtenir des tarifs réels (apis.fedex.com) avec des clés de production. Par défaut : activé.

API Key : l'API Key (client_id) de votre projet sur le FedEx Developer Portal.

Secret Key : la Secret Key (client_secret) du même projet. Après l'enregistrement, le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que si vous voulez la modifier. Vider l'API Key supprime aussi la Secret Key enregistrée.

FedEx account number : le numéro de compte d'expédition FedEx à 9 chiffres associé au projet. Les tarifs de compte (négociés) sont calculés pour ce compte.

Rates : Account rates (your negotiated FedEx prices) (par défaut) ou List rates (FedEx published prices).

Residential delivery : calcule les adresses des clients comme résidentielles (FedEx Home Delivery, supplément pour livraison résidentielle). Désactivez-le si vous expédiez surtout à des entreprises. Par défaut : activé.

Box size : dimensions facultatives du carton, dans l'unité de dimension de votre boutique, par exemple 30x20x15. FedEx applique alors le poids volumétrique. Laissez le champ vide pour calculer uniquement au poids.

FedEx account currency : la devise de votre compte FedEx, par exemple USD pour les comptes américains ou CAD pour le Canada. Par défaut : USD. FedEx est toujours invité à établir ses tarifs dans la devise par défaut de la boutique.

Exchange rate : nécessaire uniquement lorsque FedEx ne renvoie des tarifs que dans la devise du compte et que la devise par défaut de votre boutique est différente : le prix de 1 unité de la devise du compte dans votre devise par défaut, par exemple 0.92. Sans lui, ces tarifs ne sont pas utilisés.

Expédition depuis

L'adresse à laquelle FedEx vient chercher les colis ou à laquelle vous les déposez. Utilisée pour les tarifs en temps réel.

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

State / province code : le code à 2 lettres, obligatoire pour les États-Unis et le Canada, par exemple TN, CA ou ON.

City : la ville d'expédition.

ZIP / postal code : le code postal d'expédition. FedEx en a besoin pour calculer les tarifs.

Prix fixes

Ils sont utilisés lorsqu'aucune clé d'API n'est saisie, et en solution de secours lorsque FedEx ne renvoie aucun tarif (API indisponible, clés erronées, aucun service). Laissez les deux champs vides pour masquer le transporteur dans ce cas.

Country prices : un tableau de codes pays de destination à 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 autres pays. Les lignes qui ne sont pas un code pays (ou *) avec un prix sont ignorées et signalées à l'enregistrement.

Fallback cost : un prix forfaitaire lorsqu'aucun prix par pays ne correspond. Laissez-le vide pour masquer le transporteur.

Fixed price is : 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 ne concerne que les prix fixes. Les tarifs FedEx en temps réel sont toujours calculés pour le poids total du panier.

Conditions

Free shipping from : le sous-total du panier (après remises, hors taxes) à partir duquel ce transporteur est gratuit. Laissez le champ vide pour ne jamais offrir la livraison gratuite.

Minimum subtotal : n'affiche le transporteur que si le sous-total du panier atteint au moins ce montant. Laissez le champ vide pour l'afficher toujours.

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

Max weight : le poids maximum du panier en kg. Le transporteur est masqué s'il est dépassé. 0 signifie sans limite.

Default product weight : le poids en kg utilisé pour les produits sans poids, pour les tarifs FedEx et pour les limites de poids ci-dessus. Par défaut : 0.5. Les poids des produits sont convertis à partir de l'unité de poids de votre boutique (kg, g, lb ou oz), définie dans International > Localization (Local units).

Disponibilité sans zones d'expédition

Ignore shipping zones : propose le transporteur pour les pays ci-dessous même si leur zone ne lui est pas attribuée. À l'enregistrement, le transporteur est lié à toutes les zones, y compris celles créées plus tard. Le désactiver rend au transporteur ses zones précédentes.

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

Avancé

Debug log : enregistre les requêtes à l'API et le calcul des tarifs dans logs/vfd_fdx_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs d'API sont toujours enregistrées. Les clés, les jetons et les adresses des clients ne sont jamais enregistrés.

Log : affiche la taille et les dernières entrées du journal. Cliquez sur Clear log pour le vider.

Remove data on uninstall : lorsqu'elle est activée, la désinstallation du module supprime tous les réglages du module, le transporteur et les services FedEx enregistrés des commandes. Lorsqu'elle est désactivée, tout est conservé pour une nouvelle installation.

Fonctionnement au moment du paiement

À l'étape d'expédition, PrestaShop demande au module le prix FedEx. 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 pays autorisés (avec Ignore shipping zones), 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 à FedEx.

Sinon, le module obtient un jeton OAuth et envoie à la Rate API de FedEx l'adresse d'expédition, l'adresse de livraison, le poids du panier (en kg, ou en lb pour les boutiques qui utilisent lb ou oz), la taille du carton si elle est définie, et votre devise par défaut comme devise préférée. Pour les pays qui exigent un code postal, la requête n'est envoyée qu'après que le client l'a saisi. Pour les envois internationaux, la valeur en douane du panier est transmise. Les codes d'état ne sont envoyés que pour les États-Unis et le Canada.

FedEx renvoie les services disponibles. Pour chaque service, le module retient le tarif de compte ou le tarif public que vous avez choisi, privilégie un tarif dans votre devise par défaut, convertit un tarif dans la devise du compte FedEx avec votre taux de change, et écarte les tarifs qu'il ne peut pas convertir. Le service le moins cher détermine le prix, et le prix est affiché dans la devise du panier du client.

Le jeton est mis en cache par environnement et par clé, et il est demandé à nouveau automatiquement lorsque FedEx le rejette. Les tarifs sont mis en cache pendant 1 heure. Une demande de tarif échouée est mémorisée pendant 10 minutes, et une demande de jeton échouée pendant 5 minutes, afin qu'une panne ne ralentisse pas chaque mise à jour du paiement. Le délai d'attente de l'API est de 15 secondes. Si FedEx ne répond pas, 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 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 ne crée pas d'envois FedEx, n'imprime pas d'étiquettes, ne réserve pas d'enlèvements, ne suit pas les colis et ne permet pas au client de choisir un point FedEx. Il affiche une seule option (le service le moins cher), et non plusieurs, et il n'y a pas de mise en carton : le panier est calculé comme un seul colis.

Commandes

Sur la page de commande du back-office, les commandes avec le transporteur FedEx affichent un bloc FedEx shipping. Il indique le FedEx service du tarif (pour les tarifs en temps réel), la Price source (FedEx live rate, Fixed price (no live rate) ou Free shipping threshold) et le Calculated price (excl. tax) dans votre devise par défaut. Les valeurs sont figées au moment où la commande est passée : les modifications ultérieures des réglages ne les changent pas.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox FedEx est le premier bloc de Modules > Module Manager > VibeFox FedEx > 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-fedex 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 FedEx 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

FedEx n'apparaît pas au moment du 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 son groupe (ou activez Ignore shipping zones et vérifiez Countries). Consultez les avertissements en haut de la page du module, les limites de poids et Minimum subtotal. Sans tarif en temps réel, le transporteur a besoin d'un prix par pays, d'une ligne * ou d'un Fallback cost. Par ailleurs, les produits peuvent être limités à certains transporteurs sur la fiche 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. Les clés erronées, le mauvais environnement (clés de test avec Sandbox désactivé, ou clés de production avec celui-ci activé), un code postal de livraison manquant et les codes d'erreur FedEx y sont enregistrés.

Ma boutique n'est pas en USD : FedEx est invité à établir le tarif dans la devise par défaut de votre boutique. Si votre compte ne renvoie que sa propre devise, renseignez FedEx account currency et Exchange rate. Sans taux de change, ces tarifs sont ignorés et le prix fixe est utilisé, de sorte qu'un montant en USD n'est jamais affiché en euros.

« Per item » multiplie-t-il le tarif FedEx ? Non. Per item ne s'applique qu'aux prix fixes.

Les tarifs semblent obsolètes après une modification : enregistrer la page du module vide le cache. Vous pouvez aussi cliquer sur Clear cached FedEx token and rates.

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

Seuls certains services doivent être proposés : les développeurs peuvent restreindre les services avec le hook actionVfdFdxAllowedServices. Les hooks actionVfdFdxRateRequest et actionVfdFdxApiBaseUrl modifient la requête de tarif et l'adresse de l'API.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox FedEx et choisissez Uninstall. La clé de licence et le statut de la licence sont toujours supprimés. Les jetons et tarifs mis 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, le journal et les services FedEx enregistrés des commandes sont supprimés. S'il est désactivé, le transporteur est seulement désactivé et tous les réglages sont conservés. Réinstaller le module (ou utiliser Reset) rend au transporteur enregistré le statut qu'il avait avant la désinstallation.

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