VibeFox USPS for PrestaShop — Aide

Prérequis

PrestaShop: 8.0 à 9.x.

PHP: 8.0 ou ultérieur. Le module refuse de s'installer sur les anciennes versions de PHP.

Application dans le USPS Developer Portal (pour les tarifs en temps réel uniquement) : connectez-vous au USPS Developer Portal (developers.usps.com) avec un compte professionnel USPS gratuit, créez une application et copiez son Consumer Key et son Consumer Secret. Le module utilise les API USPS actuelles avec OAuth 2.0. USPS a arrêté l'ancienne API Web Tools (User ID et XML) le 25 janvier 2026 : un User ID Web Tools ne fonctionne donc plus. Sans clés, seuls les prix fixes sont utilisés.

Ship-from ZIP code: les tarifs en temps réel nécessitent le code ZIP à 5 chiffres des États-Unis d'où les colis sont expédié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 USPS dans la liste des modules et cliquez sur Configure.

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

4. Saisissez le Consumer Key et le Consumer Secret, le Ship from ZIP code à 5 chiffres, puis choisissez les services. Si la devise par défaut de votre boutique n'est pas l'USD, saisissez le USD exchange rate. Vous pouvez éventuellement saisir des prix fixes en secours. Cliquez sur Save.

À l'installation, le module crée le transporteur USPS avec le texte de délai de livraison Delivery by USPS. 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 USPS > 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 aussi le jeton USPS et les tarifs en cache.

Une valeur non valide n'est pas enregistrée : la valeur précédente est conservée et un message d'erreur indique le champ, tandis que les autres champs sont enregistrés. Les avertissements en haut de la page vous signalent lorsqu'une seule des clés est renseignée, qu'il n'y a ni clés ni prix fixes (le transporteur n'est alors jamais affiché), que le code ZIP d'expédition manque, qu'aucun service n'est sélectionné, que le taux de change USD manque, que l'environnement de test est activé, que l'unité de poids ou de dimensions de la boutique est inconnue (à définir dans International > Localization, Local units), ou que le transporteur USPS a été supprimé.

Général

Enable USPS 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 : USPS. Obligatoire, 64 caractères maximum.

Tax status: la règle de taxe du transporteur. Les prix USPS n'incluent pas les taxes. Choisissez une règle de taxe pour ajouter la taxe sur les frais de port, ou None si les frais de port ne sont pas taxés.

API USPS (tarifs en temps réel)

Consumer Key: le Consumer Key (client_id) de votre application développeur USPS.

Consumer Secret: le Consumer Secret (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. Vider le Consumer Key supprime aussi le secret enregistré.

Test environment: utilise le USPS Testing Environment for Mailers (apis-tem.usps.com). Uniquement pour les applications qui y ont accès. Laissez-le désactivé pour des tarifs réels (apis.usps.com). Par défaut : désactivé.

Prices: les tarifs USPS utilisés.

Services: les services USPS susceptibles d'être proposés. Le service sélectionné le moins cher, parmi ceux que USPS propose pour le colis, est affiché. Les tarifs Flat Rate, Cubic, Hold for Pickup et Sunday ne sont jamais utilisés. Par défaut : USPS Ground Advantage, Priority Mail et First-Class Package International Service. Si aucun service n'est sélectionné, les tarifs en temps réel ne sont pas utilisés.

USD exchange rate: les tarifs USPS sont en USD. Si la devise par défaut de votre boutique n'est pas l'USD, saisissez le prix de 1 USD dans cette devise, par exemple 0.92. Sans cette valeur, les tarifs en temps réel ne sont pas utilisés et ce sont les prix fixes qui s'appliquent. Inutile si la devise par défaut est l'USD. Doit être supérieur à 0.

Cache: le bouton Clear cached USPS token and rates vide le cache immédiatement. Les tarifs sont mis en cache pendant 1 heure, un tarif en échec pendant 10 minutes. Après un délai d'attente, une erreur serveur, une limite de requêtes ou des clés rejetées, USPS n'est pas sollicité pendant 5 minutes.

Expédition et colis (les tarifs USPS dépendent du code ZIP d'expédition, du poids et de la taille du colis ; le panier est calculé comme un seul colis, et les colis de plus de 70 lb utilisent les prix fixes)

Ship from ZIP code: le code ZIP à 5 chiffres des États-Unis d'où les colis sont expédiés. Un code ZIP+4 est ramené à 5 chiffres. Les autres valeurs sont refusées avec un message.

Box size: dimensions facultatives du carton, dans l'unité de dimensions de votre boutique, par exemple 30x20x15. Laissez vide pour calculer la taille à partir des dimensions des produits : la plus grande longueur, la plus grande largeur et les hauteurs empilées. Si un produit n'a pas de dimensions, un carton de 10 x 8 x 4 pouces est utilisé.

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

Prix fixes (prix dans la devise par défaut de votre boutique, hors taxes ; utilisés lorsqu'aucune clé API n'est saisie et en secours lorsque USPS ne renvoie aucun tarif : API indisponible, clés incorrectes, aucun service ou destination sans code ZIP américain ; laissez les deux champs vides pour masquer le transporteur dans ce cas)

Country prices: prix par pays de destination et par poids du panier. Cliquez sur Add country pour ajouter une ligne et sur l'icône de corbeille pour en supprimer une. Les colonnes sont Price et les tranches de poids XS (jusqu'à 1 kg), S (1–2 kg), M (2–3 kg), L (3–5 kg) et XL (plus de 5 kg). Une tranche vide ou égale à 0 utilise Price. La ligne * Default (any other country) s'applique à tout autre pays. Une ligne de pays sans aucun prix envoie ce pays vers Fallback cost. Les valeurs qui ne sont pas des nombres sont effacées avec un message.

Fallback cost: un prix forfaitaire lorsqu'aucun prix par pays ne correspond. Laissez vide pour masquer le transporteur dans ce cas.

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

Conditions

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

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

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

Max weight: le transporteur est masqué au-delà de ce poids de panier en kg. Par défaut : 30. USPS accepte jusqu'à 70 lb (31,7 kg). 0 signifie sans limite. Si Min weight est supérieur à Max weight, une erreur s'affiche et les limites précédentes sont conservées.

Disponibilité sans zones d'expédition

Ignore shipping zones: propose le transporteur dans toutes les zones pour les pays indiqués ci-dessous. L'enregistrement rattache le transporteur à toutes les zones de la boutique, y compris celles créées plus tard. Le désactiver rend au transporteur ses zones précédentes.

Countries: les pays de destination pour ce mode. Laissez vide pour autoriser tous les pays vers lesquels la boutique expédie. 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_usps_debug.log.php, dans le dossier du module. Ce fichier ne peut pas être ouvert depuis le web. Les erreurs API sont toujours enregistrées, même si cette option est désactivée. Les clés, les jetons et les adresses des clients ne sont jamais enregistrés.

Log: affiche la taille du journal et ses dernières entrées. Cliquez sur Clear log pour le vider.

Remove data on uninstall: si activé, la désinstallation du module supprime les réglages USPS, le transporteur, les services de commande enregistrés, les tarifs en cache et les journaux. Si désactivé, tout est conservé pour une réinstallation.

Fonctionnement lors du paiement

À l'étape d'expédition, PrestaShop demande au module le prix USPS. Seuls les produits physiques comptent : les produits virtuels n'ajoutent pas de poids et ne sont pas inclus dans le sous-total. Le module vérifie d'abord les conditions : pays autorisés (avec Ignore shipping zones), 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 à USPS.

Le module obtient un jeton OAuth auprès de USPS et le conserve jusqu'à peu de temps avant son expiration. Un jeton rejeté par USPS est renouvelé et le calcul est répété. Pour les destinations aux États-Unis et dans leurs territoires (Porto Rico, îles Vierges américaines, Guam, Samoa américaines, îles Mariannes du Nord, États fédérés de Micronésie, îles Marshall et Palaos), il interroge l'API Domestic Prices et a besoin du code ZIP à 5 chiffres du client. Pour les autres pays, il interroge l'API International Prices avec le pays et le code postal.

La requête contient le code ZIP d'expédition, le poids du panier en livres, la taille du colis en pouces et le type de prix. Les colis de plus de 70 lb reçoivent les prix fixes. Le client voit une seule option, avec le service sélectionné le moins cher, convertie de USD dans la devise par défaut de votre boutique puis affichée dans la devise du panier du client.

Chaque tarif est mis en cache pendant 1 heure. Un calcul en échec est mémorisé pendant 10 minutes. Après un délai d'attente, une erreur serveur, une limite de requêtes ou des clés rejetées, USPS n'est pas sollicité pendant 5 minutes. Le délai HTTP est de 10 secondes.

Si USPS ne renvoie aucun tarif, le prix provient de Country prices, puis de Fallback cost. Si aucun ne s'applique, le transporteur est masqué. Le client ne voit jamais les messages d'erreur de USPS. La raison est écrite dans le journal.

Si vous modifiez le transporteur dans Shipping > Carriers après qu'il a reçu des commandes, PrestaShop l'enregistre comme une nouvelle version du transporteur. Le module suit automatiquement la nouvelle version.

Le module calcule uniquement les tarifs. Il n'achète ni affranchissements ni étiquettes d'expédition, ne réserve pas d'enlèvements, ne suit pas les colis et ne permet pas au client de choisir un bureau de poste ou un point de retrait. Il affiche une seule option, et non plusieurs services USPS. Il n'y a pas de remplissage de cartons : le panier est calculé comme un seul colis. L'assurance et les autres services supplémentaires ne sont pas inclus.

Commandes

Lorsqu'une commande est passée avec le transporteur USPS, le module enregistre la manière dont le prix de livraison a été obtenu. La page de commande de l'administration affiche un bloc USPS avec le USPS service (pour un tarif en temps réel, par exemple USPS Ground Advantage) et le Price source : USPS live rate, Fixed price ou Free shipping.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox USPS est le premier bloc de la page Modules > Module Manager > VibeFox USPS > Configure, 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) 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. Plus bas figurent la ligne Product: presta-shipping-usps 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 : celui de la boutique principale, y compris dans une configuration multiboutique. 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 transporteur USPS 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 ne pouvez pas le tester au moment du paiement. Un rappel apparaît dans Modules > Module Manager, dans 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 que vous travaillez dans le back-office : 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 ou la réinitialisation du module supprime toujours la clé de licence et le statut de la licence.

Dépannage

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

Les tarifs en temps réel n'apparaissent pas : consultez les avertissements en haut de la page du module. Activez Debug log, rechargez la page de paiement et regardez le champ Log. Les clés incorrectes, le mauvais environnement et les messages d'erreur de USPS y sont enregistrés. Les tarifs nationaux nécessitent le code ZIP à 5 chiffres du client.

Ma boutique n'est pas en USD : USPS ne calcule qu'en USD. Saisissez le USD exchange rate. Sans lui, le tarif en temps réel n'est pas utilisé et c'est le prix fixe qui s'affiche.

Un User ID Web Tools ne fonctionne pas : l'ancienne API Web Tools est arrêtée. Créez une application dans le USPS Developer Portal et utilisez son Consumer Key et son Consumer Secret.

Les tarifs semblent périmés après une modification : le cache est vidé lorsque vous enregistrez les réglages. Vous pouvez aussi cliquer sur Clear cached USPS token and rates.

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

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox USPS et choisissez Uninstall. La clé de licence et le statut de la licence sont toujours supprimés. Le jeton et les tarifs en cache sont également toujours supprimés. Si Remove data on uninstall est activé, le transporteur est supprimé (les commandes conservent leur historique), ainsi que les réglages, les services de commande enregistrés et le journal. S'il est désactivé, le transporteur est seulement désactivé et tous les réglages sont conservés. Réinstaller le module, ou utiliser Reset, rend au transporteur enregistré son statut précédent : un transporteur activé le redevient, un transporteur désactivé le reste.

USPS est une marque de son titulaire respectif. Ce module n'est ni affilié à USPS ni approuvé par USPS.