VibeFox Shippo for OpenCart — Aide

Prérequis

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

PHP : 8.0 ou ultérieur.

Compte Shippo : créez un compte Shippo, connectez ou activez les transporteurs (USPS, UPS, FedEx, DHL et autres) et copiez le jeton d'API depuis Shippo > Settings > Advanced > API. Shippo facture les étiquettes achetées, et non les demandes de tarifs. Les nouveaux comptes Shippo doivent parfois être vérifiés par Shippo avant que des tarifs en direct ne soient renvoyés. Sans jeton, seuls les tarifs de repli sont utilisés.

Produits : les produits doivent avoir un poids et des dimensions. Les produits sans dimensions utilisent le format de carton par défaut.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un 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_shippo-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_shippo.ocmod.zip. Installez uniquement 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_shippo-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'Installer, vous pouvez aussi copier le contenu du dossier upload du paquet dans le dossier racine de votre boutique.

2. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox Shippo 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 le champ License key du bloc de licence en haut de la page Edit, puis cliquez sur Activate (voir License key).

5. Collez votre jeton d'API Shippo et renseignez l'adresse Ship from. Le code postal est obligatoire pour les tarifs en direct.

6. Choisissez la Shippo rate currency (USD si vous expédiez depuis les États-Unis) et, si la devise par défaut de votre boutique est différente, saisissez le Exchange rate.

7. Saisissez éventuellement des tarifs de repli, activez Enable Shippo shipping et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_shippo.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 sur Install (le bouton vert +) à côté.

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

Après l'installation, la méthode reste désactivée tant que vous n'avez pas activé Enable Shippo shipping et enregistré. Si vous réinstallez l'extension après une désinstallation, les réglages Shippo que vous avez conservés sont de nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox Shippo > Edit. Les sections sont listées à gauche. Un bouton Save enregistre toute la page sans la recharger. Chaque enregistrement efface aussi les tarifs Shippo en cache. Seuls les administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages.

Des avertissements en haut de la page vous indiquent quand la méthode ne pourra jamais être affichée ou quand les tarifs en direct ne peuvent pas être utilisés : pas de jeton d'API, pas de code postal ou de pays d'expédition, taux de change manquant, ou unité de poids ou de longueur de la boutique non reconnue par l'extension (utilisez kg, g, lb ou oz, et cm, mm, m ou in, dans System > Settings, onglet Local). Une notification vous rappelle lorsqu'un jeton de test est défini. Lors de l'enregistrement, un nom non valide, une valeur qui n'est pas un nombre, un nombre ou une cellule de prix négatifs, un Minimum weight (kg) supérieur à Maximum weight (kg) ou un ordre de tri qui n'est pas un nombre entier sont signalés comme erreur, et rien n'est enregistré tant que vous ne les avez pas corrigés.

Général

Enable Shippo shipping : propose la méthode au moment du paiement. C'est l'état de l'extension dans Extensions > Extensions > Shipping.

Name : le nom de la méthode de livraison affiché au client au moment du paiement. Par défaut : Shippo Shipping. Obligatoire, 64 caractères maximum, sans les caractères < > ; = # { }.

Tax class : la classe de taxe du coût de livraison, ou No tax. Les tarifs Shippo n'incluent pas la taxe de vente. No tax les affiche tels qu'ils sont cotés ; une classe de taxe ajoute la taxe sur la livraison selon vos règles fiscales.

Sort order : la position de la méthode parmi les méthodes de livraison au moment du paiement. Un nombre entier.

Compte Shippo

API token : votre jeton d'API Shippo. Utilisez le jeton en direct (shippo_live_...) pour des tarifs réels sur la boutique en production, ou un jeton de test (shippo_test_...) pour les tarifs de test Shippo. Le jeton n'est envoyé qu'à Shippo et n'est jamais journalisé. Après l'enregistrement, le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier.

Remove the saved API token : activez cette option et enregistrez pour supprimer le jeton enregistré.

Allowed carriers / services : facultatif, séparé par des virgules. Saisissez un transporteur tel que Shippo le nomme (USPS, UPS, FedEx, DHL Express) ou un jeton de niveau de service Shippo (usps_priority, ups_ground). Le tarif autorisé le moins cher est affiché. Laissez vide pour afficher le tarif le moins cher de n'importe quel transporteur.

Ship from (l'adresse depuis laquelle vos colis sont expédiés)

Lorsque le pays d'expédition est le pays de votre boutique, un nom d'expéditeur et un état vides sont repris du nom de la boutique et de la région dans System > Settings. OpenCart ne dispose pas d'une rue, d'une ville ou d'un code postal structurés pour la boutique : saisissez-les donc ici.

Sender name / company : le nom de l'expéditeur. Il sert aussi à signer la déclaration en douane. S'il est vide, le nom de la boutique est utilisé.

Street address : la rue de l'expéditeur.

City : la ville de l'expéditeur.

State / province : le code d'État à deux lettres, par exemple CA ou NY. Certains transporteurs en ont besoin.

Postal / ZIP code : obligatoire pour les tarifs en direct, par exemple 94105.

Country : le pays depuis lequel vous expédiez. Par défaut : États-Unis.

Tarifs

Parcels : la manière dont le panier est envoyé à Shippo.

Default box size : longueur x largeur x hauteur dans l'unité de longueur de votre boutique (indiquée dans le nom du champ), par exemple 30 x 20 x 10. Shippo a besoin de la taille du carton. Elle est utilisée lorsqu'un produit du panier n'a pas de dimensions. Laissez vide pour utiliser 30 x 20 x 10 cm. Une valeur illisible est ignorée avec une notification après l'enregistrement, et les autres réglages sont enregistrés.

Shippo rate currency : la devise dans laquelle Shippo cote vos transporteurs, soit la devise du pays d'expédition : USD (États-Unis), CAD (Canada), GBP (Royaume-Uni), EUR (zone euro) ou AUD (Australie). Par défaut : USD. Les tarifs que Shippo renvoie dans la devise par défaut de votre boutique sont toujours utilisés tels quels.

Exchange rate : le prix de 1 unité de la devise des tarifs Shippo, exprimé dans la devise par défaut de votre boutique, par exemple 0.92. Inutile si les deux devises sont identiques. Sans lui, les tarifs dans l'autre devise ne sont pas utilisés et les tarifs de repli s'appliquent. L'extension ne convertit pas les devises automatiquement.

Tarifs de repli (utilisés lorsqu'il n'y a pas de tarif en direct : pas de jeton d'API, Shippo injoignable, jeton refusé, ou aucun tarif de transporteur pour l'adresse ; prix dans la devise par défaut de votre boutique, hors taxes ; laissez les deux champs vides pour masquer la méthode dans ce cas)

Country prices : une grille tarifaire par pays et par poids du panier. Cliquez sur Add country pour ajouter une ligne. Les colonnes sont Price et les tranches de poids XS (jusqu'à 1 kg), S (de 1 à 2 kg), M (de 2 à 3 kg), L (de 3 à 5 kg) et XL (plus de 5 kg). Une tranche vide ou égale à 0 utilise la colonne Price. La ligne * Default s'applique aux pays qui n'ont pas leur propre ligne. Une ligne enregistrée avec toutes ses cellules vides facture 0 : supprimez donc les lignes que vous ne remplirez pas.

Other countries : le prix pour les pays qui ne figurent pas dans le tableau ci-dessus (lorsqu'il n'existe pas de ligne * Default). Laissez vide pour masquer la méthode pour ces pays.

Conditions

Free shipping from : le sous-total des produits nécessitant une livraison (après coupon, avant taxes) à partir duquel la livraison est gratuite. Aucune demande n'est alors envoyée à Shippo. Laissez vide pour désactiver cette option.

Minimum subtotal : n'affiche la méthode que si le sous-total des produits nécessitant une livraison (après coupon, avant taxes) atteint au moins ce montant. Laissez vide pour l'afficher toujours.

Minimum weight (kg) : le poids minimum du panier pour afficher la méthode. 0 signifie sans limite (par défaut).

Maximum weight (kg) : la méthode est masquée au-delà de ce poids de panier. Par défaut : 30. 0 signifie sans limite. Un champ vide est enregistré comme 30.

Disponibilité sans zones de livraison

Normalement, la zone géographique détermine l'endroit où la méthode est proposée. Il est aussi possible de la proposer par pays, indépendamment de la zone géographique.

Geo zone : propose la méthode uniquement pour les adresses situées dans cette zone géographique. All zones (par défaut) signifie sans limite. Non utilisé tant que Ignore shipping zones est activé. Les zones géographiques se gèrent dans System > Localisation > Geo Zones.

Ignore shipping zones : propose la méthode pour les pays indiqués ci-dessous, qu'ils soient ou non dans la zone géographique.

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 Shippo dans storage/logs/vfd_shpo_debug.log.php (sous OpenCart 4, system/storage/logs/vfd_shpo_debug.log.php). Le fichier ne peut pas être lu depuis le web. Les erreurs de l'API sont toujours journalisées, même lorsque cette option est désactivée. Le jeton d'API et les adresses des clients ne sont jamais journalisés. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_shpo_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 : lorsque l'option est activée, la désinstallation de l'extension supprime les réglages Shippo et le journal. Lorsqu'elle est désactivée (par défaut), ils sont conservés pour une réinstallation. Les tarifs en cache sont toujours supprimés. Le transporteur et le service enregistrés avec les commandes font partie de l'historique des commandes et sont conservés.

Import / Export

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

Import : collez un 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 jeton d'API enregistré n'est pas modifié.

Fonctionnement au moment du paiement

Lorsque OpenCart affiche les méthodes de livraison, il demande à l'extension le tarif Shippo. Si une Geo zone est définie (et que Ignore shipping zones est désactivé) et que l'adresse se trouve en dehors, la méthode n'est pas proposée. Seuls les produits dont Requires Shipping est réglé sur Yes comptent : les autres n'ajoutent aucun poids et ne sont pas inclus dans le sous-total. L'extension vérifie ensuite les conditions : les pays de Ignore shipping zones, le poids du panier et le sous-total minimum. Les cartes-cadeaux, les points de fidélité et les avoirs de la boutique ne sont pas pris en compte. Si la livraison gratuite s'applique, le prix est de 0 et aucune demande n'est envoyée à Shippo.

L'extension envoie ensuite à Shippo l'adresse d'expédition de la boutique, l'adresse du client et le colis. Pour les pays où OpenCart exige un code postal, la demande attend que le client l'ait saisi. Pour les envois internationaux, une déclaration en douane comprenant les noms des articles (avec les options choisies), les quantités, les poids et les valeurs est ajoutée. Shippo renvoie les tarifs de vos transporteurs, et l'extension utilise le tarif autorisé le moins cher. Le prix est calculé dans la devise par défaut de votre boutique, arrondi selon ses décimales, puis affiché au client dans sa devise, avec la taxe de la Tax class sélectionnée.

En mode par commande, les articles sont empilés dans un carton : le plus long et le côté médian des plus gros articles, et les plus petits côtés de toutes les unités additionnés. Si un produit n'a pas de dimensions, le format de carton par défaut est utilisé pour l'ensemble du colis. En mode par article, chaque produit est tarifé comme un colis distinct, et le tarif est multiplié par sa quantité.

Chaque réponse est mise en cache pendant 1 heure par adresse et par colis. Lorsque Shippo répond sans tarif utilisable, l'adresse est mémorisée pendant 10 minutes. Après un délai d'attente, un jeton refusé, une erreur serveur ou une limite de débit, l'extension suspend les requêtes pendant 5 minutes et utilise les tarifs de repli. Le délai d'attente des requêtes est de 10 secondes.

En l'absence de tarif en direct, le prix provient de la grille tarifaire de repli, puis de Other countries. Si aucun ne s'applique, la méthode est masquée. Le client ne voit jamais d'erreur. La raison est consignée dans le journal de débogage.

L'extension ne calcule que des tarifs. Elle n'achète pas d'étiquettes, ne suit pas les colis, ne valide pas les adresses et ne propose pas de points de retrait ou de dépôt, d'assurance, d'options de signature ou d'étiquettes de retour. Seul le tarif autorisé le moins cher est affiché, et non une liste de tous les services. Il n'y a pas d'autre optimisation de l'emballage que l'empilement décrit ci-dessus, ni de majoration de tarif ou de frais de traitement.

Sur OpenCart 4, le client clique sur Choose dans le bloc des méthodes de livraison de la page de paiement et choisit Shippo dans la fenêtre Shipping method options. La méthode fonctionne de la même façon que sur OpenCart 3.

Commandes

Lorsqu'une commande est passée avec un tarif Shippo en direct, l'extension conserve le Carrier / service choisi et, pour un colis par commande, les Estimated delivery days. Ouvrez la commande dans Sales > Orders : ces informations apparaissent dans le panneau Shippo, au-dessus de l'historique de la commande, afin que vous puissiez acheter l'étiquette correspondante dans Shippo. Les données sont enregistrées avec la commande : les modifications ultérieures du panier ou des réglages ne les changent pas. Le panneau reste affiché même après que vous avez désactivé la méthode. Les commandes avec un tarif de repli ou une livraison gratuite n'ont pas de panneau Shippo.

OpenCart 4 conserve une seule commande pour le paiement et la met à jour à chaque fois que le client confirme à nouveau. Le tarif Shippo enregistré est mis à jour avec elle. Si le client passe à une autre méthode de livraison, ou si le tarif de repli s'applique désormais, le tarif enregistré est retiré de la commande.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Shippo est le premier bloc de Extensions > Extensions > Shipping > VibeFox Shippo > 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) ainsi que 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 se trouvent la ligne Product: opencart-shipping-shippo 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 état connu.

Une clé fonctionne sur un 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, la méthode de livraison Shippo n'est pas affichée aux clients au moment du paiement, et aucun tarif n'est calculé. Un administrateur connecté à l'administration dans le même navigateur voit toujours la méthode dans la boutique, marquée (unlicensed — visible to admins only), ce qui vous permet de configurer et de 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 de l'administrateur, donc sans clé active la méthode est masquée pour tout le monde. Une fois la page Edit ouverte une fois, 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é à 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 l'état de la licence.

Dépannage

Shippo n'apparaît pas au moment du paiement : vérifiez que la licence est active et que Enable Shippo shipping est activé. Contrôlez la Geo zone (ou, si Ignore shipping zones est activé, les Countries), les limites de poids et le Minimum subtotal. Sans tarif en direct, vérifiez que le pays, la ligne * Default ou Other countries a un prix. Vérifiez que les produits ont Requires Shipping réglé sur Yes.

Les tarifs en direct n'apparaissent pas : activez le Debug log, rechargez le paiement et consultez le champ Log sur la page de l'extension. Causes fréquentes : pas de jeton d'API ni de code postal d'expédition, une devise par défaut de la boutique différente de la devise des tarifs Shippo sans taux de change, le code postal du client n'a pas encore été saisi, aucun transporteur de votre compte Shippo ne dessert l'adresse, ou le compte Shippo n'est pas encore vérifié.

Tarifs de test sur la boutique en production : un jeton de test (shippo_test_...) renvoie des tarifs de test Shippo. Utilisez le jeton en direct (shippo_live_...).

Livraison gratuite pour des pays inattendus : vérifiez la grille tarifaire pour une ligne vide, en particulier une ligne * Default vide. Une ligne dont toutes les cellules sont vides facture 0.

Poids ou formats de carton erronés : si la page signale une unité de poids ou de longueur inconnue, définissez une classe de poids en kg, g, lb ou oz et une classe de longueur en cm, mm, m ou in dans System > Settings, onglet Local.

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page de l'extension. Cela efface les tarifs Shippo en cache.

La page affiche "Warning: You do not have permission to modify VibeFox Shippo!" : votre groupe d'utilisateurs administrateurs ne peut probablement que consulter les réglages. Accordez au groupe l'autorisation de modification pour extension/shipping/vfd_shippo (OpenCart 3) ou extension/vfd_shippo/shipping/vfd_shippo (OpenCart 4) dans System > Users > User Groups.

Pour les développeurs : l'adresse de l'API Shippo peut être remplacée par le réglage vfd_shpo_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 Shippo. La clé de licence et l'état de la licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable Shippo shipping, Sort order, Tax class et Geo zone. Les tarifs en cache sont toujours supprimés. Si Remove data on uninstall est activé, les réglages Shippo et le journal de débogage sont aussi supprimés. Sinon, les autres réglages sont conservés et réutilisés lors d'une nouvelle installation de l'extension. Les commandes existantes conservent leur méthode de livraison, leur coût et les données de transporteur et de service Shippo.

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 Shippo dans la liste des extensions installées, puis sur Delete (le bouton rouge en forme de poubelle) pour supprimer le paquet téléversé.

Shippo est une marque déposée de son propriétaire. Cette extension n'est pas affiliée à Shippo et n'est pas approuvée par Shippo.