VibeFox SMSA Express for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les versions de PHP antérieures.

Grille tarifaire SMSA Express : les prix de la grille 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 une autre devise, convertissez-la d'abord.

passKey SMSA (pour les tarifs en temps réel uniquement) : les tarifs en temps réel utilisent le service web SMSA (SECOM, opération getShipCharges). SMSA délivre la passKey sur demande : demandez-la à votre responsable de compte SMSA ou écrivez à info@smsaexpress.com pour demander l'accès au service web SMSA en indiquant votre numéro de compte. La passKey peut être différente de la clé API du portail e-commerce 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

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 l'envoi terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox SMSA Express 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 de configuration et cliquez sur Activate (voir Clé de licence).

4. Saisissez vos prix SMSA Express dans la grille tarifaire et cliquez sur Save.

5. Facultatif : dans 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.

À l'installation, le module crée le transporteur SMSA Express avec le texte de délai de livraison SMSA Express courier. 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 SMSA Express > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Chaque enregistrement vide aussi le cache des tarifs SMSA. Une valeur qui n'est pas un nombre, un nombre négatif, un taux de change de 0, un code devise qui ne comporte pas 3 lettres, ou un Minimum weight supérieur au Maximum weight est refusé avec une erreur, et rien n'est enregistré tant que la valeur n'est pas corrigée.

Lorsque les tarifs en temps réel sont activés, des avertissements affichés au-dessus des réglages signalent une passKey, une ville d'expédition ou un taux de change manquant, ou une grille tarifaire vide. Un avertissement apparaît aussi si le module ne reconnaît pas l'unité de poids de la boutique (les poids des produits sont alors lus en kg). Définissez kg, g, lb ou oz dans International > Localization (Local units).

Général

Enable SMSA Express : active ou désactive le transporteur dans toutes les zones à la fois. C'est le même interrupteur que le statut du transporteur dans Shipping > Carriers.

Method title : le nom du transporteur affiché dans le panier et lors du paiement. Par défaut : SMSA Express. Obligatoire, jusqu'à 64 caractères.

Tax : la règle de taxe du transporteur, ou No tax. Choisissez No tax si vos prix (la grille et les tarifs SMSA) incluent déjà la taxe, par exemple la TVA saoudienne.

Tarifs en temps réel (API) (facultatif ; si SMSA ne renvoie aucun tarif, la grille tarifaire est utilisée)

Live charges : obtient le tarif de livraison auprès de SMSA Express. 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 », ce service n'accepte pas cette clé. Demandez à SMSA une 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. Laissez vide pour utiliser la ville de la boutique définie dans Shop Parameters > Contact > Stores.

Ship-from country : le pays d'où partent vos colis. Par défaut, c'est le pays de votre boutique.

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

Currency of SMSA charges : SMSA renvoie chaque tarif avec son code devise, généralement SAR (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 d'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 c'est la grille tarifaire qui s'applique. Le point et la virgule sont tous deux acceptés comme séparateur décimal.

Prix (votre grille tarifaire 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 et sur l'icône de corbeille pour en supprimer une. La ligne * Default (all other countries) s'applique aux pays qui n'ont pas de ligne propre. Chaque ligne comporte un prix de base et des colonnes de poids : XS jusqu'à 1 kg, S jusqu'à 2 kg, M jusqu'à 3 kg, L jusqu'à 5 kg et XL au-delà de 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. Les formats « 9.99 » et « 9,99 » sont tous deux acceptés.

Price for countries not in the table : utilisé lorsque la grille ne comporte aucune ligne pour le pays de destination (ni ligne *) ou lorsque la ligne n'a pas de prix pour ce poids. Laissez vide pour masquer le transporteur dans ce cas.

Price applies : le mode de calcul du prix.

Les poids des produits sont convertis de l'unité de poids de votre boutique en kilogrammes.

Conditions

Minimum weight : masque le transporteur lorsque le panier pèse moins, en kg. 0 signifie aucune limite.

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

Minimum order amount : n'affiche le transporteur que lorsque le sous-total du panier (après remises, avant taxes) atteint ce montant. Laissez vide pour l'afficher en permanence.

Free shipping from : le sous-total du panier (après remises, 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.

Disponibilité sans zones de livraison

En règle générale, le transporteur est proposé dans les zones qui lui sont affectées dans Shipping > Carriers.

Ignore shipping zones : propose SMSA Express pour les pays indiqués ci-dessous, quelle que soit la zone correspondante. Tant que cette option est activée, le transporteur est ajouté à toutes les zones, y compris celles créées ultérieurement. La désactiver supprime de nouveau 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 : enregistre les calculs de tarifs dans logs/vfd_smsa_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Aucune adresse client ni aucune clé n'est enregistrée. Les erreurs des tarifs en temps réel sont toujours enregistrées, même lorsque cette option est désactivée. Désactivez le journal une fois que vous avez terminé.

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 du module supprime les réglages SMSA Express, le transporteur et le journal. Lorsqu'elle est désactivée, tout est conservé pour une réinstallation. Les tarifs en cache sont toujours supprimés.

Fonctionnement lors du paiement

À l'étape de livraison, PrestaShop demande au module le prix SMSA Express. Seuls les produits physiques comptent : les produits virtuels n'ajoutent pas de poids et ne sont pas inclus dans le montant de la commande. Le module vérifie d'abord les conditions : les pays de Ignore shipping zones (si activé), le poids du panier et le montant minimum de commande. Si la livraison gratuite s'applique, le prix est de 0 et aucune requête n'est envoyée à SMSA.

Lorsque les tarifs en temps réel sont activés, le module envoie à SMSA votre ville et votre 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. Le module le convertit dans la devise par défaut de votre boutique, puis le prix est affiché dans la devise du panier du client. Un tarif en temps réel n'est demandé qu'une fois 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 pas sollicité de nouveau pendant 2 minutes. Après une clé rejetée, il n'est pas sollicité pendant 5 minutes. Ainsi, le paiement n'attend jamais un service défaillant à chaque actualisation. Le délai d'attente de la requête est de 12 secondes.

Lorsque SMSA ne renvoie aucun tarif exploitable (pas de passKey, pas encore de ville saisie, poids de produit manquants, clé non valide, délai d'attente, erreur, aucun service vers la ville ou devise inconnue), la grille tarifaire est utilisée. Si la grille et Price for countries not in the table ne donnent aucun prix, le transporteur est masqué. Le client ne voit jamais d'erreur. La raison est inscrite dans le journal.

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 le prix de la livraison. Il ne crée pas d'envois SMSA, n'imprime pas d'étiquettes AWB, ne traite 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'existe pas de sélecteur de point relais SMSA : le transporteur assure une livraison à domicile.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox SMSA Express est le premier bloc de Modules > Module Manager > VibeFox SMSA Express > 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-smsa-express 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 SMSA Express 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

SMSA Express n'apparaît pas lors du paiement : vérifiez que la licence est active et que Enable SMSA Express est activé. Dans Shipping > Carriers, vérifiez que le transporteur couvre la zone du pays du client et son groupe (ou que Ignore shipping zones est activé et que le pays est autorisé). Contrôlez 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 défini. Les produits peuvent aussi être limités à certains transporteurs dans la fiche produit.

Les clients voient le prix de la grille au lieu du tarif SMSA : SMSA a besoin de la ville du client ; tant qu'elle n'est pas saisie, le prix de la grille est affiché. La grille est aussi utilisée 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 de la page du module pour connaître la raison.

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

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

Les réglages ne sont pas enregistrés et une erreur s'affiche : un champ numérique contient du texte ou une valeur négative, le taux de change est 0, le code devise ne comporte pas 3 lettres, ou Minimum weight est supérieur à Maximum weight. Corrigez la valeur indiquée dans le message et cliquez de 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 sur No tax.

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

La page indique que le transporteur SMSA Express 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 SMSA Express et choisissez Uninstall. La clé de licence et le statut de la 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, ou une réinitialisation, rend au transporteur le statut qu'il avait auparavant.

SMSA Express est une marque déposée de son titulaire respectif. Ce module n'est ni affilié à SMSA Express ni approuvé par SMSA Express.