VibeFox SF 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 anciennes versions de PHP.

Compte SF Express (uniquement pour les tarifs en temps réel) : les tarifs en temps réel utilisent la plateforme ouverte FengQiao de SF Express (open.sf-express.com). Vous avez besoin d'un compte mensuel SF Express et d'un compte développeur FengQiao. Inscrivez-vous, créez une application, ajoutez-y l'API « Delivery time standard and price query » (EXP_RECE_QUERY_DELIVERTM) et copiez le code client et le checkword. Les checkwords de sandbox et de production sont différents. Si vous utilisez uniquement la grille tarifaire, vous n'avez pas besoin de compte SF Express.

Provinces chinoises (uniquement pour les tarifs en temps réel) : le tarif en temps réel nécessite la province de l'adresse de livraison. PrestaShop n'a pas de provinces chinoises par défaut. Le module peut les ajouter pour vous (voir Chinese provinces ci-dessous).

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 le téléversement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox SF Express dans la liste des modules et cliquez sur Configure.

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

4. Renseignez la grille tarifaire et/ou le coût de repli, puis cliquez sur Save.

5. Pour les tarifs en temps réel en Chine continentale, saisissez le code client et le checkword, la province et la ville d'expédition (ou configurez une adresse de boutique en Chine) et, si la devise de votre boutique n'est pas le CNY, le taux de conversion. Cliquez sur Add Chinese provinces si la page vous le demande. Testez d'abord avec Sandbox et des identifiants sandbox.

À l'installation, le module crée le transporteur SF Express avec le texte de délai de livraison Courier delivery. 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 ici : le prix provient toujours du module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox SF Express > Configure. Ils s'appliquent à toutes les zones du transporteur. Chaque section a son propre bouton Save, qui enregistre toute la page. Chaque enregistrement efface aussi les tarifs SF Express en cache.

Lors de l'enregistrement, le module vérifie les chiffres. Une valeur qui n'est pas un nombre, un montant ou un poids négatif, un taux de conversion de 0, un Min weight supérieur à Max weight ou un tarif incorrect dans la grille tarifaire est refusé avec un message, et rien n'est enregistré tant que vous ne l'avez pas corrigé. Des avertissements au-dessus des réglages vous indiquent quand les tarifs en temps réel sont partiellement configurés (les réglages manquants sont listés), quand le taux de conversion manque, quand les adresses chinoises n'ont pas de champ de province, ou quand l'unité de poids ou de dimension de votre boutique n'est pas connue du module. Les unités se règlent dans International > Localization (Local units).

Général

Enable SF Express : active ou désactive le transporteur. 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 : SF Express. Obligatoire, 64 caractères maximum.

Tax : la règle de taxe du transporteur, ou No tax. Avec une règle de taxe, la taxe de livraison de votre boutique s'ajoute au coût. Choisissez No tax si le tarif SF Express inclut déjà tout ce que vous voulez facturer.

API FengQiao de SF Express (tarifs en temps réel) (facultatif, pour les adresses de livraison en Chine continentale)

Customer code (partnerID) : le code client (顾客编码) de votre application FengQiao. Le vider efface aussi le checkword enregistré, ce qui vous permet de supprimer les identifiants.

Checkword : le checkword (校验码) du même environnement. Il ne sert qu'à signer les requêtes et n'est jamais envoyé ni journalisé. 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.

Sandbox : utilise le sandbox FengQiao (sfapi-sbox.sf-express.com) pour tester avec des identifiants sandbox. Les tarifs sandbox ne sont pas réels. Désactivez-le dans une boutique en production. Par défaut : désactivé.

SF Express product : le produit SF Express dont le tarif est affiché.

Sender province : la province d'où partent les colis. Laissez vide pour utiliser la province de l'adresse de la boutique dans Shop Parameters > Contact > Stores, lorsque la boutique est en Chine.

Sender city : le nom standard de la ville chinoise, par exemple 深圳市. Laissez vide pour utiliser la ville de la boutique, lorsque la boutique est en Chine.

Currency conversion rate : les tarifs SF Express sont en CNY (yuan). Si la devise par défaut de votre boutique n'est pas le CNY, indiquez combien d'unités de votre devise vaut un CNY (1 CNY = ? unités). Sans lui, les tarifs en temps réel ne sont pas utilisés. Si la devise de votre boutique est le CNY, les tarifs sont utilisés tels quels. Le point et la virgule sont tous deux acceptés comme séparateur décimal.

Chinese provinces : indique si les adresses chinoises peuvent avoir une province. Sinon, cliquez sur Add Chinese provinces. Le bouton ajoute les 32 provinces, régions autonomes et municipalités comme états de Chine (codes ISO comme GD et BJ, noms comme « Guangdong / 广东 »), active « Contains states » pour la Chine et ajoute le champ d'état au formulaire d'adresse chinois. Les provinces déjà existantes ne sont pas ajoutées à nouveau. Rien n'est modifié sans ce clic.

Grille tarifaire et repli (utilisée pour Hong Kong, Macao, Taïwan et les autres pays, lorsque les tarifs en temps réel ne sont pas configurés ou lorsque SF Express ne donne aucun tarif ; les tarifs sont dans la devise par défaut de votre boutique, hors taxes)

Country prices : un tableau avec un tarif de base par pays. Cliquez sur Add country pour ajouter une ligne et sur l'icône de corbeille pour en supprimer une. La ligne * All other countries s'applique à tous les pays sans ligne propre. Un tarif de tranche de poids supérieur à 0 remplace le tarif de base pour les colis de cette tranche : XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg et XL >5 kg. Un tarif de base de 0 signifie livraison gratuite. Un tarif de base vide signifie qu'il n'y a pas de tarif pour ce pays et que le coût de repli est utilisé. « 9.99 » et « 9,99 » sont tous deux acceptés. Une ligne sans aucun tarif n'est pas enregistrée.

Fallback cost : utilisé lorsque ni SF Express ni le tableau ne donnent de tarif. Laissez vide pour masquer le transporteur dans ce cas.

Table / fallback price is : la manière dont les tarifs du tableau et de repli sont facturés.

Les tarifs en temps réel de SF Express sont toujours calculés pour la commande entière.

Conditions

Free shipping from : le sous-total du panier (après remises, avant taxes) à partir duquel la livraison est gratuite. Laissez vide pour ne jamais proposer la livraison gratuite. La livraison gratuite est vérifiée avant toute recherche de tarif : à partir de ce montant, le transporteur est proposé gratuitement pour toutes les destinations où il est disponible, même un pays sans ligne dans le tableau ou sans Fallback cost.

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

Min weight : le poids minimum du panier en kg. Les poids des produits sont convertis depuis l'unité de poids de votre boutique. 0 signifie aucune limite.

Max weight : le poids maximum du panier en kg. Par défaut : 50. 0 ou vide signifie aucune limite.

Disponibilité sans zones de livraison

Ignore shipping zones : propose SF Express pour les pays ci-dessous, quelle que soit la zone correspondante. À l'enregistrement, le transporteur est ajouté à toutes les zones, ainsi qu'aux zones créées plus tard. Désactiver l'option supprime à nouveau les zones ajoutées. Lorsqu'elle est désactivée, le transporteur n'apparaît que dans ses propres zones.

Countries : les pays de destination pour ce mode. Laissez vide pour autoriser tous les pays actifs. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.

Avancé

Debug log : écrit les calculs de tarifs dans logs/vfd_sfex_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. Ni le checkword ni les adresses des clients ne sont écrits.

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

Remove data on uninstall : si activé, la désinstallation du module supprime les réglages, le transporteur, les tarifs en cache et les journaux. Si désactivé, tout est conservé pour une réinstallation.

Fonctionnement lors du paiement

À l'étape de livraison, PrestaShop demande au module le tarif SF Express. Seuls les produits physiques comptent : les produits virtuels n'ajoutent aucun 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 le sous-total atteint Free shipping from, le tarif est de 0 et aucune requête n'est envoyée à SF Express.

Pour une adresse de livraison en Chine continentale, avec le code client et le checkword renseignés, le module envoie à SF Express la province et la ville d'expédition, la province et la ville du client, le poids du panier et le volume du panier (à partir des produits ayant les trois dimensions). La requête est signée avec votre checkword. SF Express renvoie les tarifs en CNY, et le module convertit celui choisi dans la devise par défaut de votre boutique. Le tarif est ensuite affiché dans la devise du panier du client.

SF Express reconnaît les adresses grâce aux noms chinois standard. La province du client provient du champ d'état de l'adresse. La ville doit être écrite en chinois, par exemple 广州市. Pour Beijing, Shanghai, Tianjin et Chongqing, la ville est renseignée automatiquement. Une ville écrite en lettres latines, comme « Guangzhou », reçoit le tarif du tableau.

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 10 minutes, pour que le paiement n'attende pas SF Express à chaque actualisation. Le délai d'attente HTTP est de 10 secondes.

S'il n'y a pas de tarif en temps réel, le tarif provient de la grille tarifaire, puis du Fallback cost. Si aucun ne s'applique, le transporteur est masqué. Le client ne voit jamais d'erreur. L'erreur est écrite 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 les tarifs. Il ne crée ni lettres de transport ni étiquettes, ne crée pas de commandes dans SF Express, ne réserve pas d'enlèvements, n'annule ni ne suit d'envois. Créez et suivez vos envois dans votre compte SF Express comme d'habitude. Les clients ne peuvent pas choisir un point relais ou une consigne SF. SF Express est utilisé comme un service de livraison de porte à porte. Les tarifs en temps réel existent uniquement pour les adresses de livraison en Chine continentale. Le module a été développé à partir de la documentation FengQiao et de réponses simulées : vérifiez donc les tarifs avec votre compte SF Express (d'abord en sandbox) avant la mise en production.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox SF Express est le premier bloc de Modules > Module Manager > VibeFox SF 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 active et votre domaine) et 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-sf-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 : celui 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 l'emplacement dans votre compte vibefox.net.

Sans clé active, le transporteur SF Express n'est pas affiché aux clients lors du paiement et aucun tarif n'est calculé. La vitrine de PrestaShop ne sait pas que vous êtes connecté au back-office : le transporteur est donc masqué pour vous aussi. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au paiement. Un rappel apparaît dans Modules > Module Manager, dans l'onglet Alerts. Les commandes existantes ne sont pas affectées.

Lorsqu'une licence expire, le module continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement pendant que vous travaillez 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. Désinstaller ou réinitialiser le module supprime toujours la clé de licence et le statut de licence.

Dépannage

SF Express n'apparaît pas lors du paiement : vérifiez que la licence est active et que Enable SF Express 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. Vérifiez que le tableau ou le Fallback cost a un tarif pour le pays. Les produits peuvent aussi être limités à certains transporteurs sur la page produit.

Le tarif provient du tableau, pas de SF Express : les tarifs en temps réel nécessitent le code client et le checkword, une province et une ville d'expédition, une adresse de livraison en Chine continentale avec une province et un nom de ville chinois, et (pour les boutiques qui ne sont pas en CNY) le taux de conversion. Lisez les avertissements en haut de la page du module, puis activez Debug log, rechargez le paiement et consultez le champ Log pour voir la raison. Une requête échouée est relancée après 10 minutes.

Le formulaire d'adresse pour la Chine n'a pas de province : cliquez sur Add Chinese provinces dans la section API de la page du module.

Erreur A1006 dans le journal : signature invalide. Le checkword est erroné ou appartient à l'autre environnement. Vérifiez le réglage Sandbox.

Erreur A1004 dans le journal : l'API de requête de tarifs n'est pas ajoutée à votre application FengQiao.

Hong Kong : fonctionne avec la grille tarifaire et le coût de repli. La requête de tarifs FengQiao concerne uniquement les adresses de Chine continentale.

Les tarifs semblent obsolètes après une modification : cliquez sur Save sur la page du module. Cela efface les tarifs SF Express en cache.

La page indique que le transporteur SF Express est introuvable : le transporteur a été supprimé dans Shipping > Carriers. Réinitialisez le module dans Modules > Module Manager pour le recréer.

Pour les développeurs : le hook actionVfdSfExpressQuoteRequest modifie la requête de tarif, par exemple pour utiliser un autre code produit. actionVfdSfExpressApiUrl modifie l'URL de la passerelle.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox SF Express et choisissez Uninstall. La clé de licence et le statut de 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) ainsi que les réglages et le journal. S'il est désactivé, le transporteur est seulement désactivé et tous les réglages sont conservés. Réinstaller le module, ou faire un Reset, rend au transporteur le statut qu'il avait auparavant. Les commandes existantes conservent leurs lignes de livraison.

SF Express est une marque de commerce de son propriétaire respectif. Ce module n'est ni affilié à SF Express ni approuvé par SF Express.