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

Compte Shippo : créez un compte Shippo, connectez ou activez les 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 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_shippo dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

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

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

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

6. Choisissez la Shippo rate currency (USD si vous expédiez depuis les États-Unis) et, si votre boutique utilise une autre devise, saisissez le taux de change.

7. Vous pouvez éventuellement saisir des prix de secours dans le tableau par pays et poids.

8. Ajoutez VibeFox Shippo à une zone d'expédition dans WooCommerce > Settings > Shipping > Shipping zones, ou activez Ignore shipping zones et choisissez des pays.

Configuration

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

Title (zone): le nom que voit le client pour cette zone. Laissez-le vide pour utiliser le Name général.

Chaque fois que vous enregistrez les réglages, les tarifs Shippo mis en cache sont effacés. Les avertissements affichés au-dessus des réglages vous indiquent quand la méthode ne peut 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, ou pas de taux de change. Un avis vous rappelle qu'un jeton de test est défini.

Général

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

Name: le nom de la méthode d'expédition affiché au paiement. Une zone peut le remplacer par son propre Title. Par défaut : Shippo Shipping.

Compte Shippo

API token: votre jeton d'API Shippo. Utilisez le jeton de production (shippo_live_...) pour des tarifs réels sur la boutique en ligne, ou un jeton de test (shippo_test_...) pour les tarifs de test de Shippo.

Allowed carriers / services: facultatif, séparé par des virgules. Saisissez un transporteur comme 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 d'où vos colis sont expédiés ; les champs vides sont repris de l'adresse de la boutique dans WooCommerce > Settings > General 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.

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

City: la ville de l'expéditeur.

State / province: le code de l'État à 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 : United States.

Tarifs

Parcels: la façon dont le panier est envoyé à Shippo.

Default box size: longueur x largeur x hauteur dans l'unité de dimension de votre boutique, 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.

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 de la boutique sont toujours utilisés tels quels.

Exchange rate: le prix de 1 unité de la Shippo rate currency dans la devise 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. L'extension ne convertit pas les devises automatiquement.

Tax status: Taxable permet à WooCommerce d'ajouter la taxe sur l'expédition selon vos règles fiscales, None ne l'ajoute pas. Les tarifs Shippo n'incluent pas les taxes de vente.

Prix de secours (utilisés lorsqu'aucun tarif en direct n'est disponible : pas de jeton d'API, Shippo injoignable, jeton refusé ou aucun tarif de transporteur pour l'adresse ; prix dans la devise de votre boutique ; laissez les deux champs vides pour masquer la méthode 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 la croix 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 égale à 0 utilise la colonne Price. La ligne * Default s'applique aux pays qui n'ont pas leur propre ligne. Une nouvelle ligne commence comme * 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 pour les pays absents du 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 du panier à partir duquel l'expédition est gratuite. Aucune requête n'est alors envoyée à Shippo. Laissez vide pour la désactiver.

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

Minimum weight (kg): le poids minimal du panier pour afficher cette méthode. 0 signifie sans limite.

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

Disabled 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 d'expédition

Ignore shipping zones: propose la méthode pour les pays indiqués ci-dessous, qu'elle soit ajoutée ou non à une zone.

Countries: les pays de destination pour ce mode. Laissez vide pour utiliser tous les pays vers lesquels la boutique expédie. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé. Une méthode ajoutée à une zone d'expédition fonctionne toujours pour les pays de sa zone.

Avancé

Debug log: enregistre les requêtes vers Shippo dans WooCommerce > Status > Logs, source vfd-shippo. Les erreurs de l'API sont toujours enregistrées, même lorsque cette option est désactivée. Le jeton d'API et les adresses des clients ne sont jamais enregistrés.

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

Fonctionnement au 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 désactivées. Si la livraison gratuite s'applique, la méthode est affichée avec un prix de 0 et aucune requête n'est envoyée à Shippo.

L'extension envoie ensuite à Shippo l'adresse d'expédition, l'adresse du client et le colis. Pour les pays où WooCommerce 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 l'extension affiche le tarif autorisé le moins cher, dans la devise de votre boutique, sous le nom de la méthode.

En mode par commande, les articles sont empilés dans un seul carton : le côté le plus long et le côté médian des plus gros articles, ainsi que 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 son propre colis 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 prix de secours. Le délai d'expiration des requêtes est de 10 secondes.

En l'absence de tarif en direct, le prix provient de la grille de secours, puis de Other countries. Si aucun ne s'applique, la méthode est masquée. Le client ne voit jamais d'erreur.

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 calcule uniquement les tarifs. Elle 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 d'optimisation de remplissage des cartons au-delà de l'empilement décrit ci-dessus, ni de majoration du tarif ni de frais de gestion.

Commandes

La ligne d'expédition de la commande enregistre le Carrier / service choisi et, pour un colis par commande, les Estimated delivery days. Vous les voyez sur l'écran d'administration de la commande et pouvez acheter l'étiquette correspondante dans Shippo.

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 Shippo. 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, et 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, Shippo n'est pas affiché aux clients au paiement. Les gestionnaires connectés de la boutique 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 Plugins 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 le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

Shippo n'apparaît pas au 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é). Contrôlez les limites de poids, Minimum subtotal et Disabled shipping classes. Sans tarif en direct, vérifiez que le pays, * Default ou Other countries dispose d'un prix.

Les tarifs en direct n'apparaissent pas : activez Debug log, rechargez le paiement et ouvrez WooCommerce > Status > Logs, source vfd-shippo. Causes fréquentes : pas de jeton d'API ni de code postal d'expédition, une devise de boutique différente de la Shippo rate currency 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é.

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

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

Les tarifs semblent obsolètes après une modification : enregistrez la page des réglages. Cela efface les tarifs Shippo mis en cache.

Pour les développeurs : les filtres vfd_shpo_shipment_request, vfd_shpo_customs_declaration, vfd_shpo_selected_rate et vfd_shpo_api_url modifient le corps de la requête, la déclaration en douane, le tarif choisi et l'URL de l'API.

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 puis 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 toutes les données. 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 les tarifs mis 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 d'expédition.

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