VibeFox UPS 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 sur des versions plus anciennes de PHP ou sans cURL.

Application du UPS Developer Portal (uniquement pour les tarifs en temps réel) : connectez-vous au 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. Le module utilise OAuth 2.0. Aucune Access Key, aucun nom d'utilisateur ni mot de passe n'est nécessaire. Pour les tarifs négociés, il vous faut aussi 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

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 plus tard VibeFox UPS 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. Saisissez le Client ID et le Client Secret, votre numéro de compte UPS (pour les tarifs négociés) et l'adresse Ship from : le code postal et, pour les États-Unis et le Canada, le code d'état à 2 lettres.

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

6. Vous pouvez éventuellement saisir des prix fixes en secours, puis cliquer sur Save.

À l'installation, le module crée le transporteur UPS avec le texte de délai de livraison UPS 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 provient toujours du module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox UPS > 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 le jeton UPS et les tarifs en cache. Vous pouvez aussi cliquer sur Clear cached UPS token and rates dans la section UPS API.

Les avertissements affichés au-dessus des réglages vous indiquent lorsque seul l'un des deux champs Client ID et Client Secret est renseigné, qu'il n'y a ni identifiants ni prix fixes (le transporteur n'est alors jamais affiché), que le code postal ou l'état d'expédition est manquant, 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 dimensions de la boutique n'est pas reconnue par le module. Les valeurs numériques non valides, une taille de carton incorrecte et un Min weight supérieur à Max weight sont signalés à l'enregistrement, et l'ancienne valeur est conservée.

Général

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

Name : le nom du transporteur affiché au client lors du paiement. Par défaut : UPS. Obligatoire, 64 caractères maximum.

Tax status : la règle de taxe du transporteur, ou None. Les tarifs UPS sont calculés hors taxes. Avec une règle de taxe, la boutique ajoute par-dessus sa taxe de livraison.

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 obtenir des tarifs réels. Par défaut : off.

Client ID : le Client ID de votre application dans le 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 publics.

Rates : les prix UPS utilisés.

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

Residential delivery : calcule les adresses des clients comme résidentielles, avec la surcharge résidentielle d'UPS. Désactivez-le si vous expédiez surtout à des entreprises. Par défaut : on.

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

UPS account currency : UPS calcule 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 ce taux, ces tarifs ne sont pas utilisés et les prix fixes s'appliquent. Les taux de change ne sont pas mis à jour automatiquement.

Adresse d'expédition (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.

City : la ville depuis laquelle vous expédiez.

ZIP / postal code : le code postal depuis lequel vous expédiez. UPS en a besoin pour calculer les tarifs.

Prix fixes (utilisés lorsqu'aucun identifiant d'API n'est saisi et en secours lorsque UPS ne renvoie aucun tarif ; laissez les deux champs vides pour masquer le transporteur 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. Le pays * s'applique à tous les autres pays. Une colonne de poids (XS jusqu'à 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL au-delà de 5 kg) remplace Price pour ce poids. Les cellules vides utilisent Price. 0 signifie livraison gratuite. Les lignes sans aucun prix sont supprimées à l'enregistrement, et les valeurs qui ne sont pas des nombres sont refusées avec un message.

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

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

Conditions

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

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

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

Max weight : le transporteur est masqué au-delà de ce poids de panier en kg. Par défaut : 70, la limite UPS par colis (70 kg / 150 lbs). 0 signifie aucune limite, vide signifie 70. Min weight ne peut pas être supérieur à Max weight.

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

Disponibilité sans zones de livraison

Normalement, le transporteur est proposé dans les zones qui lui sont affectées dans Shipping > Carriers.

Ignore shipping zones : propose le transporteur pour les pays indiqués ci-dessous, quelle que soit la zone correspondante. À l'enregistrement, le transporteur est ajouté à toutes les zones, y compris celles créées ultérieurement. Le désactiver supprime de nouveau ces zones.

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

Avancé

Debug log : enregistre les requêtes API et le calcul des tarifs dans logs/vfd_upsx_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, même lorsque cette option est désactivée. Les identifiants, 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 les réglages, le transporteur, les jetons et tarifs en cache, le journal et les services UPS enregistrés avec les commandes. Les commandes elles-mêmes sont conservées. Lorsqu'elle est désactivée, tout est conservé pour une réinstallation.

Fonctionnement au moment du paiement

À l'étape de livraison, PrestaShop demande au module le prix UPS. 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 conditions : les pays de 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 à UPS.

Le module obtient un jeton OAuth auprès d'UPS et le conserve jusqu'à son expiration. Un jeton rejeté par UPS est renouvelé automatiquement. Il demande ensuite à l'API Rating d'UPS tous les services, de votre adresse d'expédition jusqu'à l'adresse du client, pour le panier considéré comme un seul colis. Pour les pays qui utilisent des codes postaux, la requête attend que le client ait saisi le sien. Pour les envois depuis les États-Unis vers le Canada ou Porto Rico, la valeur de la marchandise 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, puis affiché dans la devise du panier du client. UPS Access Point Economy n'est pas proposé, car le module ne collecte aucune adresse de point d'accès.

Chaque devis 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 incorrects, aucun service, autre devise sans taux de change), le prix provient de Country prices, puis de Fallback cost. Si aucun des deux ne s'applique, le transporteur est masqué. Le client ne voit jamais les messages d'erreur d'UPS.

Si vous modifiez le transporteur dans Shipping > Carriers alors qu'il a déjà des commandes, PrestaShop l'enregistre comme une nouvelle version du transporteur. Le module suit automatiquement la nouvelle version.

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

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 du back-office affiche un bloc UPS avec le UPS service, par exemple UPS Ground, et le Live rate (excl. tax). Les modifications ultérieures du panier dans le back-office ne le changent pas. Les commandes à prix fixe ou en livraison gratuite n'ont pas ce bloc.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox UPS est le premier bloc de Modules > Module Manager > VibeFox UPS > Configure, au-dessus des réglages. Saisissez la clé dans License key puis 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-ups 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 : le domaine de la boutique principale, y compris dans une configuration multiboutique. Retirer la clé de la boutique ne libère pas l'emplacement de domaine. Libérez cet emplacement dans votre compte vibefox.net.

Sans clé active, le transporteur UPS 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 : le transporteur est donc masqué pour vous aussi. Vous pouvez configurer le module avant d'acheter une clé, mais non le tester au moment du 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 suivant 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

UPS n'apparaît pas au moment du paiement : vérifiez que la licence est active et que Enable UPS shipping est activé. Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone du pays du client et le groupe de clients, ou activez Ignore shipping zones et vérifiez Countries. Contrôlez les limites de poids et le Minimum subtotal. Sans identifiants UPS valides, le transporteur a besoin d'un prix fixe (Country prices ou Fallback cost). Par ailleurs, les produits peuvent être limités à certains transporteurs depuis la page produit.

Les tarifs en temps réel n'apparaissent pas : consultez les avertissements en haut de la page Configure. Activez Debug log, rechargez le paiement et regardez le champ Log sur la page du module. Il affiche les erreurs OAuth (vérifiez le Client ID, le Client Secret et Test mode), les messages d'erreur d'UPS et les problèmes de devise.

Le tarif est en USD mais la boutique ne l'est pas : UPS renvoie les tarifs dans la devise du compte expéditeur. Renseignez UPS account currency et 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, ou choisissez les unités attendues par UPS pour votre pays d'expédition.

La page signale que l'unité de poids ou de dimensions de la boutique n'est pas reconnue : les poids sont alors lus en kg et la taille du carton en cm. Définissez une unité standard (kg, g, lb ou oz ; cm, mm, m ou in) dans International > Localization, section Local units.

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page du module ou sur Clear cached UPS token and rates.

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

Pour les développeurs : les hooks actionVfdUpsxAllowedServices et actionVfdUpsxExcludedServices limitent les services UPS pouvant être affichés. actionVfdUpsxRateRequest modifie la requête de tarif, actionVfdUpsxApiBaseUrl l'adresse de l'API et actionVfdUpsxCurrencyCodes fait correspondre les codes de devise renvoyés par UPS.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox UPS et choisissez Uninstall. La clé de licence et le statut de la licence sont toujours supprimés. Le jeton UPS et les tarifs 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 UPS enregistrés avec les commandes sont supprimés. S'il est désactivé, le transporteur est seulement désactivé et les réglages sont conservés. Réinstaller le module, ou effectuer une réinitialisation, rend au transporteur le statut qu'il avait auparavant.

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