VibeFox ShipStation 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 ShipStation : connectez vos transporteurs dans ShipStation (Settings > Shipping > Carriers), puis copiez l'API Key et l'API Secret depuis ShipStation > Settings > Account > API Settings. L'accès à l'API dépend de votre offre ShipStation. Si la page n'est pas disponible, votre offre n'inclut pas l'accès à l'API. Le module utilise l'API V1 de ShipStation (API Key et API Secret). Les comptes ShipStation API V2 avec une seule clé d'API ne sont pas pris en charge. Sans clés, seuls les tarifs de secours sont utilisé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. Lorsque le téléversement est terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox ShipStation dans la liste des modules et cliquez sur Configure.

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

4. Collez l'API Key et l'API Secret, saisissez le code postal d'expédition et cliquez sur Save. La page affiche alors les codes transporteur de votre compte. Saisissez celui ou ceux que vous voulez dans Carrier codes et enregistrez à nouveau.

5. Si la devise par défaut de votre boutique n'est pas la devise de votre compte ShipStation, renseignez Exchange rate.

6. Vous pouvez éventuellement renseigner les tarifs de secours.

À l'installation, le module crée le transporteur ShipStation Shipping avec le texte de délai de livraison ShipStation carriers (USPS, UPS, FedEx, ...). 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 ShipStation > Configure. Chaque section possède son propre bouton Save, qui enregistre la page entière. Chaque enregistrement vide le cache des tarifs ShipStation et vérifie l'API Key et l'API Secret. La page affiche ensuite les transporteurs connectés à votre compte avec leurs codes, par exemple « stamps_com (Stamps.com), ups_walleted (UPS by ShipStation) ».

Les avertissements en haut de la page vous indiquent quand les tarifs en direct ne peuvent pas fonctionner : pas de clés, pas de code transporteur, pas de code postal d'expédition, taux de change manquant, échec de la vérification de connexion ou codes transporteur non connectés à votre compte. Un avertissement apparaît aussi lorsque l'unité de poids ou de dimension de la boutique n'est pas convertible par le module. Réglez kg, g, lb ou oz, ainsi que cm, mm, m ou in, dans International > Localization (Local units). Un champ numérique à valeur négative, un texte qui n'est pas un nombre, ou un Minimum weight supérieur au Maximum weight est signalé comme erreur et rien n'est enregistré.

Général

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

Tax : la règle de taxe du transporteur, ou No tax. Les tarifs ShipStation 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 ShipStation

API Key : l'API Key depuis ShipStation > Settings > Account > API Settings. Elle n'est envoyée qu'à ShipStation et n'est jamais journalisée. 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.

API Secret : l'API Secret de la même page. Elle est traitée de la même façon que la clé.

Remove the saved API key and secret : apparaît une fois les clés enregistrées. Cochez-le et enregistrez pour supprimer les deux.

Carrier codes : un ou plusieurs codes transporteur ShipStation, séparés par des virgules, par exemple stamps_com, ups_walleted. Jusqu'à 5 codes sont utilisés, avec une requête API par transporteur. Si vous en saisissez davantage, seuls les 5 premiers sont conservés et la page l'indique. Le tarif le moins cher de ces transporteurs est affiché. Prenez les codes dans la liste affichée après l'enregistrement.

Allowed services : facultatif, codes de service ShipStation séparés par des virgules, par exemple usps_priority_mail, ups_ground. Laissez vide pour afficher le service le moins cher des transporteurs indiqués ci-dessus.

Package code : « package » (par défaut) tarifie votre propre carton et exclut les enveloppes et les cartons à forfait du transporteur. Laissez vide pour tarifer tous les types de colis proposés par le transporteur.

Expédition depuis

Ship-from postal code : obligatoire pour les tarifs en direct. ShipStation calcule le tarif à partir du code postal uniquement, et celui-ci doit se trouver dans le pays de votre compte ShipStation. Laissez vide pour utiliser le code postal de la boutique, défini dans Shop Parameters > Contact > Stores.

Tarifs

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

ShipStation account currency : la devise dans laquelle ShipStation renvoie les tarifs : USD, CAD, GBP, AUD, NZD ou EUR. Par défaut : USD (comptes américains).

Exchange rate : le prix d'1 unité de la devise du compte dans la devise par défaut de votre boutique, par exemple 0.92. Il n'est nécessaire que si la devise par défaut diffère de celle du compte. Sans lui, les tarifs en direct ne sont pas utilisés et les tarifs de secours s'appliquent. Les taux de change ne sont pas mis à jour automatiquement.

Tarifs de secours (utilisés lorsqu'il n'y a pas de tarif en direct : pas de clés API, ShipStation injoignable, aucun tarif transporteur pour l'adresse ; prix dans la devise par défaut de votre boutique ; laissez le tableau et Other countries vides pour masquer le transporteur dans ce cas)

Prices by country : un tableau avec un tarif de base par pays et des colonnes de taille selon le poids du colis : XS ≤ 1 kg, S ≤ 2 kg, M ≤ 3 kg, L ≤ 5 kg et XL > 5 kg. Cliquez sur Add country pour ajouter une ligne, et sur l'icône de corbeille pour en supprimer une. Une taille vide utilise le tarif de base. Un tarif de base de 0 signifie livraison gratuite. La ligne * Default (all other countries) s'applique aux pays qui n'ont pas de ligne propre. Une ligne sans aucun prix n'est pas enregistrée.

Other countries : le tarif lorsque le tableau ne comporte pas de prix pour le pays. Laissez vide pour masquer le transporteur dans ce cas.

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 à ShipStation. Laissez vide pour désactiver l'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 l'afficher toujours.

Minimum weight : le poids minimum du panier, dans l'unité de poids de votre boutique, pour afficher le transporteur. 0 signifie aucune limite.

Maximum weight : le transporteur est masqué au-dessus de ce poids de panier, dans l'unité de poids de votre boutique. 0 signifie aucune limite.

Disponibilité sans zones de livraison

En règle générale, le transporteur est proposé dans ses zones, dans Shipping > Carriers. Il peut aussi être proposé par pays.

Ignore shipping zones : propose le transporteur pour les pays indiqués ci-dessous, que leur zone soit affectée ou non. Tant que l'option est active, le transporteur est ajouté à toutes les zones, y compris celles créées plus tard. La désactiver supprime ces zones ajoutées.

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 : journalise les requêtes à ShipStation dans logs/vfd_shst_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs de l'API sont toujours journalisées, même si cette option est désactivée. La clé API, le secret et les adresses des clients ne sont jamais journalisés. Le code postal est masqué.

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

Remove data on uninstall : lorsqu'elle est active, la désinstallation du module supprime les réglages, le transporteur, le journal et le service ShipStation enregistré avec les commandes. Lorsqu'elle est désactivée, tout est conservé pour une réinstallation.

Fonctionnement au moment du paiement

À l'étape d'expédition, PrestaShop demande au module le prix. 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 transporteur est affiché avec un prix de 0 et aucune requête n'est envoyée à ShipStation.

Le module envoie ensuite à ShipStation le code postal d'expédition, le pays de destination, la région, la ville et le code postal, le poids du colis et les dimensions du carton. Aucune requête n'est faite avant que le client ait saisi un code postal. Les pays sans codes postaux reçoivent les tarifs de secours. Les articles sont empilés dans un seul carton. Si un produit n'a pas de dimensions, le colis est tarifé au poids seulement.

ShipStation est interrogé une fois par code transporteur. Le module utilise le tarif autorisé le moins cher, converti dans la devise par défaut de votre boutique. Le prix est ensuite affiché dans la devise du panier du client.

Chaque réponse est mise en cache pendant 1 heure. Lorsque ShipStation répond sans tarif exploitable, la réponse est retenue pendant 10 minutes. Lorsque ShipStation rejette les clés ou est injoignable, les requêtes sont suspendues pendant 5 minutes. Après une limite de débit, la pause suit l'heure de réinitialisation indiquée par ShipStation. Le délai d'expiration des requêtes est de 12 secondes. Désactiver le module vide le cache des tarifs.

S'il n'y a pas de tarif en direct, le prix provient du tableau des tarifs de secours, puis de Other countries. Si aucun ne s'applique, le transporteur est masqué. Le client ne voit jamais les messages d'erreur de ShipStation. Les détails sont envoyés au 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 ne calcule que des tarifs. Il n'achète pas d'étiquettes, ne crée ni commandes ni envois dans ShipStation, ne suit pas les colis et ne gère pas les retours. Il n'y a ni points relais, ni choix entre plusieurs services au moment du paiement, ni vérification d'adresse, ni assurance, ni confirmation de signature, ni répartition en plusieurs colis, ni majoration des tarifs.

Commandes

Lorsqu'une commande est passée avec un tarif ShipStation en direct, le service choisi est enregistré avec la commande. La page de commande du back office l'affiche dans un bloc ShipStation, sous le libellé Service, par exemple « USPS Ground Advantage - Package », afin que vous puissiez créer l'étiquette correspondante dans ShipStation. Les recalculs ultérieurs du panier ne le modifient pas. Les commandes passées avec un tarif de secours ou la livraison gratuite n'ont pas de bloc de service.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox ShipStation est le premier bloc de Modules > Module Manager > VibeFox ShipStation > 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 valable 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: presta-shipping-shipstation 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 : le domaine 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 ShipStation n'est pas affiché aux clients au moment du paiement et aucun tarif n'est calculé. La boutique PrestaShop ne sait pas que vous êtes connecté au back office, donc le transporteur est aussi masqué pour vous : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au moment du paiement. Un rappel apparaît dans Modules > Module Manager, sous l'onglet Alerts. Les commandes existantes ne sont pas affectées.

Lorsqu'une licence arrive à expiration, le module continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement pendant votre travail 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

ShipStation n'apparaît pas au moment du paiement : vérifiez que la licence est active et que Enable ShipStation 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 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.

Le paiement affiche le tarif de secours au lieu du tarif ShipStation : vérifiez les avertissements en haut de la page du module (clés, code transporteur, code postal d'expédition, taux de change). Activez le Debug log, rechargez le paiement et consultez le champ Log. Le code postal du client est obligatoire. Aucune requête n'est faite avant sa saisie.

Quel code transporteur saisir : enregistrez les réglages avec la clé et le secret. La page affiche les codes transporteur de votre compte. Utilisez-en un ou plusieurs.

La vérification de connexion à ShipStation a échoué : le message indique la raison. Vérifiez l'API Key et l'API Secret, puis enregistrez à nouveau pour relancer la vérification.

Le tarif diffère de celui de ShipStation : le colis est construit à partir des poids et dimensions des produits, les articles étant empilés dans un seul carton. Les produits sans dimensions sont tarifés au poids seulement. Les tarifs sont mis en cache pendant 1 heure. Cliquez sur Save sur la page du module pour vider le cache.

La page indique que le transporteur ShipStation 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 ShipStation et choisissez Uninstall. La clé de licence et le statut de la licence sont toujours supprimés. Le cache des tarifs et le résultat de la vérification de connexion sont toujours supprimés. Si Remove data on uninstall est activé, le transporteur est supprimé (les commandes conservent leur historique), et les réglages, le journal et le service enregistré avec les commandes sont supprimés. Si elle est désactivée, le transporteur est seulement désactivé, et les réglages ainsi que le service des commandes passées sont conservés. Réinstaller le module, ou effectuer une réinitialisation, rend au transporteur le statut qu'il avait auparavant.

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