VibeFox SMSA Express for WooCommerce — Aide

Prérequis

WordPress : 5.8 ou ultérieur.

WooCommerce : 5.0 ou ultérieur, installé et activé. L'extension refuse de s'activer sans lui.

PHP : 8.0 ou ultérieur.

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 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 direct) : les tarifs en direct utilisent le service web SMSA (SECOM, opération getShipCharges). SMSA délivre le passKey sur demande : demandez-le à votre responsable de compte SMSA ou écrivez à info@smsaexpress.com en demandant l'accès au service web SMSA avec votre numéro de compte. Le passKey peut être différent 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 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_smsa_express dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox SMSA Express, 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. Saisissez vos prix SMSA Express dans la grille tarifaire.

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 de votre boutique n'est pas SAR, le taux de change.

7. Ajoutez VibeFox SMSA Express à une zone d'expédition dans WooCommerce > Settings > Shipping > Shipping zones (par exemple « Arabie saoudite »), ou activez Ignore shipping zones et choisissez les pays.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Shipping > VibeFox SMSA Express. 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 voient les clients pour cette zone. Laissez-le vide pour utiliser le Method title global.

Chaque fois que vous enregistrez les réglages, les tarifs SMSA en cache sont effacés. Lorsque les tarifs en direct sont activés, des avertissements au-dessus des réglages signalent un passKey, une ville d'expédition ou un taux de change manquant, ou une grille tarifaire vide.

Général

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

Method title : le nom de la méthode d'expédition affiché dans le panier et au moment du paiement. Une zone peut le remplacer. Par défaut : SMSA Express.

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

Live charges : obtient le tarif d'expédition auprès de SMSA Express. Par défaut : désactivé.

SMSA passKey : la clé du service web SMSA (SECOM). Si le journal affiche « Invalid Passkey », ce service n'accepte pas la clé. Demandez à SMSA un passKey pour le service web.

Ship-from city : la ville d'où partent vos colis, orthographiée comme le fait SMSA, par exemple Riyadh, Jeddah ou Dammam. Laissez-la vide pour utiliser la ville de la boutique définie dans WooCommerce > Settings > General.

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 (la valeur par défaut) correspond à la livraison standard. Ne le modifiez que si SMSA vous a donné un autre code.

Currency of SMSA charges : SMSA renvoie chaque tarif avec son code devise, en général SAR (par défaut). Un tarif dans une devise autre que celle-ci ou que la devise de votre boutique n'est pas utilisé.

Exchange rate : le prix d'1 unité de la devise SMSA dans la devise de votre boutique, par exemple 0.24. Inutile si les deux devises sont identiques. Sans ce taux, les tarifs dans une autre devise ne sont pas utilisés et la grille tarifaire 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 de votre boutique ; utilisée lorsque les tarifs en direct sont désactivés, et en solution de repli lorsque SMSA ne renvoie aucun tarif)

Price table : une ligne par pays de destination. Cliquez sur + Add country pour ajouter une ligne et sur la croix pour en supprimer une. La ligne * 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 à 0 utilise le prix de base. Un prix de base de 0 signifie livraison gratuite. Les lignes sans aucun prix sont supprimées à l'enregistrement. « 9.99 » et « 9,99 » sont tous deux acceptés.

Price for countries not in the table : utilisé lorsque la grille 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-le vide pour masquer la méthode 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 (kg) : masque la méthode lorsque le panier pèse moins. 0 signifie sans limite.

Maximum weight (kg) : masque la méthode lorsque le panier pèse plus. Par défaut : 30. 0 signifie sans limite.

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

Free shipping from : le sous-total du panier (après remises, avant taxes) à partir duquel la livraison SMSA Express est gratuite. La livraison gratuite n'est proposée que lorsque la méthode a un prix pour la destination : un tarif SMSA, une ligne de la grille ou le prix des pays absents de la grille. Si la grille a un prix, aucune requête n'est envoyée à SMSA. Laissez-le vide pour ne jamais proposer la livraison gratuite.

Excluded shipping classes : masque la méthode lorsque le panier contient un produit appartenant à l'une de ces classes d'expédition WooCommerce.

Tax status : Taxable ajoute la taxe WooCommerce au coût de l'expédition, None ne l'ajoute pas. Choisissez None si vos prix (la grille et les tarifs SMSA) incluent déjà la taxe, par exemple la TVA saoudienne.

Disponibilité sans zones d'expédition

Ignore shipping zones : propose SMSA Express pour les pays indiqués ci-dessous, même si la méthode n'est ajoutée à aucune zone d'expédition.

Countries : les pays de destination pour ce mode. Laissez-le vide pour utiliser tous les pays vers lesquels vous expédiez. 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 : journalise chaque calcul de tarif dans WooCommerce > Status > Logs, source vfd_smsa_express. Aucune adresse de client ni aucune clé n'est journalisée. Les erreurs des tarifs en direct sont toujours journalisées, même lorsque cette option est désactivée. Désactivez le journal une fois vos tests terminés.

Remove data on uninstall : lorsque l'option est activée, supprimer l'extension efface tous les réglages SMSA Express et les méthodes de zone. Désactiver l'extension ne supprime jamais rien.

Fonctionnement au moment du paiement

Lorsque le client saisit une adresse de livraison, WooCommerce demande à l'extension un prix. L'extension vérifie d'abord les conditions : pays de livraison, poids du panier, montant minimal de commande et classes d'expédition exclues. Si la livraison gratuite s'applique et que la destination a un prix, la méthode s'affiche avec un prix de 0.

Lorsque les tarifs en direct sont activés, l'extension 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. L'extension le convertit dans la devise de votre boutique et l'affiche. Un tarif en direct n'est demandé qu'après que le client a saisi 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 de la requête est de 12 secondes.

Lorsque SMSA ne renvoie aucun tarif exploitable (pas de passKey, aucune ville saisie pour l'instant, poids de produit manquants, clé invalide, 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, la méthode est masquée. Le client ne voit jamais d'erreur. La raison est consignée dans le journal.

La méthode fonctionne avec le paiement classique et avec les blocs Panier et Paiement. Elle est compatible avec le stockage haute performance des commandes de WooCommerce (HPOS). Une traduction en arabe est incluse.

L'extension ne calcule que le prix de l'expédition. 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 direct. Il n'existe pas de sélecteur de point relais SMSA : la méthode est une livraison à domicile.

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 SMSA Express. 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, SMSA Express n'est pas affiché aux clients au moment du paiement. Les gestionnaires connectés de la boutique le voient toujours, avec la mention (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 l'assistance nécessitent un renouvellement. Le statut est vérifié automatiquement en arrière-plan.

Dépannage

SMSA Express n'apparaît pas au moment du 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 order amount et Excluded shipping classes. Vérifiez que le pays ou * a un prix, ou que Price for countries not in the table est défini.

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 s'affiche. La grille est aussi utilisée lorsque SMSA ne répond pas, refuse la clé ou la ville, ou renvoie le tarif dans une devise sans taux de change. Ouvrez WooCommerce > Status > Logs, source vfd_smsa_express, 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 orthographe des villes. Les développeurs peuvent adapter la requête, par exemple le nom de la ville, avec le filtre vfd_smsa_express_live_request_fields.

La taxe est facturée deux fois sur l'expédition : votre grille ou les tarifs SMSA incluent peut-être déjà la TVA. Réglez Tax status sur None.

Les tarifs semblent périmés après une modification : enregistrez la page des réglages. Cela efface les tarifs SMSA en cache.

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 et 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

Désactiver 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 sont toujours supprimés. Les réglages, les méthodes de zone et les tarifs en cache 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.

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