VibeFox UPS for OpenCart — Aide

Prérequis

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

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

Application dans l'UPS Developer Portal (pour les tarifs en temps réel uniquement) : connectez-vous à l'UPS Developer Portal (developer.ups.com), créez une application avec le produit « Rating », associez votre compte UPS et copiez le Client ID et le Client Secret. L'extension utilise OAuth 2.0. Aucun Access Key, nom d'utilisateur ni mot de passe n'est nécessaire. Pour les tarifs négociés, vous avez aussi besoin de votre numéro de compte UPS à 6 caractères. Sans identifiants, seuls les prix fixes sont utilisés.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un seul domaine.

Installation

Le téléchargement est un seul 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_ups-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_ups.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_ups-oc3-(version).ocmod.zip. L'extension n'ajoute aucune modification OCMOD : vous n'avez donc pas besoin de rafraîchir Extensions > Modifications. Au lieu de l'installateur, vous pouvez 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 UPS et cliquez sur Install (le bouton vert +).

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

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

5. Saisissez le Client ID et le Client Secret, votre numéro de compte UPS (pour les tarifs négociés) et l'adresse d'expédition Ship from : le code postal et, pour les États-Unis et le Canada, le code d'état à 2 lettres.

6. Si la devise de votre compte UPS diffère de la devise par défaut de votre boutique, saisissez la UPS account currency et le Exchange rate.

7. Facultativement, saisissez des prix fixes en secours, activez Enable UPS shipping et cliquez sur Save.

OpenCart 4

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

3. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox UPS, 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 à 7 pour OpenCart 3. La page des réglages et ses champs sont identiques dans les deux versions.

Après l'installation, le mode reste désactivé tant que vous n'avez pas activé Enable UPS shipping et enregistré. Le pays de Ship from commence par le pays de votre boutique. Si vous réinstallez l'extension après une désinstallation, les réglages UPS conservés sont à nouveau utilisés.

Configuration

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

Si le nom, la classe de taxe, l'ordre de tri ou la zone géographique n'est pas valide, rien n'est enregistré et la page indique la raison, par exemple Enter a valid name (64 characters max, without < > ; = # { }). Nothing was saved. Les nombres non valides (par exemple négatifs), une mauvaise dimension de carton, un Min weight (kg) supérieur à Max weight (kg) et les cellules de prix qui ne sont pas des nombres sont signalés à l'enregistrement : ce champ conserve son ancienne valeur et le reste est enregistré. Des avertissements au-dessus des réglages signalent lorsque seul l'un des deux, Client ID ou Client Secret, est renseigné, qu'il n'y a ni identifiants ni prix fixes (le mode n'est alors jamais affiché), que le code postal ou le code d'état de l'expédition manque, que des tarifs de compte sont choisis sans numéro de compte, que le taux de change manque, ou que l'unité de poids ou de longueur de la boutique n'est pas reconnue par l'extension.

Général

Les réglages s'appliquent à toutes les zones géographiques. UPS est proposé comme une seule option de livraison au paiement.

Enable UPS shipping : affiche ou masque UPS au paiement. Par défaut : désactivé.

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

Tax class : la classe de taxe du coût de livraison, ou None (par défaut). Les tarifs UPS sont cotés hors taxes. Avec une classe de taxe, OpenCart ajoute sa taxe de livraison en plus.

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

API UPS (tarifs en temps réel)

Test mode : utilise l'environnement de test d'UPS. Les tarifs de test ne sont pas de vrais prix. Désactivez-le pour les tarifs en temps réel. Par défaut : désactivé.

Client ID : le Client ID de votre application dans l'UPS Developer Portal. Le vider supprime aussi le Client Secret enregistré.

Client Secret : le Client Secret de la même application. Après l'enregistrement, le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier.

UPS account number : votre numéro d'expéditeur UPS à 6 caractères, par exemple A1B2C3. Nécessaire pour les tarifs de compte (négociés), facultatif pour les tarifs publiés.

Rates : les tarifs UPS utilisés.

Measurement units : les unités envoyées à UPS. Les poids et dimensions de la boutique sont convertis.

Residential delivery : cote les adresses des clients comme résidentielles, avec la surtaxe résidentielle d'UPS. 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 votre boutique (affichée dans le nom du champ), par exemple 30x20x15. UPS applique alors le poids volumétrique. Laissez vide pour coter uniquement au poids.

UPS account currency : UPS cote dans la devise du pays du compte expéditeur, par exemple USD pour les États-Unis, CAD pour le Canada ou EUR pour la zone euro. Par défaut : USD.

Exchange rate : nécessaire uniquement lorsque la devise du compte UPS diffère de la devise par défaut de votre boutique. Saisissez 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 et les prix fixes s'appliquent. Les taux de change ne sont pas mis à jour automatiquement.

Cache : les jetons UPS sont mis en cache jusqu'à leur expiration (au plus la durée de vie du cache d'OpenCart), les tarifs pendant 1 heure, les requêtes en échec pendant 5 à 10 minutes. Cliquez sur Clear cached UPS token and rates pour vider le cache immédiatement.

Ship from (l'adresse où UPS vient chercher les colis ou où vous les déposez ; utilisée pour les tarifs en temps réel)

Country : le pays depuis lequel vous expédiez. Par défaut, c'est le pays de votre boutique.

State / province code : le code à 2 lettres, obligatoire pour les États-Unis et le Canada, par exemple NY, CA ou ON. Il n'est envoyé à UPS que pour ces deux pays.

City : la ville depuis laquelle vous expédiez.

ZIP / postal code : le code postal depuis lequel vous expédiez. UPS en a besoin pour coter les tarifs. OpenCart n'a pas de code postal de boutique : saisissez-le ici.

Prix fixes (utilisés lorsqu'aucun identifiant d'API n'est saisi, et en secours lorsque UPS ne renvoie aucun tarif ; laissez les deux vides pour masquer le mode dans ce cas)

Country prices : prix dans la devise par défaut de votre boutique, hors taxes, par pays de destination. Cliquez sur Add country pour ajouter une ligne et sur le bouton de suppression pour en retirer une. * Default (all other countries) s'applique à tout autre pays. Une colonne de poids (XS jusqu'à 1 kg, S de 1 à 2 kg, M de 2 à 3 kg, L de 3 à 5 kg, XL au-delà de 5 kg) remplace Price pour ce poids de panier. Les cellules vides utilisent Price. 0 signifie livraison gratuite. Une ligne de pays sans valeur pour le poids passe à la ligne *. Les lignes sans aucun prix ne sont pas enregistrées.

Fallback cost : un prix fixe dans la devise par défaut de votre boutique, lorsqu'aucun prix par pays ne correspond. Laissez vide pour masquer le mode dans ce cas.

Fixed price is : Per order (par défaut) facture le prix une seule fois, selon le poids de tout le panier. Per item (each item priced by its own weight x quantity) tarife chaque produit selon son propre poids (le poids par défaut s'il n'en a pas) et le multiplie par sa quantité. Les tarifs UPS en temps réel sont toujours cotés selon le poids de tout le panier.

Conditions

Free shipping from : le sous-total du panier (produits nécessitant une livraison, après le coupon, avant taxes) à partir duquel ce mode est gratuit. Aucune requête n'est envoyée à UPS dans ce cas. Laissez vide pour ne jamais proposer la livraison gratuite.

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

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

Max weight (kg) : le mode est masqué au-dessus de ce poids de panier. Par défaut : 70, la limite UPS par colis (70 kg / 150 lbs). 0 signifie aucune limite, vide signifie 70.

Default product weight (kg) : le poids utilisé pour les produits sans poids, dans les tarifs UPS, les colonnes de poids et les limites de poids. Par défaut : 0.5. Vide signifie aussi 0.5.

Geo zone : proposez UPS 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.

Disponibilité sans zones de livraison

Ignore shipping zones : ne vérifie pas la zone géographique. Le mode est proposé pour les pays indiqués ci-dessous.

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

Avancé

Debug log : consigne les requêtes à l'API et le calcul des tarifs dans storage/logs/vfd_upsx_debug.log.php (sur OpenCart 4 system/storage/logs/vfd_upsx_debug.log.php). Le fichier ne peut pas être lu depuis le web. Les erreurs d'API sont toujours journalisées, même lorsque cette option est désactivée. Les identifiants, jetons et adresses des clients ne sont jamais journalisés. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_upsx_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 UPS, les jetons et tarifs en cache, et le journal. Les services UPS enregistrés avec les commandes sont toujours conservés. Lorsqu'elle est désactivée, tout est conservé pour une réinstallation.

Import / Export

Export : cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. Le Client Secret n'est pas exporté.

Import : collez le JSON précédemment exporté 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. Le Client Secret enregistré est conservé.

Fonctionnement au paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le prix UPS. Si une Geo zone est définie et que l'adresse est en dehors, UPS n'est pas proposé (avec Ignore shipping zones, c'est la liste des pays qui décide). Seuls les produits dont Requires Shipping est réglé sur Yes sont pris en compte : les autres n'ajoutent pas de poids et ne sont pas inclus dans le sous-total. Le sous-total est le 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 conditions : 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 à UPS.

L'extension obtient auprès d'UPS un jeton OAuth et le conserve jusqu'à son expiration. Un jeton rejeté par UPS est renouvelé automatiquement et la requête est répétée une fois. Elle demande ensuite à l'API UPS Rating tous les services depuis votre adresse d'expédition jusqu'à l'adresse du client, pour le panier comme un seul colis. Pour les pays où OpenCart exige un code postal, la requête attend que le client en ait saisi un. Pour les envois depuis les États-Unis vers le Canada ou Porto Rico, la valeur des marchandises est transmise, comme l'exige UPS.

Le client voit une seule option avec le service UPS le moins cher. Le prix est calculé dans la devise par défaut de votre boutique, arrondi à ses décimales, et affiché dans la devise du client avec la taxe de la Tax class sélectionnée. UPS Access Point Economy n'est pas proposé, car l'extension ne collecte pas d'adresse de point d'accès.

Chaque tarif est mis en cache pendant 1 heure. Une requête en échec est mémorisée pendant 10 minutes, et une requête de jeton en échec pendant 5 minutes, afin qu'une panne ne ralentisse pas chaque mise à jour du paiement. Le délai d'attente HTTP est de 15 secondes.

Si UPS ne renvoie aucun tarif (API indisponible, identifiants erronés, aucun service, autre devise sans taux de change), le prix provient de Country prices, puis de Fallback cost. Si aucun ne s'applique, le mode est masqué. Le client ne voit jamais les messages d'erreur d'UPS. La raison est consignée dans le journal de débogage.

L'extension calcule uniquement des tarifs. Elle ne propose pas la sélection d'un point UPS Access Point, ne crée pas d'étiquettes ni d'envois UPS, ne réserve pas d'enlèvements et ne suit pas les colis. Elle affiche une seule option, et non plusieurs services UPS. Il n'y a pas de calcul de remplissage de cartons : le panier est coté comme un seul colis. Les taux de change ne sont pas automatiques.

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

Commandes

Lorsqu'une commande est passée avec un tarif UPS en temps réel, le service UPS est enregistré avec la commande. La page de commande dans Sales > Orders affiche un panneau UPS avec le UPS service, par exemple UPS Ground, et le Live rate (excl. tax). Ces valeurs sont enregistrées au moment où la commande est passée. Les commandes avec prix fixe ou livraison gratuite n'ont pas ce panneau.

OpenCart 4 conserve une seule commande pour le paiement et la met à jour chaque fois que le client confirme à nouveau. Le service UPS enregistré est mis à jour avec elle. Si le client change de mode de livraison, ou si le prix devient un prix fixe ou une livraison gratuite, le service enregistré est retiré de la commande. Sur OpenCart 4, le panneau UPS s'affiche au-dessus de la section History.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox UPS est le premier bloc de Extensions > Extensions > Shipping > VibeFox UPS > 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 à 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-ups 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. Vous gérez vos licences et vos domaines dans votre compte vibefox.net.

Sans clé active, UPS n'est pas affiché aux clients au paiement et aucun tarif n'est calculé. Un administrateur connecté à l'administration dans le même navigateur voit toujours le mode 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 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 le support nécessitent un renouvellement. L'état est vérifié automatiquement à nouveau 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

UPS does not appear at checkout : vérifiez que la licence est active et que Enable UPS shipping est activé. Contrôlez Geo zone, ou activez Ignore shipping zones et contrôlez Countries. Vérifiez les limites de poids et Minimum subtotal. Sans identifiants UPS valides, le mode a besoin d'un prix fixe (Country prices ou Fallback cost). Vérifiez que les produits ont Requires Shipping réglé sur Yes.

Live rates do not appear : consultez les avertissements en haut de la page Edit. Activez Debug log, rechargez le paiement et consultez le champ Log de la page de l'extension. Il affiche les erreurs OAuth (vérifiez le Client ID, le Client Secret et le Test mode), les messages d'erreur d'UPS et les problèmes de devise.

The rate is in USD but the store is not : UPS renvoie les tarifs dans la devise du compte expéditeur. Renseignez UPS account currency et le Exchange rate. Sans taux de change, ces tarifs sont ignorés et le prix fixe est utilisé.

« This measurement system is not valid for the selected country » : laissez Measurement units sur Automatic (by ship-from country), ou choisissez les unités qu'UPS attend pour votre pays d'expédition.

The page warns about the weight or length unit : sans classe de poids en kg, les unités de poids inconnues sont lues comme des kg. Ajoutez une classe de poids en kg dans System > Localisation > Weight Classes. Une unité de longueur inconnue de la boutique fait lire Box size en cm. Utilisez cm, mm, m ou in comme classe de longueur de la boutique (System > Settings, onglet Option).

Rates look outdated after a change : cliquez sur Save sur la page de l'extension ou sur Clear cached UPS token and rates.

The page says "Warning: You do not have permission to modify VibeFox UPS!" : 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_ups (OpenCart 3) ou extension/vfd_ups/shipping/vfd_ups (OpenCart 4) dans System > Users > User Groups.

For developers : l'extension déclenche des événements OpenCart que d'autres extensions peuvent écouter : vfd_ups/allowed_services et vfd_ups/excluded_services restreignent les services UPS pouvant être affichés, vfd_ups/rate_request modifie la requête de tarif, vfd_ups/api_base_url l'adresse de l'API et vfd_ups/currency_codes associe les codes de devise renvoyés par UPS.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox UPS. OpenCart réinitialise toujours Enable UPS shipping, Sort order, Tax class et Geo zone. Le jeton et les tarifs UPS en cache sont toujours supprimés. Si Remove data on uninstall est activée, les réglages UPS et le journal de débogage sont aussi supprimés. Si elle est désactivée, les autres réglages sont conservés et réutilisés lors d'une nouvelle installation de l'extension. Les services UPS enregistrés avec les commandes ne sont jamais supprimés, et les commandes existantes conservent leur mode de livraison et leur coût.

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

UPS est une marque déposée de son propriétaire. Cette extension n'est ni affiliée à UPS, ni approuvée par UPS.