VibeFox UPS for WooCommerce — Aide

Prérequis

WordPress : 5.8 ou ultérieur.

WooCommerce : 7.0 ou ultérieur, installé et activé. L'extension refuse de s'activer sans lui.

PHP : 8.0 ou ultérieur.

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. L'extension utilise OAuth 2.0. Aucune clé d'accès (Access Key), aucun 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

1. Dans WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier vfd_ups dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox UPS, ou cliquez sur Settings sous le nom de l'extension sur la page des extensions.

4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.

5. 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.

6. Si la devise de votre compte UPS est différente de celle de la boutique, saisissez UPS account currency et Exchange rate.

7. Ajoutez VibeFox UPS à une zone de livraison dans WooCommerce > Settings > Shipping > Shipping zones, ou activez Ignore shipping zones et choisissez les pays.

8. Facultativement, saisissez des prix fixes en secours.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Shipping > VibeFox UPS. Ils s'appliquent à toutes les zones de livraison. Lorsque vous ajoutez la méthode à une zone, la fenêtre de la zone ne comporte qu'un seul champ :

Title (zone) : le nom de cette option au moment du paiement. Laissez-le vide pour utiliser le Name global.

Chaque fois que vous enregistrez les réglages, le jeton UPS et les tarifs en cache sont effacés. 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é, lorsqu'il n'y a ni identifiants ni prix fixes, lorsque le code postal ou l'état d'expédition est manquant, lorsque des tarifs de compte sont choisis sans numéro de compte, ou lorsque le taux de change est absent.

General

Enable/Disable : active ou désactive la méthode dans toutes les zones à la fois.

Name : le nom du mode de livraison affiché au moment du paiement. Par défaut : UPS.

Tax status : Taxable permet à WooCommerce d'ajouter sa taxe sur la livraison, None ne l'ajoute pas. Les tarifs UPS sont donnés hors taxes, la taxe n'est donc pas facturée deux fois.

UPS API (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 le UPS Developer Portal.

Client Secret : le Client Secret de la même application.

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 UPS. Désactivez-la si vous livrez surtout des entreprises. Par défaut : activé.

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

UPS account currency : UPS établit ses tarifs 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 est différente de celle de la boutique. Saisissez le prix de 1 unité de la devise du compte dans la devise de votre boutique, 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 fournit aucun tarif ; laissez les deux vides pour masquer la méthode dans ce cas)

Country prices : prix dans la devise de votre boutique par pays de destination. Cliquez sur + Add country pour ajouter une ligne et sur la croix pour en supprimer une. La ligne * Default s'applique à tout autre 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 de panier. 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 fixe dans la devise de votre boutique lorsqu'aucun prix par pays ne correspond. Laissez-le vide pour masquer la méthode dans ce cas.

Fixed price is : Per order facture le prix une seule fois. Per item (each item priced by its own weight x quantity) tarifie chaque article 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 calculés sur le poids total du panier.

Conditions

Free shipping from : le sous-total du panier à partir duquel cette méthode est gratuite. Le client voit le nom de la méthode suivi de « (Free) » et aucune requête n'est envoyée à UPS. Laissez vide pour ne jamais proposer la livraison gratuite.

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

Min weight (kg) : le poids minimum du panier pour que cette méthode apparaisse. 0 signifie aucune limite.

Max weight (kg) : la méthode est masquée au-delà de ce poids de panier. Par défaut : 70, la limite UPS par colis (70 kg / 150 lbs). 0 signifie aucune limite.

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.

Excluded shipping classes : masque la méthode si le panier contient un produit appartenant à l'une de ces classes d'expédition WooCommerce.

Disponibilité sans zones de livraison

Ignore shipping zones : propose la méthode pour les pays indiqués ci-dessous, même sans l'ajouter à une zone de livraison.

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

Avancé

Debug log : journalise les requêtes API et le calcul des tarifs dans WooCommerce > Status > Logs, source vfd-ups. Les erreurs d'API sont toujours journalisées, même lorsque cette option est désactivée. Les identifiants, les jetons et les adresses des clients ne sont jamais journalisés.

Remove data on uninstall : lorsque l'option est activée, la suppression de l'extension efface tous ses réglages et les méthodes de zone. La désactivation ne supprime jamais les réglages.

Fonctionnement au moment du paiement

Lorsque le client saisit une adresse de livraison, WooCommerce demande un tarif à l'extension. L'extension vérifie d'abord les conditions : poids du panier, sous-total minimum et classes d'expédition exclues. Si la livraison gratuite s'applique, la méthode s'affiche comme gratuite et aucune requête n'est envoyée à UPS.

L'extension obtient un jeton OAuth auprès d'UPS et le conserve jusqu'à son expiration. Un jeton rejeté par UPS est renouvelé automatiquement. Elle interroge ensuite l'API Rating d'UPS pour tous les services, de votre adresse d'expédition à l'adresse du client, pour le panier considéré comme un seul colis. Pour les pays qui utilisent un code postal, la requête attend que le client l'ait saisi. 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, correspondant au service UPS le moins cher, convertie dans la devise de votre boutique. UPS Access Point Economy n'est pas proposé, car l'extension ne collecte pas d'adresse d'Access Point.

Chaque tarif est mis en cache pendant 1 heure. Une requête échouée est retenue 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 HTTP est de 15 secondes. La désactivation de l'extension efface le jeton et les tarifs en cache.

Si UPS ne fournit aucun tarif (API indisponible, identifiants incorrects, aucun service), le prix provient de Country prices, puis de Fallback cost. Si aucun ne s'applique, la méthode est masquée. Le client ne voit jamais les messages d'erreur d'UPS.

La méthode fonctionne sur le paiement classique et sur les blocs Panier et Paiement. Elle est compatible avec WooCommerce High-Performance Order Storage (HPOS).

L'extension ne calcule que les tarifs. Elle ne propose pas de choix d'UPS Access Point, ne crée ni étiquettes d'expédition ni expéditions 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 des colis : le panier est calculé comme un seul colis. Les taux de change ne sont pas automatiques.

Commandes

Pour un tarif en temps réel, la ligne de livraison de la commande enregistre le UPS service, par exemple UPS Ground. Le gestionnaire de la boutique le voit sur l'écran d'administration de la commande.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Shipping > VibeFox UPS. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active, ainsi que votre domaine. Utilisez Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour la retirer de ce site. Le lien Manage licenses and domains in your account ouvre votre compte vibefox.net.

Une clé fonctionne sur un seul domaine. Retirer la clé d'un site ne libère pas son emplacement de domaine. Libérez-le dans votre compte vibefox.net.

Sans clé active, UPS n'est pas affiché aux clients au moment du paiement. Les gestionnaires de boutique connectés le voient toujours, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page des extensions et sur les pages WooCommerce. 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 en arrière-plan.

Dépannage

UPS n'apparaît pas au moment du paiement : vérifiez que la licence est active, que Enable/Disable est activé et que la méthode est ajoutée à la zone du pays du client (ou que Ignore shipping zones est activé et que le pays est autorisé). Vérifiez les limites de poids, le Minimum subtotal et les Excluded shipping classes. Sans identifiants UPS valides, la méthode a besoin d'un prix fixe (Country prices ou Fallback cost).

Les tarifs en temps réel n'apparaissent pas : consultez les avertissements en haut de la page des réglages. Activez le Debug log et ouvrez WooCommerce > Status > Logs, source vfd-ups. Vous y verrez 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.

Le tarif est en USD mais pas la boutique : 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.

Les tarifs semblent obsolètes après une modification : enregistrez la page des réglages ou cliquez sur Clear cached UPS token and rates.

Pour les développeurs : les filtres vfd_upsx_allowed_services et vfd_upsx_excluded_services limitent les services UPS pouvant être affichés. vfd_upsx_rate_request modifie la requête de tarif, vfd_upsx_api_base_url l'adresse de l'API et vfd_upsx_currency_codes associe les codes de devise renvoyés par UPS.

Le bloc de licence affiche une erreur : suivez le message affiché dans le bloc. Par exemple, si la clé est déjà utilisée sur un autre domaine, libérez un emplacement dans votre compte vibefox.net et cliquez sur Check now. Si l'adresse du site a changé, cliquez sur Check now pour activer la clé pour le nouveau domaine. Si le serveur de licences est injoignable, l'extension continue de fonctionner avec le dernier statut connu.

Désinstallation

La désactivation de l'extension conserve les réglages et efface uniquement le jeton et les tarifs en cache. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et le statut de licence de cette extension, ainsi que le jeton et les tarifs en cache, sont toujours supprimés. Les réglages et les méthodes de zone ne sont supprimés que si Remove data on uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les commandes existantes conservent leurs lignes de livraison.

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