VibeFox SMSA Express 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.

Grille tarifaire SMSA Express : les prix du tableau proviennent de votre compte SMSA ou de l'équipe commerciale de SMSA. Saisissez-les dans la devise par défaut de votre boutique. Si votre grille est en SAR, AED ou dans une autre devise, convertissez-la d'abord.

passKey SMSA (uniquement pour les tarifs en temps réel) : les tarifs en temps réel utilisent le service web SMSA (SECOM, opération getShipCharges). SMSA délivre le passKey sur demande : adressez-vous à votre responsable de compte SMSA ou écrivez à info@smsaexpress.com. Le passKey peut être différent de la clé API du portail e-commerce de SMSA. SMSA ne propose pas de serveur de test (sandbox) pour ce service.

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 contenant les paquets pour les deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 vfd_smsa_express-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_smsa_express.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_smsa_express-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 SMSA Express 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. Saisissez vos prix SMSA Express dans le tableau de prix.

6. Facultatif : sous Live rates (API), activez Live charges, saisissez votre passKey SMSA, la ville et le pays d'expédition et, si la devise par défaut de votre boutique n'est pas le SAR, le taux de change.

7. Activez Enable SMSA Express et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_smsa_express.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 tire le code de l'extension du 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 SMSA Express, 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 les mêmes dans les deux versions.

Après l'installation, le mode reste désactivé tant que vous n'activez pas Enable SMSA Express et n'enregistrez pas. Si vous réinstallez l'extension après une désinstallation, les réglages SMSA Express 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 SMSA Express > Edit. Les sections sont listées à gauche. Un seul bouton Save enregistre toute la page sans la recharger. Chaque enregistrement vide aussi le cache des tarifs SMSA. Un titre de mode non valide, une valeur qui n'est pas un nombre, un nombre négatif, un taux de change de 0, un code de devise qui ne compte pas 3 lettres, un prix erroné dans le tableau, un Minimum weight (kg) supérieur au Maximum weight (kg) ou un ordre de tri qui n'est pas un nombre entier sont refusés avec une erreur, et rien n'est enregistré tant que vous n'avez pas corrigé. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification de cette extension peuvent enregistrer les réglages.

Lorsque les tarifs en temps réel sont activés, des avertissements affichés au-dessus des réglages vous signalent un passKey, une ville ou un taux de change d'expédition manquant, ou un tableau de prix vide. Un avertissement apparaît aussi si la boutique n'a pas de classe de poids en kg et si son unité de poids par défaut n'est pas connue de l'extension (les poids des produits sont alors lus en kg). Ajoutez une classe de poids en kg dans System > Localisation > Weight Classes.

Général

Les réglages s'appliquent à toutes les zones géographiques. Vous pouvez limiter le mode à une zone géographique dans Conditions, ou à une liste de pays avec Ignore shipping zones.

Enable SMSA Express : affiche ou masque SMSA Express au moment du paiement. Par défaut : désactivé.

Method title : le nom du mode de livraison affiché au client dans le panier et au moment du paiement. Par défaut : SMSA Express. Obligatoire, 64 caractères maximum, sans les caractères < > ; = # { }.

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

Tarifs en temps réel (API) (facultatif ; si SMSA ne renvoie aucun tarif, le tableau de prix est utilisé)

Live charges : obtient le tarif de livraison auprès de SMSA Express. Lorsque l'option est désactivée, rien n'est envoyé à SMSA au moment du paiement. Par défaut : désactivé.

SMSA passKey : la clé du service web SMSA (SECOM). 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. Cochez Remove the saved passKey pour la supprimer. Si le journal affiche "Invalid Passkey", cette clé n'est pas acceptée par ce service. Demandez à SMSA un passKey pour le service web.

Ship-from city : la ville d'où partent vos colis, écrite comme le fait SMSA, par exemple Riyadh, Jeddah ou Dammam. Obligatoire pour les tarifs en temps réel : OpenCart n'a pas de ville de boutique, elle n'est donc jamais reprise depuis l'adresse de la boutique.

Ship-from country : le pays d'où partent vos colis. La première option, Store country, utilise le pays de votre boutique défini dans System > Settings > Store > Local. C'est la valeur par défaut.

Shipment type : envoyé à SMSA comme type d'envoi. DLV (la valeur par défaut) correspond à la livraison standard. Ne le modifiez que si SMSA vous a communiqué un autre code.

Currency of SMSA charges : le code à 3 lettres de la devise dans laquelle SMSA renvoie les tarifs, généralement SAR (la valeur par défaut). Un tarif dans une devise autre que celle-ci ou que la devise par défaut de votre boutique n'est pas utilisé.

Exchange rate : le prix de 1 unité de la devise SMSA dans la devise par défaut de votre boutique, par exemple 0.27. Inutile lorsque les deux devises sont identiques. Sans lui, les tarifs dans une autre devise ne sont pas utilisés et le tableau de prix s'applique.

Prix (votre grille SMSA Express dans la devise par défaut de votre boutique ; utilisée lorsque les tarifs en temps réel sont désactivés, et en secours lorsque SMSA ne renvoie aucun tarif)

Price table : une ligne par pays de destination. Cliquez sur Add country pour ajouter une ligne. La ligne * All other countries s'applique aux pays sans ligne propre. Chaque ligne a un prix Base et des colonnes de poids : XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg et XL >5 kg. Une colonne de poids vide ou égale à 0 utilise le prix de base. Un prix de base de 0 signifie livraison gratuite. Les lignes sans aucun prix ne sont pas enregistrées. Si un pays a deux lignes, la première est utilisée. "9.99" et "9,99" sont tous deux acceptés.

Price for countries not in the table : utilisé lorsque le tableau n'a pas de ligne pour le pays de destination (et pas de ligne *) ou lorsque la ligne n'a pas de prix pour ce poids. Laissez vide pour masquer le mode dans ce cas.

Price applies : la manière dont le prix est calculé.

Les poids des produits sont convertis de leur classe de poids OpenCart en kilogrammes.

Conditions

Minimum weight (kg) : masque le mode lorsque le panier pèse moins. 0 signifie aucune limite (par défaut).

Maximum weight (kg) : masque le mode lorsque le panier pèse plus. Par défaut : 30. 0 ou un champ vide signifie aucune limite.

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

Free shipping from : le sous-total des produits nécessitant une livraison (après le coupon, avant taxes) à partir duquel la livraison SMSA Express est gratuite. Lorsque le panier l'atteint, le prix est de 0 et aucune requête n'est envoyée à SMSA. Laissez vide pour ne jamais proposer la livraison gratuite.

Tax class : la classe de taxe du coût de livraison, ou No tax (par défaut). Choisissez No tax si vos prix (le tableau et les tarifs SMSA) incluent déjà la taxe, par exemple la TVA saoudienne.

Geo zone : proposer SMSA Express 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.

Disponibilité sans zones d'expédition

Normalement, le mode est proposé pour les adresses de la zone géographique choisie dans Conditions.

Ignore shipping zones : proposer SMSA Express pour les pays indiqués ci-dessous, quelle que soit la zone géographique. Lorsque l'option est désactivée, c'est la zone géographique qui décide et la liste de pays n'est pas utilisée.

Countries : les pays de destination pour ce mode. Laissez vide pour utiliser tous les pays activés dans la boutique. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.

Avancé

Debug log : consigne les calculs de tarifs dans storage/logs/vfd_smsa_debug.log.php. Le fichier ne peut pas être lu depuis le web. Aucune adresse de client ni aucune clé n'est consignée. Les erreurs des tarifs en temps réel sont toujours consignées, même lorsque cette option est désactivée. Désactivez le journal lorsque vous avez terminé. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_smsa_debug.old.log.php et un nouveau journal est démarré.

Log : affiche la taille et les dernières entrées du journal de débogage. 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 SMSA Express et le journal de débogage. Lorsqu'elle est désactivée (par défaut), les réglages sont conservés pour une réinstallation. Les tarifs en cache sont toujours supprimés.

Import / Export

Export : cliquez sur Download JSON pour enregistrer les réglages dans un fichier JSON. Le passKey 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 passKey enregistré est conservé.

Fonctionnement au moment du paiement

Lorsqu'OpenCart affiche les modes de livraison, il demande à l'extension le prix SMSA Express. Si une Geo zone est définie (et que Ignore shipping zones est désactivé) et que l'adresse se trouve en dehors, SMSA Express 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 montant de la commande. L'extension vérifie ensuite les conditions : les pays de Ignore shipping zones (si activé), le poids du panier et le montant minimum de commande. 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 prix est de 0 et aucune requête n'est envoyée à SMSA.

Avec les tarifs en temps réel activés, l'extension envoie à SMSA la ville et le pays d'expédition, la ville et le pays du client, le type d'envoi, le poids du colis en kg et un montant de paiement à la livraison de 0. SMSA répond avec le tarif et sa devise. L'extension le convertit dans la devise par défaut de votre boutique et l'arrondit à ses décimales. Le prix est ensuite affiché dans la devise du client avec la taxe de la Tax class sélectionnée. Un tarif en temps réel n'est demandé qu'après que le client a saisi une adresse de livraison avec une ville.

Chaque tarif est mis en cache pendant une heure, afin que le même panier ne déclenche pas une nouvelle requête. Une requête échouée est mise en cache pendant 5 minutes. Après un délai d'attente ou une erreur serveur, SMSA n'est plus interrogé pendant 2 minutes. Après une clé rejetée, il n'est plus interrogé pendant 5 minutes. Ainsi, le paiement n'attend jamais un service défaillant à chaque actualisation. Le délai d'attente des requêtes est de 12 secondes.

Chaque fois que SMSA ne renvoie aucun tarif exploitable (pas de passKey, ville non encore saisie, clé invalide, délai d'attente, erreur, aucun service vers la ville ou devise inconnue), le tableau de prix est utilisé. Si le tableau et Price for countries not in the table ne donnent aucun prix, le mode est masqué. Le client ne voit jamais d'erreur. La raison est consignée dans le journal.

L'extension calcule uniquement le prix de la livraison. Elle ne crée pas d'envois SMSA, n'imprime pas d'étiquettes AWB, ne gère pas les retours et ne suit pas les colis. Le paiement à la livraison et ses frais ne sont pas inclus dans le tarif en temps réel. Il n'y a pas de sélecteur de point de vente SMSA : le mode est une livraison à domicile. L'extension n'ajoute rien aux commandes : la commande affiche le titre du mode et le coût de livraison comme pour tout autre mode de livraison OpenCart.

Dans OpenCart 4, le client clique sur Choose dans le bloc des modes de livraison de la page de paiement, puis choisit SMSA Express dans la fenêtre Shipping method options. Le mode fonctionne de la même façon que sur OpenCart 3.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox SMSA Express est le premier bloc de Extensions > Extensions > Shipping > VibeFox SMSA Express > Edit, au-dessus des réglages. Collez 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) 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: opencart-shipping-smsa-express 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é une place 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 sa place de domaine. Libérez la place dans votre compte vibefox.net.

Sans clé active, SMSA Express n'est pas affiché aux clients au moment du paiement et aucun tarif n'est calculé. Un 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é. Sur 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. 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. Le statut 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 le statut de la licence.

Dépannage

SMSA Express n'apparaît pas au moment du paiement : vérifiez que la licence est active et que Enable SMSA Express est activé. Contrôlez Geo zone (ou, si Ignore shipping zones est activé, Countries), les limites de poids et le Minimum order amount. Vérifiez que le pays ou * a un prix, ou que Price for countries not in the table est renseigné. Vérifiez que les produits ont Requires Shipping réglé sur Yes.

Les clients voient le prix du tableau au lieu du tarif SMSA : SMSA a besoin de la ville du client, donc tant qu'elle n'est pas saisie, le prix du tableau s'affiche. Le tableau est aussi utilisé lorsque SMSA ne répond pas, rejette la clé ou la ville, ou renvoie le tarif dans une devise sans taux de change. Consultez le champ Log sur la page de l'extension pour connaître la raison.

"Invalid Passkey" dans le journal : la clé n'est pas acceptée par le service web SMSA. Demandez à SMSA un passKey pour le service web.

La ville du client n'est pas acceptée : SMSA attend sa propre écriture des noms de villes. Vérifiez la ville de l'adresse de livraison et la Ship-from city.

Les réglages ne sont pas enregistrés et un message d'erreur apparaît : un champ numérique contient du texte ou une valeur négative, le taux de change est 0, le code de devise ne compte pas 3 lettres, ou Minimum weight (kg) est supérieur à Maximum weight (kg). Corrigez la valeur indiquée dans le message et cliquez à nouveau sur Save.

La taxe est facturée deux fois sur la livraison : votre grille ou les tarifs SMSA incluent peut-être déjà la TVA. Réglez Tax class sur No tax.

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page de l'extension. Cela vide le cache des tarifs SMSA.

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

Pour les développeurs : l'adresse du service web SMSA peut être remplacée par le réglage vfd_smsa_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 SMSA Express. La clé de licence et le statut de la licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable SMSA Express, 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 SMSA Express 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 et leur coût.

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

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