VibeFox EasyPost for OpenCart — Aide

Prérequis

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

PHP : 8.0 ou ultérieur avec cURL.

Compte EasyPost (pour les tarifs en temps réel uniquement) : créez un compte sur le site web d'EasyPost, connectez vos comptes transporteurs (USPS, UPS, FedEx et d'autres) dans le tableau de bord EasyPost et copiez la clé 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 des tarifs de repli, vous n'avez pas besoin de compte EasyPost.

Produits : les produits ont besoin d'un poids et, de préférence, de dimensions.

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 contenant les paquets pour les deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 vfd_easypost-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_easypost.ocmod.zip. N'installez que le paquet de 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_easypost-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 du paquet dans le dossier racine de votre boutique.

2. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox EasyPost et cliquez sur Install (le bouton vert +).

3. Cliquez sur Edit (le bouton crayon) pour ouvrir la page de réglages.

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. Collez votre clé API EasyPost et remplissez l'adresse Ship from. Le code postal est obligatoire pour les tarifs en temps réel.

6. 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 repli (voir Configuration). Activez Enable EasyPost shipping et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_easypost.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 tire le code de l'extension du 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 lui.

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

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

Après l'installation, la méthode reste désactivée tant que vous n'activez pas Enable EasyPost shipping et n'enregistrez pas. Si vous réinstallez l'extension après une désinstallation, les réglages conservés sont à nouveau utilisés.

Configuration

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

En haut de la page, l'extension affiche des avertissements lorsque les tarifs en temps réel ne peuvent pas être utilisés : aucune clé API (avec ou sans tarifs de repli), aucun code postal ou pays d'expédition, ou une devise par défaut autre que l'USD sans taux de change. Une note apparaît aussi lorsqu'une clé API de test est définie, et un avertissement lorsque l'unité de poids ou de longueur de votre boutique (System > Settings > Option) n'est pas connue de l'extension (kg, g, lb, oz ; cm, mm, m, in).

À l'enregistrement, un nom de plus de 64 caractères, un Sort order qui n'est pas un nombre entier, ou une classe de taxe ou une zone géographique inconnue empêchent l'enregistrement, et rien n'est alors enregistré. Une valeur qui n'est pas un nombre (ou qui est négative) n'est pas enregistrée : un avertissement signale le champ et l'ancienne valeur est conservée, tandis que les autres réglages sont enregistrés. Il en va de même lorsque le USD exchange rate vaut 0, ou lorsque le Minimum weight est supérieur au Maximum weight.

Général

Enable EasyPost shipping : propose la méthode au paiement. C'est l'état de l'extension dans Extensions > Extensions > Shipping. Par défaut : désactivé.

Name : le nom du mode de livraison affiché au client au paiement, 64 caractères au maximum. Par défaut : EasyPost Shipping. Si le nom est vide, le nom par défaut est utilisé. Un nom contenant les caractères < > ; = # { } est remplacé par le nom par défaut, avec un avertissement.

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

Compte EasyPost

API key : votre clé API EasyPost, depuis EasyPost Dashboard > Account Settings > API Keys. Une clé de production (commence par EZAK) renvoie de vrais tarifs. Une clé de test (commence par EZTK) renvoie des tarifs de test EasyPost ; ne l'utilisez que pour des essais. Après l'enregistrement, le champ reste vide et affiche la clé enregistrée masquée, par exemple Saved key: EZAK******abcd. Leave the field empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier. Sans clé, seuls les tarifs de repli sont utilisés.

Remove the saved API key : activez-le et cliquez sur Save pour supprimer la clé enregistrée.

Allowed carriers / services : facultatif, séparé 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 n'importe quel transporteur.

Adresse d'expédition

L'adresse depuis laquelle vos colis sont expédiés. Si le Country est le pays de votre boutique, le champ vide Sender name / company est repris du nom de la boutique, et le champ vide State de la région de votre boutique (System > Settings). OpenCart n'a pas de code postal pour la boutique, le code postal doit donc être saisi ici.

Sender name / company : le nom de l'expéditeur ou de l'entreprise. Vide signifie le nom de la boutique (uniquement dans le même pays).

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

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

State : le code d'État à deux lettres, par exemple CA ou NY.

ZIP code : le code ZIP ou postal d'expédition, par exemple 94105. 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.

Les poids sont convertis de l'unité de poids de votre boutique en onces (1 oz au minimum), et les dimensions de l'unité de longueur de votre boutique 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 la devise par défaut de votre boutique, par exemple 0.92. Sans lui, les tarifs en temps réel ne sont pas utilisés, seuls les tarifs de repli le sont. Il n'est pas nécessaire lorsque la devise par défaut est l'USD. Les boutiques en USD et en CAD demandent à EasyPost de coter dans leur propre devise. Le point et la virgule sont tous deux acceptés comme séparateur décimal.

Tax class : la classe de taxe appliquée à la livraison, ou No tax. Les tarifs EasyPost ne comprennent pas la taxe de vente.

Tarifs de repli

Utilisés lorsqu'aucun tarif en temps réel n'est disponible : pas de clé API, EasyPost est injoignable, la clé est refusée, ou aucun transporteur n'a de tarif pour l'adresse. Les prix sont dans la devise par défaut de votre boutique, hors taxes. Laissez les deux champs vides pour masquer la méthode 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 dans un autre format sont ignorées et listées dans un avertissement lors de l'enregistrement.

Other countries : le prix pour les pays absents de la liste ci-dessus. Laissez vide pour masquer la méthode pour eux.

Conditions

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

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

Minimum weight : masque la méthode 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 (par défaut).

Maximum weight : masque la méthode lorsque le panier pèse plus, dans l'unité de poids de votre boutique. 0 signifie aucune limite (par défaut).

Disponibilité

En règle générale, la zone géographique détermine où la méthode est proposée. Il est également possible de la proposer par pays, indépendamment de la zone géographique.

Geo zone : propose la méthode uniquement pour les adresses de cette zone géographique. All zones (par défaut) signifie aucune limite. Les zones géographiques se gèrent dans System > Localisation > Geo Zones. Non utilisé avec Ignore shipping zones.

Ignore shipping zones : propose la méthode pour les pays indiqués ci-dessous, qu'ils fassent partie de la zone géographique ou non.

Countries : les pays de destination pour ce mode. Laissez vide pour utiliser tous les pays activés de votre boutique. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.

Avancé

Debug log : écrit les requêtes EasyPost dans storage/logs/vfd_ep.log.php (sur OpenCart 4 system/storage/logs/vfd_ep.log.php). Le fichier ne peut pas être lu depuis le web. Lorsqu'il atteint 5 Mo, il est déplacé vers vfd_ep.old.log.php et un nouveau journal commence. Les erreurs et avertissements de l'API sont toujours enregistrés, même lorsque cette option est désactivée. La clé API et les adresses des clients ne sont jamais enregistrées.

Log : affiche la taille et les 100 dernières lignes 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 ses réglages et le journal. Les données EasyPost des commandes passées sont conservées. Désactiver la méthode ne supprime jamais les réglages.

Import / Export

Export : cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. La clé API 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é API enregistrée n'est pas modifiée.

Fonctionnement au paiement

Lorsqu'OpenCart affiche les modes de livraison, il demande à l'extension le prix d'EasyPost. Si une Geo zone est définie (et que Ignore shipping zones est désactivé) et que l'adresse se trouve hors de cette zone, la méthode n'est pas proposée. Seuls les produits dont Requires Shipping est réglé sur Yes comptent : les autres produits n'ajoutent pas de poids et ne sont pas inclus dans le sous-total. L'extension vérifie d'abord les conditions : pays de destination (avec Ignore shipping zones), poids du panier et sous-total minimal. Le sous-total est le prix des produits à expédier, 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. Si la livraison gratuite s'applique, le prix est de 0 et aucune requête n'est envoyée à EasyPost.

Sinon, l'extension envoie à EasyPost l'adresse d'expédition, l'adresse de livraison et le colis, et reçoit les tarifs de tous vos comptes transporteurs. Elle retient le tarif autorisé le moins cher, le convertit dans la devise par défaut de votre boutique et l'affiche dans la devise du client avec la taxe de la Tax class choisie. Pour les pays marqués Postcode Required dans System > Localisation > Countries, la requête n'est envoyée que si l'adresse de livraison comporte un code postal. Dans les données standard d'OpenCart, cette option est désactivée pour les États-Unis ; une adresse américaine sans code ZIP est donc aussi envoyée. EasyPost renvoie alors une erreur, et le tarif de repli est utilisé.

Chaque réponse est mise en cache pendant 1 heure pour la même adresse et le même colis. Une adresse sans tarif exploitable est mémorisée pendant 10 minutes. Après un délai d'attente, 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 repli est utilisé, ou la méthode est masquée s'il n'y a pas de tarif de repli. La raison est écrite dans le journal.

L'extension ne calcule que des tarifs. Elle 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 ni assurance ni options de signature. Elle affiche une seule option (le tarif autorisé le moins cher), et non une liste de services. Il n'y a pas d'optimisation de l'emballage au-delà du rangement des articles dans un seul colis, ni de majoration du tarif ou de frais de gestion.

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

Commandes

Lorsqu'une commande avec la méthode EasyPost est passée, le tarif affiché au paiement est conservé avec la commande. La page de commande de l'administration (Sales > Orders) affiche le panneau EasyPost shipping au-dessus de l'historique :

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 : les délais de livraison renvoyés par EasyPost (uniquement en mode un colis par commande, lorsqu'EasyPost les renvoie).

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

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

Le panneau reste affiché même si l'extension est désactivée plus tard. Les modifications ultérieures de la commande dans l'administration ne changent pas ces valeurs. Utilisez-les pour acheter l'étiquette dans votre compte EasyPost. OpenCart crée un enregistrement de commande chaque fois que le paiement atteint l'étape de confirmation ; les tarifs enregistrés de ces commandes non terminées sont supprimés au bout de 30 jours.

Sur OpenCart 4, le paiement conserve une seule commande et la met à jour chaque fois que le client confirme à nouveau. Le tarif enregistré est mis à jour avec elle : c'est le tarif que le client a vu au paiement. Si le client passe à un autre mode de livraison, le panneau n'est plus affiché pour cette commande.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox EasyPost est le premier bloc de la page Extensions > Extensions > Shipping > VibeFox EasyPost > Edit, au-dessus des réglages. Saisissez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, l'état (par exemple la date jusqu'à laquelle la licence est active et votre domaine) et les boutons Check now pour vérifier de nouveau l'état, 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-easypost 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 état connu.

Une clé fonctionne sur un seul domaine : l'adresse de la boutique issue de la configuration d'OpenCart. 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 mode de livraison EasyPost n'est pas affiché aux clients au paiement et aucun tarif n'est calculé. Un utilisateur administrateur connecté à l'administration dans le même navigateur voit toujours la méthode dans la boutique, marquée (unlicensed — visible to admins only), ce qui vous permet de configurer et de 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 la méthode est masquée 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 le support nécessitent un renouvellement. L'état est vérifié à nouveau automatiquement lorsque vous ouvrez le Dashboard ou la page Edit de l'administration : 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 de l'extension supprime toujours la clé de licence et l'état 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é. Vérifiez Geo zone (ou Ignore shipping zones et Countries), les limites de poids et le Minimum subtotal. Sans tarif en temps réel, la méthode a besoin d'un tarif de repli pour le pays ou pour Other countries. Vérifiez que les produits ont Requires Shipping réglé sur Yes.

Les tarifs en temps réel n'apparaissent pas : lisez les avertissements en haut de la page de l'extension, puis activez Debug log, rechargez la page de paiement et consultez le champ Log. Causes fréquentes : pas de clé API ou de code postal d'expédition, une boutique qui n'est pas en USD sans le 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 Allowed carriers / services filtre 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 se sont arrêtés pendant quelques minutes : après un délai d'attente, une clé refusée ou une erreur serveur d'EasyPost, l'extension suspend les requêtes pendant 5 minutes et utilise les tarifs de repli. Vérifiez la clé API et le journal.

La taxe est-elle incluse ? Les tarifs EasyPost ne comprennent pas la taxe de vente. Choisissez la classe de taxe dans Tax class pour ajouter la taxe à la livraison.

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page de l'extension. Cela vide les tarifs EasyPost en cache.

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

Pour les développeurs : d'autres extensions peuvent ajuster le corps de la requête, le tarif retenu et l'URL de base de l'API avec les événements OpenCart vfd_easypost/shipment_request, vfd_easypost/selected_rate et vfd_easypost/api_url.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox EasyPost. La clé de licence et l'état de la licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable EasyPost shipping, Sort order, Tax class et Geo zone. L'extension supprime toujours ses événements et les tarifs en cache. Si Remove data on uninstall est activé, les autres réglages et le journal sont également supprimés. S'il est désactivé, les réglages sont conservés et réutilisés lors d'une nouvelle installation de l'extension. Les données EasyPost des commandes passées ne sont jamais supprimées, et les commandes existantes conservent leur mode de livraison et leur coût.

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

EasyPost est une marque déposée de son propriétaire respectif. Cette extension n'est pas affiliée à EasyPost et n'est pas approuvée par EasyPost.