VibeFox USPS for OpenCart — Aide

Prérequis

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

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

Application du portail développeurs USPS (pour les tarifs en temps réel uniquement): connectez-vous au portail développeurs USPS (developers.usps.com) avec un compte professionnel USPS gratuit, créez une application et copiez son Consumer Key et son Consumer Secret. L'extension utilise les API USPS actuelles avec OAuth 2.0. L'ancien Web Tools User ID ne fonctionne pas avec elles. Sans clés, seuls les prix fixes sont utilisés.

Code postal d'expédition: les tarifs en temps réel nécessitent le code postal américain à 5 chiffres 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

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_usps-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_usps.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_usps-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 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 USPS et cliquez sur Install (le bouton vert +).

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

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

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

6. Vous pouvez éventuellement saisir des prix fixes de secours, activer Enable USPS shipping et cliquer sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_usps.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 prend le code de l'extension dans le 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 à côté sur Install (le bouton vert +).

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

4. Saisissez la clé de licence et les réglages comme aux étapes 4 à 6 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 USPS shipping et enregistré. Si vous réinstallez l'extension après une désinstallation, les réglages USPS conservés sont de nouveau utilisés.

Configuration

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

Une valeur non valide n'est pas enregistrée: la page indique le champ, rétablit la valeur précédente et affiche The other settings were saved. Cela concerne un nom vide, trop long ou contenant des caractères interdits, un nombre négatif ou non numérique, un code postal qui ne comporte pas 5 chiffres, une taille de carton incorrecte, un Min weight (kg) supérieur à Max weight (kg) (les deux limites conservent leurs valeurs), un ordre de tri qui n'est pas un nombre entier, ainsi qu'une classe de taxe ou une zone géographique inconnue. Les prix par pays qui ne sont pas des nombres sont effacés et listés. Les avertissements affichés au-dessus des réglages indiquent qu'une seule des deux clés est renseignée, qu'il n'y a ni clé ni prix fixe (le mode n'est alors jamais affiché), que le code postal manque, qu'aucun service n'est sélectionné, que le taux de change USD manque, que l'environnement de test est activé, 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. USPS est proposé comme une option de livraison au paiement.

Enable USPS shipping: propose la livraison USPS au paiement. Par défaut: désactivé.

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

Tax class: la classe de taxe du coût de livraison. Les prix USPS n'incluent pas les taxes. No tax (par défaut) signifie que la livraison n'est pas taxée.

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

API USPS (tarifs en temps réel)

Consumer Key: le Consumer Key (client_id) de votre application développeur USPS. Le vider supprime aussi le Consumer Secret enregistré.

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. Clearing the Consumer Key removes it too. Ne saisissez une valeur que si vous voulez la modifier.

Test environment: utilisez le Testing Environment USPS pour les expéditeurs. Uniquement pour les applications qui y ont accès. Laissez-le désactivé pour les vrais prix. Par défaut: désactivé.

Prices: la liste de prix USPS utilisée.

Services: les services USPS pouvant être proposés. Le service sélectionné le moins cher que USPS propose pour le colis est affiché. Choisissez parmi USPS Ground Advantage, Priority Mail / Priority Mail International, Priority Mail Express / Priority Mail Express International, First-Class Package International Service, Media Mail (books and media only) et Library Mail (libraries and schools only). Par défaut: Ground Advantage, Priority Mail et First-Class Package International. Les tarifs Flat Rate, Cubic, Hold for Pickup et Sunday ne sont jamais utilisés. Si aucun service n'est sélectionné, les tarifs en temps réel ne sont pas utilisés.

USD exchange rate: les prix 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 votre devise, par exemple 0.92. Il doit être supérieur à 0. Sans lui, les tarifs en temps réel ne sont pas utilisés et les prix fixes s'appliquent. Si la devise de votre boutique est l'USD, il n'est pas nécessaire. Le taux n'est pas mis à jour automatiquement.

Cache: les tarifs sont mis en cache pendant 1 heure et un tarif en échec pendant 10 minutes. Après un délai dépassé, une erreur serveur, une limite de requêtes ou des clés rejetées, USPS n'est plus sollicité pendant 5 minutes. Cliquez sur Clear cached USPS token and rates pour vider le cache immédiatement.

Expédition et colis (les prix USPS dépendent du code postal d'origine, du poids et de la taille du colis; le panier est calculé comme un seul colis)

Ship from ZIP code: le code postal américain à 5 chiffres d'où les colis sont expédiés. Le ZIP+4 est réduit à 5 chiffres. OpenCart n'a pas de code postal de boutique, saisissez-le donc ici.

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. Laissez vide pour utiliser les dimensions du produit: la plus grande longueur, la plus grande largeur et les hauteurs empilées. Les produits sans dimensions sont calculés comme un carton de 10 x 8 x 4 pouces.

Default product weight (kg): le poids utilisé pour les produits sans poids, dans les tarifs USPS, les limites de poids et les tranches de poids. Par défaut: 0.5. Vide signifie également 0,5 kg.

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; laissez les deux vides pour masquer le mode dans ce cas)

Country prices: prix selon le pays de destination et le poids du panier. Cliquez sur Add country pour ajouter une ligne et sur le bouton de suppression pour en retirer une. Les tranches de poids sont XS jusqu'à 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg et XL au-delà de 5 kg. Une tranche vide ou à 0 utilise Price. * Default (any other country) s'applique à tous les autres pays.

Fallback cost: un prix forfaitaire lorsqu'aucun prix par pays ne correspond. Laissez-le 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) calcule chaque produit selon son propre poids multiplié 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 des produits nécessitant une livraison (après le coupon, avant taxes) à partir duquel ce mode est gratuit. Aucune requête n'est alors envoyée à USPS. Laissez vide pour ne jamais proposer la livraison gratuite.

Minimum subtotal: n'afficher le mode que si le sous-total des produits nécessitant une livraison (après le coupon, avant taxes) 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-delà de ce poids de panier. Par défaut: 30. Vide signifie 30 kg, 0 signifie aucune limite. USPS accepte jusqu'à 70 lb (31,7 kg): les colis plus lourds reçoivent les prix fixes.

Geo zone: proposer USPS 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 pas vérifier la zone géographique. Le mode est proposé pour les pays ci-dessous.

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

Avancé

Debug log: consigne les requêtes API et le calcul des tarifs dans storage/logs/vfd_usps_debug.log.php (sur OpenCart 4 system/storage/logs/vfd_usps_debug.log.php). Le fichier ne peut pas être lu depuis le web. Les erreurs API sont toujours consignées, même lorsque cette option est désactivée. Les clés, les jetons, les codes postaux et les adresses des clients ne sont jamais consignés. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_usps_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: si activé, la désinstallation de l'extension supprime les réglages USPS et le journal. Les tarifs en cache sont toujours supprimés. Les services USPS des commandes passées sont toujours conservés. Si désactivé, les réglages sont conservés pour une réinstallation.

Import / Export

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

Import: collez le 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. Le Consumer Secret enregistré est conservé.

Fonctionnement au paiement

Lorsque OpenCart affiche les modes de livraison, il demande à l'extension le prix USPS. Si une Geo zone est définie et que l'adresse est en dehors, USPS n'est pas proposé (avec Ignore shipping zones, c'est la liste des pays qui décide). Seuls les produits dont Requires Shipping est sur Yes comptent: les autres produits n'ajoutent aucun poids et ne sont pas inclus dans le sous-total. Les cartes cadeaux, les points de fidélité et les avoirs de la 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 0 et aucune requête n'est envoyée à USPS.

L'extension obtient un jeton OAuth auprès de USPS et le conserve jusqu'à peu avant son expiration. Pour les destinations aux États-Unis et dans leurs territoires (Porto Rico, îles Vierges américaines, Guam, Samoa américaines, îles Mariannes du Nord, Micronésie, îles Marshall et Palaos), elle demande les tarifs nationaux et a besoin du code postal à 5 chiffres du client: sans lui, aucune requête n'est envoyée. Pour les autres pays, elle demande les tarifs internationaux.

La requête contient le code postal d'expédition, le poids du panier, la taille du colis 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. Le prix en USD est converti dans votre devise par défaut, arrondi à ses décimales, et affiché dans la devise du client avec la taxe de la Tax class sélectionnée.

Chaque tarif est mis en cache pendant 1 heure. Un tarif en échec est mémorisé pendant 10 minutes. Après un délai dépassé, une erreur serveur, une limite de requêtes ou des clés rejetées, USPS n'est plus sollicité pendant 5 minutes. Le délai d'expiration 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 mode est masqué. Le client ne voit jamais les messages d'erreur USPS. La raison est écrite dans le journal de débogage.

L'extension calcule uniquement les tarifs. Elle 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. Elle affiche une seule option, et non plusieurs services USPS. Il n'y a pas de mise en carton: le panier est calculé comme un seul colis. L'assurance et les autres services supplémentaires ne sont pas inclus.

Sur OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison de la page de paiement, puis choisit USPS 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 USPS, l'extension enregistre la manière dont le prix de livraison a été déterminé. La page de commande dans Sales > Orders affiche un panneau USPS avec le USPS service (pour un tarif en temps réel, par exemple USPS Ground Advantage), la Price source (USPS live rate, Fixed price ou Free shipping) et le Calculated price (excl. tax). Ces valeurs sont enregistrées lors de la passation de la commande.

OpenCart 4 conserve une seule commande pour le paiement et la met à jour chaque fois que le client confirme à nouveau. Les valeurs enregistrées sont mises à jour avec elle. Si le client choisit un autre mode de livraison, elles sont retirées de la commande. Sur OpenCart 4, le panneau USPS 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 USPS est le premier bloc de Extensions > Extensions > Shipping > VibeFox USPS > Edit, 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. En dessous figurent la ligne Product: opencart-shipping-usps et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les 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 statut 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 l'emplacement dans votre compte vibefox.net.

Sans clé active, USPS 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. Le statut est vérifié à nouveau automatiquement lorsque vous ouvrez le Dashboard de l'administration ou la page Edit : 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 le statut de licence.

Dépannage

USPS n'apparaît pas au paiement: vérifiez que la licence est active et que Enable USPS shipping est activé. Vérifiez la Geo zone, ou activez Ignore shipping zones et vérifiez Countries. Vérifiez les limites de poids et le Minimum subtotal. Sans clés USPS fonctionnelles, le mode a besoin d'un prix fixe (Country prices ou Fallback cost). Vérifiez que les produits ont Requires Shipping sur Yes.

Les tarifs en temps réel n'apparaissent pas: vérifiez les avertissements en haut de la page Edit: les deux clés, le code postal, au moins un service et, pour les boutiques qui ne sont pas en USD, le taux de change. Les clients américains doivent saisir un code postal. Activez Debug log, rechargez le paiement et consultez le champ Log sur la page de l'extension.

Les tarifs ne sont pas de vrais prix: désactivez Test environment.

La page signale un problème d'unité de poids ou de longueur: sans classe de poids avec l'unité 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 est traitée comme des cm. Utilisez cm, mm, m ou in comme classe de longueur de la boutique (System > Settings, onglet Option).

Les tarifs semblent obsolètes après une modification: cliquez sur Save sur la page de l'extension ou sur Clear cached USPS token and rates.

La page affiche "Warning: You do not have permission to modify VibeFox USPS!": 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_usps (OpenCart 3) ou extension/vfd_usps/shipping/vfd_usps (OpenCart 4) dans System > Users > User Groups.

Pour les développeurs: l'adresse de l'API USPS peut être remplacée avec le réglage vfd_usps_api_url (pour les tests); il n'a pas de champ sur la page des réglages.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox USPS. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable USPS shipping, Sort order, Tax class et Geo zone. Le jeton et les tarifs USPS en cache sont toujours supprimés. Si Remove data on uninstall est activé, les réglages USPS et le journal de débogage sont également supprimés. S'il est désactivé, les autres réglages sont conservés et réutilisés lorsque vous réinstallez l'extension. Les données USPS des commandes passées ne sont jamais supprimées, 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 USPS dans la liste des extensions installées, puis sur Delete (le bouton corbeille rouge) pour supprimer le paquet téléversé.

USPS est une marque déposée de son titulaire. Cette extension n'est ni affiliée à USPS ni approuvée par USPS.