VibeFox ShipStation for OpenCart — Aide

Prérequis

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

PHP : 8.0 ou ultérieur.

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 forfait ShipStation. L'extension utilise l'API V1 de ShipStation (API Key et API Secret). 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

Le téléchargement est un fichier zip unique contenant les paquets pour les deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 vfd_shipstation-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_shipstation.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_shipstation-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 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 ShipStation et cliquez sur Install (le bouton vert +).

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

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

5. 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 ceux que vous voulez dans Carrier codes et enregistrez à nouveau.

6. Si la devise par défaut de votre boutique n'est pas celle de votre compte ShipStation, renseignez Exchange rate. Vous pouvez aussi remplir les tarifs de secours.

7. Activez Enable ShipStation shipping et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_shipstation.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é de lui.

3. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox ShipStation, 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 de réglages et ses champs sont identiques dans les deux versions.

Après l'installation, le mode reste désactivé tant que vous ne l'activez pas et n'enregistrez pas. Si vous réinstallez l'extension après une désinstallation, les réglages ShipStation que vous avez conservés sont à nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox ShipStation > Edit. Les sections sont listées à gauche. Un seul bouton Save enregistre toute la page sans la recharger. Chaque enregistrement vide le cache des tarifs ShipStation et vérifie la clé et le secret de l'API. La page affiche ensuite les transporteurs connectés à votre compte avec leurs codes, par exemple "stamps_com (Stamps.com), ups_walleted (UPS by ShipStation)". Seuls les utilisateurs administrateurs disposant de l'autorisation de modification de cette extension peuvent enregistrer les réglages.

Des avertissements en haut de la page vous indiquent quand les tarifs en temps réel ne peuvent pas fonctionner : pas de clés, pas de code transporteur, pas de code postal d'expédition, pas de taux de change, é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 longueur de la boutique ne peut pas être convertie par l'extension. Utilisez kg, g, lb ou oz et cm, mm, m ou in (System > Settings > Option). Un nom invalide, un champ numérique ou une cellule de prix contenant une valeur négative ou un texte qui n'est pas un nombre, un Minimum weight supérieur au Maximum weight, ou un ordre de tri qui n'est pas un nombre entier sont signalés comme erreur, et rien n'est enregistré.

Général

Enable ShipStation shipping : affiche ou masque le mode au moment du paiement. Il s'agit du statut de l'extension dans Extensions > Extensions > Shipping.

Name : le nom du mode de livraison affiché au client lors du paiement. Par défaut : ShipStation 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 ShipStation n'incluent pas la taxe de vente. No tax les affiche tels quels ; une classe de taxe ajoute la taxe sur la livraison selon vos règles fiscales.

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

Compte ShipStation

API Key : l'API Key de 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 manière que la clé.

Remove the saved API key and secret : apparaît une fois les clés enregistrées. Cochez-la 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 vous en avertit. 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" (la valeur par défaut) calcule les tarifs pour votre propre carton et exclut les enveloppes et les cartons à forfait du transporteur. Laissez vide pour calculer le tarif de tous les types de colis proposés par le transporteur.

Expédition depuis

Ship-from postal code : obligatoire pour les tarifs en temps réel, par exemple 78703. ShipStation calcule les tarifs à partir du code postal uniquement, et celui-ci doit se situer dans le pays de votre compte ShipStation. OpenCart n'a pas de code postal de boutique : il n'est donc jamais repris depuis l'adresse de la boutique.

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 de 1 unité de la devise du compte dans la devise par défaut de votre boutique, par exemple 0.92. Nécessaire uniquement lorsque la devise par défaut diffère de celle du compte. Sans lui, les tarifs en temps réel 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 temps réel : pas de clés API, ShipStation injoignable ou 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 mode dans ce cas)

Prices by country : un tableau avec un prix Base par pays et des colonnes de taille selon le poids du colis : XS jusqu'à 1 kg, S jusqu'à 2 kg, M jusqu'à 3 kg, L jusqu'à 5 kg et XL au-delà de 5 kg. Cliquez sur Add country pour ajouter une ligne. Une taille vide utilise le prix de base. Un prix de base de 0 signifie livraison gratuite. La ligne * Default (all other countries) s'applique aux pays sans ligne propre. Une ligne sans aucun prix n'est pas enregistrée.

Other countries : le prix lorsque le tableau n'a pas de prix pour le pays. Laissez-le vide pour masquer le mode dans ce cas.

Conditions

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

Minimum subtotal : afficher le mode uniquement si le sous-total des produits nécessitant une livraison (après le coupon, avant taxes) atteint ce montant. Laissez vide pour l'afficher toujours.

Minimum weight : le poids minimum du panier, dans l'unité de poids de votre boutique (indiquée dans le nom du champ), pour afficher le mode. 0 signifie aucune limite (par défaut).

Maximum weight : le mode est masqué au-delà de ce poids de panier, dans l'unité de poids de votre boutique. 0 signifie aucune limite (par défaut).

Disponibilité

Geo zone : proposer le mode uniquement pour les adresses de cette zone géographique. All zones (par défaut) signifie aucune limite. Non vérifié tant que Ignore shipping zones est activé. Les zones géographiques se gèrent dans System > Localisation > Geo Zones.

Ignore shipping zones : proposer le mode pour les pays indiqués ci-dessous, quelle que soit 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 ShipStation dans storage/logs/vfd_shst_debug.log.php (sous OpenCart 4 system/storage/logs/vfd_shst_debug.log.php). Le fichier ne peut pas être lu depuis le web. Les erreurs de l'API sont toujours consignées, même lorsque cette option est désactivée. La clé et le secret de l'API ainsi que les adresses des clients ne sont jamais consignés. Le code postal est masqué. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_shst_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 ShipStation 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 service ShipStation des commandes passées est toujours conservé.

Import / Export

Export : cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. La clé et le secret de l'API ne sont pas exportés.

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. La clé et le secret de l'API enregistrés sont conservés.

Fonctionnement au moment du paiement

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

L'extension envoie ensuite à ShipStation le code postal d'expédition, le pays de destination, le code d'état, la ville et le code postal, le poids du colis et la taille 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 n'est tarifé qu'au poids.

ShipStation est interrogé une fois par code transporteur. L'extension utilise le tarif autorisé le moins cher, converti dans la devise par défaut de votre boutique et arrondi à ses décimales. Le prix est ensuite affiché dans la devise du client avec la taxe de la Tax class sélectionnée.

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'attente des requêtes est de 12 secondes.

S'il n'existe pas de tarif en temps réel, le prix provient du tableau de secours, puis de Other countries. Si aucun ne s'applique, le mode est masqué. Le client ne voit jamais les messages d'erreur de ShipStation. Les détails sont consignés dans le journal de débogage.

L'extension calcule uniquement les tarifs. Elle n'achète pas d'étiquettes, ne crée pas de commandes ou d'envois dans ShipStation, ne suit pas les colis et ne gère pas les retours. Il n'y a pas de points de retrait, pas de choix entre plusieurs services au moment du paiement, pas de validation d'adresse, pas d'assurance, pas de confirmation de signature, pas de répartition en plusieurs colis et pas de majoration des tarifs.

Sous OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison de la page de paiement et choisit ShipStation dans la fenêtre Shipping method options. Le mode fonctionne de la même façon que sous OpenCart 3.

Commandes

Lorsqu'une commande est passée avec un tarif ShipStation en temps réel, le service choisi est enregistré avec la commande. Ouvrez la commande dans Sales > Orders : le panneau ShipStation, au-dessus de l'historique de la commande, l'affiche sous Service, par exemple "USPS Ground Advantage - Package", afin que vous puissiez créer l'étiquette correspondante dans ShipStation. En mode par article, les services sont listés et séparés par des virgules. Les modifications ultérieures du panier ne le changent pas, et le panneau reste affiché même après la désactivation du mode. Les commandes passées avec un tarif de secours ou une livraison gratuite n'ont pas de panneau ShipStation.

OpenCart 4 conserve une seule commande pour le paiement et la met à jour chaque fois que le client confirme à nouveau. Le service ShipStation enregistré est mis à jour avec elle. Si le client passe à un autre mode de livraison, ou si le tarif de secours s'applique désormais, le service 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 ShipStation est le premier bloc de la page Extensions > Extensions > Shipping > VibeFox ShipStation > 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) et les boutons Check now pour revérifier 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-shipstation et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les utilisateurs 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-le dans votre compte vibefox.net.

Sans clé active, ShipStation n'est pas affiché aux clients au moment du paiement et aucun tarif n'est calculé. Un utilisateur 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é. Sous 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 à l'ouverture du Dashboard de l'administration ou de 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 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é. Contrôlez Geo zone (ou, si Ignore shipping zones est activé, Countries), les limites de poids et le Minimum subtotal. Sans tarif en temps réel, vérifiez que le pays, * Default ou Other countries a un prix. Vérifiez que les produits ont Requires Shipping réglé sur Yes.

Le paiement affiche le tarif de secours au lieu du tarif ShipStation : consultez les avertissements en haut de la page de l'extension (clés, code transporteur, code postal d'expédition, taux de change). Activez Debug log, rechargez la page de paiement et regardez le champ Log. Le code postal du client est obligatoire. Aucune requête n'est faite tant qu'il n'est pas saisi.

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 carton. Les produits sans dimensions ne sont tarifés qu'au poids. Les tarifs sont mis en cache pendant 1 heure. Cliquez sur Save sur la page de l'extension pour vider le cache.

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

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

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox ShipStation. La clé de licence et le statut de la licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable ShipStation shipping, Sort order, Tax class et Geo zone. Les tarifs en cache et le résultat de la vérification de connexion sont toujours supprimés. Si Remove data on uninstall est activé, les réglages ShipStation 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 lors d'une nouvelle installation de l'extension. Les commandes existantes conservent leur mode de livraison, leur coût et leur service ShipStation.

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

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