VibeFox FedEx for OpenCart — Aide

Prérequis

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

PHP : 8.0 ou ultérieur avec l'extension cURL.

Compte FedEx et clés API (uniquement pour les tarifs en temps réel) : dans le portail développeurs FedEx (developer.fedex.com), créez un projet avec l'API de tarifs, liez votre compte d'expédition FedEx et copiez la clé API (API Key) et la clé secrète (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é, les clés de production uniquement avec celui-ci désactivé. L'extension utilise l'API REST FedEx avec OAuth 2.0 ; elle n'a pas besoin de numéro de compteur ni de mot de passe de services web. Si vous n'utilisez que des tarifs 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

Le téléchargement est un fichier zip unique contenant les paquets des deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 vfd_fedex-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_fedex.ocmod.zip. N'installez que le paquet correspondant à 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_fedex-oc3-(version).ocmod.zip. L'extension n'ajoute aucune modification OCMOD, vous n'avez donc pas besoin d'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 FedEx et cliquez sur Install (le bouton vert +).

3. Cliquez sur Edit (le bouton en forme de crayon) pour ouvrir la page de configuration.

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 (API Key), la clé secrète (Secret Key), le numéro de compte FedEx à 9 chiffres et l'adresse Ship from (code postal et, pour les États-Unis et le Canada, l'état sur 2 lettres). Désactivez Sandbox lorsque vous utilisez des clés de production. Vous pouvez éventuellement saisir des tarifs fixes en secours. Activez Enable/Disable et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_fedex.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é de celui-ci.

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

4. Saisissez la clé de licence et les réglages comme aux étapes 4 et 5 pour OpenCart 3. La page de configuration et ses champs sont identiques dans les deux versions.

Après l'installation, le mode de livraison reste désactivé tant que vous n'activez pas Enable/Disable et n'enregistrez pas. Si vous réinstallez l'extension après l'avoir désinstallée, les réglages FedEx conservés sont à nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox FedEx > Edit. Les sections sont listées à gauche. Un bouton Save en bas enregistre toute la page sans la recharger. Chaque enregistrement vide aussi le jeton FedEx et les tarifs en cache. Seuls les administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages.

En haut de la page, l'extension affiche des avertissements : seules certaines des trois informations d'identification de l'API sont renseignées, aucune clé API ni aucun tarif fixe (le mode de livraison n'est alors jamais affiché), aucun code postal d'expédition, aucun état d'expédition pour les États-Unis ou le Canada, une devise de boutique sans taux de change pour des tarifs dans la devise du compte FedEx, une unité de poids que l'extension ne connaît pas en l'absence de classe de poids en kg (ajoutez-en une dans System > Localisation > Weight Classes) ou, avec une taille de carton, une unité de longueur qu'elle ne connaît pas. Les champs numériques acceptent un point ou une virgule décimale. À l'enregistrement, un nombre ou une taille de carton invalide, un taux de change de 0, une devise de compte qui n'est pas un code à 3 lettres, un nom ou un ordre de tri invalide sont signalés et non enregistrés ; le champ conserve sa valeur précédente et les autres champs sont enregistrés (The other settings were saved.). Un poids minimum supérieur au poids maximum est aussi signalé, et les deux poids conservent leurs valeurs précédentes.

Général

Les réglages s'appliquent à toutes les zones géographiques. FedEx est proposé au paiement sous la forme d'une seule option de livraison : le service FedEx le moins cher, ou le tarif fixe lorsque FedEx ne renvoie aucun tarif.

Enable/Disable : active ou désactive la livraison FedEx au paiement. Par défaut : désactivé.

Name : le nom du mode de livraison affiché au client lors du paiement, de 64 caractères au maximum, sans < > ; = # { }. Par défaut : FedEx. Obligatoire.

Tax class : la classe de taxe du coût de livraison, ou No tax (par défaut). Avec une classe de taxe, OpenCart ajoute la taxe au coût de livraison ; on utilise donc le montant FedEx hors taxes. Avec No tax, le montant net FedEx est utilisé tel quel.

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

API FedEx (tarifs en temps réel)

La section renvoie vers le portail développeurs FedEx. Sans clés, les tarifs fixes sont utilisés.

Sandbox : utilise le bac à sable 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 : la clé API (client_id) de votre projet dans le portail développeurs FedEx. La vider supprime aussi la clé secrète enregistrée.

Secret Key : la clé secrète (client_secret) du même projet. Après l'enregistrement, le champ reste vide et affiche Saved — leave empty to keep it. Clearing the API Key removes it too. Ne saisissez une nouvelle valeur que pour la modifier.

FedEx account number : le compte d'expédition FedEx à 9 chiffres lié 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 résidentiel). Désactivez-le si vous expédiez surtout à des entreprises. Par défaut : activé.

Box size (L x W x H) : dimensions facultatives du carton dans l'unité de longueur de la boutique indiquée dans le nom du champ, par exemple 30x20x15. FedEx applique alors le poids volumétrique. Laissez-le 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 interrogé pour établir son devis dans la devise par défaut de la boutique également.

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 d'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, et un montant dans une autre devise n'est jamais affiché comme votre devise.

Cache : le bouton Clear cached FedEx token and rates vide le cache immédiatement. Les jetons FedEx sont mis en cache jusqu'à leur expiration, les tarifs pendant 1 heure et les requêtes échouées pendant 5 à 10 minutes.

Ship from

L'adresse à partir de laquelle FedEx enlève les colis ou à laquelle vous les déposez. Elle sert aux 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 établir les tarifs. OpenCart n'a pas de code postal pour la boutique, saisissez-le donc ici.

Tarifs fixes

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

Country prices : une liste de pays de destination et de prix dans la devise par défaut de votre boutique, hors taxes. Cliquez sur Add row pour ajouter une ligne et sur le bouton × pour en supprimer une. Choisissez * Any other country pour un prix appliqué à chaque pays sans ligne propre. Les lignes sans pays ou prix valide 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 mode de livraison.

Fixed price is : Per order (par défaut) 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 tarifs 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 des produits nécessitant une livraison (après le coupon, avant taxes) à partir duquel ce mode est gratuit. Aucune requête n'est alors envoyée à FedEx. Laissez-le vide pour ne jamais offrir la livraison gratuite.

Minimum subtotal : affiche le mode de livraison uniquement si le même sous-total atteint au moins ce montant. Laissez-le vide pour l'afficher toujours.

Min weight (kg) : le poids minimum du panier pour que le mode de livraison apparaisse. 0 signifie sans limite (par défaut).

Max weight (kg) : le poids maximum du panier. Le mode de livraison est masqué s'il est dépassé. 0 signifie sans limite (par défaut).

Default product weight (kg) : le poids utilisé pour les produits sans poids, pour les tarifs FedEx et pour les limites de poids ci-dessus. Par défaut : 0.5 ; un champ vide signifie aussi 0.5 kg. Les poids des produits sont convertis à partir de la classe de poids de chaque produit.

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

Disponibilité sans zones de livraison

Ignore shipping zones : ne vérifie pas la zone géographique ; propose le mode de livraison pour les pays ci-dessous. Par défaut : désactivé.

Countries : les pays de destination pour ce mode. Laissez-le 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 storage/logs/vfd_fdx_debug.log.php (sur OpenCart 4, system/storage/logs/vfd_fdx_debug.log.php). Le fichier ne peut pas être lu depuis le web. Les erreurs de l'API sont toujours enregistrées, même lorsque le journal est désactivé. Les clés, les jetons, le numéro de compte et les adresses des clients ne sont jamais enregistrés. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_fdx_debug.old.log.php et un nouveau journal est démarré.

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 de l'extension supprime les réglages FedEx, les jetons et tarifs en cache et le journal. Lorsqu'elle est désactivée (par défaut), tout est conservé pour une réinstallation. Les tarifs FedEx des commandes passées sont toujours conservés.

Import / Export

Export : cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. La clé secrète n'est pas exportée.

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

Fonctionnement lors du paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le prix FedEx. Si une Geo zone est définie (et que Ignore shipping zones est désactivé) et que l'adresse se trouve en dehors, FedEx n'est pas proposé. Seuls les produits dont Requires Shipping est défini sur Yes sont pris en compte : les autres produits n'ajoutent pas de poids et ne sont pas inclus dans le sous-total. Le sous-total correspond au prix de ces produits après la remise du coupon et avant taxes ; les cartes cadeaux, les points de fidélité et le crédit boutique ne sont pas pris en compte. L'extension vérifie ensuite 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, si la clé API, la clé secrète et le numéro de compte sont renseignés, l'extension obtient un jeton OAuth et envoie à l'API de tarifs FedEx l'adresse d'expédition, l'adresse de livraison, le poids du panier (en kg, ou en lb pour les boutiques dont la classe de poids est 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 où Postcode Required est activé dans OpenCart, la requête n'est faite qu'après que le client a saisi un code postal. 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, l'extension prend le tarif de compte ou 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'elle ne peut pas convertir. Le service le moins cher est utilisé. Le prix est arrondi aux décimales de votre devise par défaut et affiché au client dans sa devise, avec la taxe de la Tax class sélectionnée.

Le jeton est mis en cache jusqu'à son expiration et redemandé automatiquement lorsque FedEx le rejette. Les devis sont mis en cache pendant 1 heure. Une requête de tarif échouée est retenue pendant 10 minutes et une requête 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 mode de livraison est masqué. La raison est inscrite dans le journal de débogage.

L'extension calcule uniquement les tarifs. Elle ne crée pas d'envois FedEx, n'imprime pas d'étiquettes, ne programme pas d'enlèvements, ne suit pas les colis et ne permet pas aux clients de choisir un point FedEx. Elle affiche une seule option (le service le moins cher), et non plusieurs, et il n'y a pas de remplissage de cartons : le panier est calculé comme un seul colis.

Sur OpenCart 4, le client clique sur Choose dans le bloc des modes de livraison de la page de paiement et choisit FedEx dans la fenêtre Shipping method options. Le mode de livraison fonctionne de la même façon que sur OpenCart 3.

Commandes

Lorsqu'une commande avec FedEx est passée, le tarif affiché au client est enregistré avec la commande. Dans Sales > Orders, la page de commande comporte un panneau FedEx shipping. Il affiche 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 lors de la commande : les modifications ultérieures des réglages ne les changent pas. Sur OpenCart 4, une seule commande est conservée pour le paiement ; elle est mise à jour à chaque fois que le client confirme à nouveau : le tarif FedEx enregistré est mis à jour avec elle, et il est supprimé lorsque le client choisit un autre mode de livraison.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox FedEx est le premier bloc de Extensions > Extensions > Shipping > VibeFox FedEx > Edit, 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. En dessous figurent la ligne Product: opencart-shipping-fedex et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les utilisateurs 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 indiquée dans la configuration d'OpenCart. 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 mode de livraison FedEx n'est pas affiché aux clients lors du paiement et aucun tarif n'est calculé. Un utilisateur administrateur connecté à l'administration dans le même navigateur voit toujours le mode de livraison dans la boutique, marqué (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 le mode de livraison est masqué pour tout le monde. Après avoir ouvert une fois la page Edit, 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 l'assistance 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 suivant 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

FedEx n'apparaît pas lors du paiement : vérifiez que la licence est active et que Enable/Disable est activé. Vérifiez Geo zone, ou Ignore shipping zones et Countries. Vérifiez les avertissements en haut de la page de l'extension, les limites de poids et Minimum subtotal. Sans tarif en temps réel, le mode de livraison a besoin d'un tarif par pays, d'une ligne * Any other country ou d'un Fallback cost. Vérifiez que les produits ont Requires Shipping défini sur Yes.

Les tarifs en temps réel n'apparaissent pas : activez Debug log, rechargez le paiement et consultez le champ Log sur la page de l'extension. 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 consignés.

Ma boutique n'est pas en USD : FedEx est interrogé pour un 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.

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

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

La page affiche « Warning: You do not have permission to modify VibeFox FedEx! » : votre groupe d'utilisateurs administrateurs ne peut que consulter les réglages. Accordez au groupe l'autorisation de modification pour extension/shipping/vfd_fedex (OpenCart 3) ou extension/vfd_fedex/shipping/vfd_fedex (OpenCart 4) dans System > Users > User Groups.

Pour les développeurs : d'autres extensions peuvent modifier l'adresse de l'API, les services FedEx autorisés et la requête de tarif via les événements OpenCart vfd_fedex/api_base_url, vfd_fedex/allowed_services et vfd_fedex/rate_request (enregistrés comme catalog/vfd_fedex/...) ; le réglage vfd_fdx_api_url remplace l'adresse de l'API pour les tests et n'a pas de champ sur la page de configuration.

Désinstallation

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

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

FedEx est une marque de son propriétaire. Cette extension n'est ni affiliée ni approuvée par FedEx.