VibeFox Shippo 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.

Compte Shippo : créez un compte Shippo, connectez ou activez des transporteurs (USPS, UPS, FedEx, DHL et d'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 peuvent devoir être vérifiés par Shippo avant que des tarifs en direct ne soient renvoyés. Sans jeton, seuls les prix de secours sont utilisés.

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

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éversement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Shippo 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. Collez votre jeton d'API Shippo et renseignez l'adresse Ship from. Le code postal est obligatoire pour les tarifs en direct.

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

6. Saisissez éventuellement des prix de secours dans le tableau par pays et poids, puis cliquez sur Save.

À l'installation, le module crée le transporteur Shippo Shipping avec le texte de délai de livraison Shippo carriers (USPS, UPS, FedEx, DHL). 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. Ne définissez pas de prix à cet endroit : le prix provient toujours du module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Shippo > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Chaque enregistrement vide aussi le cache des tarifs Shippo.

Les avertissements en haut de la page vous indiquent quand le transporteur ne pourra jamais être affiché 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, pas de taux de change, ou une unité de poids ou de dimensions de la boutique que le module ne connaît pas (réglez kg, g, lb ou oz et cm, mm, m ou in dans International > Localization, unités locales). Un avis vous rappelle lorsqu'un jeton de test est défini. Lors de l'enregistrement, une valeur qui n'est pas un nombre, un nombre négatif ou un Minimum weight (kg) supérieur à Maximum weight (kg) est signalé comme erreur, et rien n'est enregistré tant que vous ne l'avez pas corrigé.

Général

Enable Shippo 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 au paiement. Par défaut : Shippo Shipping. Obligatoire, 64 caractères maximum.

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

Compte Shippo

API token : votre jeton d'API Shippo. Utilisez le jeton réel (shippo_live_...) pour des tarifs réels sur la boutique en production, ou un jeton de test (shippo_test_...) pour les tarifs de test de 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. Saisissez une nouvelle valeur uniquement pour la modifier, ou cochez Remove the saved API token pour la supprimer.

Allowed carriers / services : facultatif, séparés 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.

Expédié depuis (l'adresse d'où vos colis sont envoyés ; les champs vides sont repris de l'adresse de la boutique dans Shop Parameters > Contact > Stores lorsqu'elle se trouve dans le même pays)

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 de région à deux lettres, par exemple CA ou NY. Certains transporteurs en ont besoin.

Postal / ZIP code : obligatoire pour les tarifs en direct.

Country : le pays d'où 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 dimensions 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 un avis après l'enregistrement.

Shippo rate currency : la devise dans laquelle Shippo cote vos transporteurs, c'est-à-dire 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 de 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 prix de secours s'appliquent. Le module ne convertit pas les devises automatiquement.

Prix de secours (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 le transporteur dans ce cas)

Country prices : une grille de prix par pays et 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 (jusqu'à 2 kg), M (jusqu'à 3 kg), L (jusqu'à 5 kg) et XL (plus de 5 kg). Une tranche vide ou à 0 utilise la colonne Price. La ligne * Default s'applique aux pays qui n'ont pas leur propre ligne. Une nouvelle ligne commence en tant que * Default. Une ligne enregistrée avec toutes les cellules vides facture 0, supprimez donc les lignes que vous ne remplissez pas.

Other countries : le prix des pays qui ne figurent pas dans le tableau ci-dessus (lorsqu'il n'y a pas de ligne * Default). Laissez vide pour masquer le transporteur pour ces pays.

Conditions

Free shipping from : le sous-total du panier (après remises, avant taxes) à partir duquel la livraison est gratuite. Aucune requête n'est alors envoyée à Shippo. Laissez vide pour désactiver cette option.

Minimum subtotal : n'affiche le transporteur que si le sous-total du panier (après remises, avant taxes) atteint au moins ce montant. Laissez vide pour toujours l'afficher.

Minimum weight (kg) : le poids minimal du panier pour afficher le transporteur. 0 signifie sans limite.

Maximum weight (kg) : le transporteur est masqué 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 d'expédition

Normalement, le transporteur est proposé dans ses zones d'expédition sous Shipping > Carriers. Il peut aussi être proposé par pays, indépendamment des zones.

Ignore shipping zones : propose le transporteur pour les pays ci-dessous, que leur zone soit affectée ou non. Tant que cette option est active, le transporteur est ajouté à toutes les zones, y compris les zones créées plus tard. La désactiver supprime ces zones ajoutées, et le transporteur conserve ses propres 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 vers Shippo dans logs/vfd_shpo_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs d'API sont toujours journalisées, même si cette option est désactivée. Le jeton d'API et les adresses des clients ne sont jamais journalisés.

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 du module supprime ses réglages, le transporteur et le journal. Si désactivé, tout est conservé 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.

Fonctionnement au paiement

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

Le module envoie ensuite à Shippo l'adresse d'expédition, l'adresse du client et le colis. Pour les pays où PrestaShop exige un code postal, la requête attend que le client l'ait saisi. Pour les envois internationaux, une déclaration en douane comprenant les noms, quantités, poids et valeurs des articles est ajoutée. Shippo renvoie les tarifs de vos transporteurs, et le module utilise le tarif autorisé 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.

En mode par commande, les articles sont empilés dans un seul carton : les côtés les plus longs et intermédiaires des plus grands articles, et les plus petits côtés de toutes les unités additionnés. Si un produit n'a pas de dimensions, le 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 requêtes, le module suspend les requêtes pendant 5 minutes et utilise les prix de secours. Le délai d'attente des requêtes est de 10 secondes.

S'il n'y a pas de tarif en direct, le prix provient de la grille de secours, puis de Other countries. Si aucune ne s'applique, le transporteur est masqué. Le client ne voit jamais d'erreur. La raison est écrite dans le journal de débogage.

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 pas d'étiquettes, ne suit pas les colis, ne valide pas les adresses et ne propose ni points de retrait ou de dépôt, ni assurance, options de signature ou é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 de remplissage de cartons au-delà de l'empilement décrit ci-dessus, ni de majoration de tarif ni de frais de gestion.

Commandes

Lorsqu'une commande est passée avec un tarif Shippo en direct, le module conserve le Carrier / service choisi et, pour un colis par commande, les Estimated delivery days. Ils apparaissent dans le bloc Shippo de la page de commande du back-office, afin que vous puissiez acheter l'étiquette correspondante dans Shippo. Les données sont figées avec la commande : les modifications ultérieures du panier ne les changent pas. Les commandes avec prix de secours ou livraison gratuite n'ont pas de bloc Shippo.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Shippo est le premier bloc de Modules > Module Manager > VibeFox Shippo > 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) et 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-shippo 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 l'emplacement dans votre compte vibefox.net.

Sans clé active, le transporteur Shippo n'est pas affiché aux clients lors du paiement et aucun tarif n'est calculé. La vitrine de 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 pas le tester au 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. Désinstaller ou réinitialiser le module supprime toujours la clé de licence et le statut de licence.

Dépannage

Shippo n'apparaît pas au paiement : vérifiez que la licence est active et que Enable Shippo shipping est activé. Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone du pays du client et le groupe du client (ou que Ignore shipping zones est activé et que le pays est autorisé). Vérifiez les limites de poids et le Minimum subtotal. Sans tarif en direct, vérifiez que le pays, * Default ou Other countries a un prix. Les produits peuvent aussi être limités à certains transporteurs sur la page produit.

Les tarifs en direct n'apparaissent pas : activez le Debug log, rechargez le paiement et consultez le champ Log sur la page du module. 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 de tarifs Shippo sans taux de change, le code postal du client pas encore 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 réel (shippo_live_...).

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

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page du module. Cela vide le cache des tarifs Shippo.

La page indique que le transporteur Shippo 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 Shippo et choisissez Uninstall. La clé de licence et le statut de licence sont toujours supprimés. 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 et le journal sont supprimés. S'il est désactivé, le transporteur est seulement désactivé et tous les réglages sont conservés. Réinstaller le module rend au transporteur le statut qu'il avait auparavant. Les commandes existantes conservent leurs données de transporteur et de service Shippo.

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