VibeFox SF Express for WooCommerce — Aide

Prérequis

WordPress: 5.8 ou ultérieur.

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

PHP: 8.0 ou ultérieur.

Compte SF Express (pour les tarifs en temps réel uniquement) : 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), puis 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.

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_sf_express dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox SF Express, ou cliquez sur Settings sous le nom de l'extension dans la page Plugins.

4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page, puis cliquez sur Activate.

5. Renseignez la grille tarifaire et/ou le coût de repli.

6. 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 renseignez une adresse de boutique en Chine) et, si la devise de votre boutique n'est pas le CNY, le taux de conversion. Testez d'abord avec Sandbox et les identifiants de sandbox.

7. Ajoutez VibeFox SF Express à une zone d'expédition dans WooCommerce > Settings > Shipping > Shipping zones, ou activez Ignore shipping zones et choisissez les pays.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Shipping > VibeFox SF 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 général.

Chaque fois que vous enregistrez les réglages, les tarifs SF Express mis en cache sont effacés. Si les tarifs en temps réel sont configurés partiellement, un avertissement au-dessus des réglages indique les réglages manquants ou le taux de conversion manquant.

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 de livraison affiché dans le panier et au paiement. Une zone peut le remplacer. Par défaut : SF Express.

Tax status: Taxable ajoute la taxe de livraison de votre boutique au coût, None ne l'ajoute pas. Choisissez None 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.

Checkword: le checkword (校验码) du même environnement. Il sert uniquement à signer les requêtes et n'est jamais envoyé ni journalisé.

Sandbox: utilisez le sandbox FengQiao pour tester avec des identifiants de sandbox. Les tarifs du sandbox ne sont pas réels. Désactivez-le dans une boutique en production. Par défaut : off.

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

Sender province: la province d'où partent les colis. Laissez-le vide pour utiliser la province de l'adresse de la boutique dans WooCommerce > Settings > General, lorsque la boutique se trouve en Chine.

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

Currency conversion rate: les tarifs SF Express sont en CNY (yuan). Si la devise de votre boutique n'est pas le CNY, indiquez combien d'unités de la devise de votre boutique vaut un CNY. Sans ce taux, 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.

Grille tarifaire et coût de repli (utilisés pour Hong Kong, Macao, Taïwan et les autres pays, lorsque les tarifs en temps réel ne sont pas configurés ou que SF Express ne renvoie aucun tarif ; les tarifs sont dans la devise de votre boutique)

Country prices: un tableau avec un tarif de base par pays. La ligne * Any other country s'applique à tous les pays qui n'ont pas leur propre ligne. Un tarif de tranche de poids supérieur à 0 remplace le tarif de base pour les colis de cette tranche : ≤ 1 kg, ≤ 2 kg, ≤ 3 kg, ≤ 5 kg et > 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 le coût de repli est utilisé.

Fallback cost: utilisé lorsque ni SF Express ni le tableau ne fournissent de tarif. Laissez-le vide pour masquer la méthode dans ce cas.

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

Les tarifs SF Express en temps réel s'appliquent toujours à la commande entière.

Conditions

Free shipping from: le sous-total du panier à partir duquel la livraison est gratuite. La livraison gratuite n'est proposée que là où la méthode a un tarif pour la destination : un tarif en temps réel, une ligne de la grille ou le Fallback cost. Laissez-le vide pour ne jamais proposer la livraison gratuite.

Minimum subtotal: n'affiche la méthode que lorsque le sous-total du panier atteint ce montant. Laissez-le vide pour l'afficher toujours.

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

Max weight (kg): le poids maximum du panier en kg. Par défaut : 50. 0 signifie sans limite.

Excluded shipping classes: masque la méthode si le panier contient des produits de ces classes d'expédition WooCommerce.

Disponibilité sans zones d'expédition

Ignore shipping zones: propose la méthode pour les pays indiqués ci-dessous, même si elle n'est pas ajoutée à une zone. Lorsque l'option est désactivée, la méthode n'apparaît que dans les zones d'expédition auxquelles elle a été ajoutée.

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é.

Avancé

Debug log: écrit les calculs de tarifs dans le journal WooCommerce : WooCommerce > Status > Logs, source vfd-sf-express. Les erreurs de l'API sont toujours journalisées, même lorsque cette option est désactivée. Aucun checkword ni aucune adresse de client n'est écrit.

Remove data on uninstall: lorsque l'option est activée, la suppression de l'extension efface ses réglages, ses méthodes dans les zones d'expédition et ses caches. La désactivation de l'extension ne supprime jamais rien.

Fonctionnement au paiement

Lorsque le client saisit une adresse de livraison, WooCommerce demande un tarif à l'extension. L'extension vérifie d'abord les conditions : pays de livraison, poids du panier, sous-total minimum et classes d'expédition exclues. Si la livraison gratuite s'applique et que la grille tarifaire ou le Fallback cost a un tarif pour la destination, la méthode s'affiche avec un tarif de 0 et aucune requête n'est envoyée à SF Express. Sinon, l'extension demande d'abord à SF Express un tarif en temps réel, et n'affiche la méthode gratuite que si un tarif est renvoyé.

Pour une adresse de livraison en Chine continentale, lorsque le code client et le checkword sont renseignés, l'extension 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 dont les trois dimensions sont renseignées). La requête est signée avec votre checkword. SF Express renvoie les tarifs en CNY, et l'extension convertit celui qui a été choisi dans la devise de votre boutique.

SF Express reconnaît les adresses à partir des noms chinois standard. La province du client provient du champ région du paiement. La ville doit être écrite en chinois, par exemple 广州市. Pour Pékin, Shanghai, Tianjin et Chongqing, la ville est renseignée automatiquement. Une ville écrite en lettres latines, comme « Guangzhou », reçoit le tarif de la grille.

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 des deux ne s'applique, la méthode est masquée. Le client ne voit jamais d'erreur. L'erreur est écrite dans le journal.

La méthode fonctionne sur le paiement classique ainsi que sur les blocs Panier et Paiement. Elle est compatible avec WooCommerce High-Performance Order Storage (HPOS). Des traductions en anglais et en chinois simplifié sont incluses.

L'extension calcule uniquement les tarifs. Elle 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 et 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 coursier de porte à porte. Les tarifs en temps réel n'existent que pour les adresses de livraison en Chine continentale. L'extension a été développée à 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

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 SF Express. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche l'état, par exemple la date jusqu'à laquelle la licence est active, et votre domaine. Utilisez Check now pour vérifier à nouveau l'état, 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 l'emplacement dans votre compte vibefox.net.

Sans clé active, SF Express n'est pas affiché aux clients au paiement. Les gestionnaires de la boutique connectés 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. L'état est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

SF Express n'apparaît pas au 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é). Vérifiez les limites de poids, le Minimum subtotal et les Excluded shipping classes. Vérifiez que la grille ou le Fallback cost ont un tarif pour le pays.

Le tarif provient de la grille, et non 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. Ouvrez WooCommerce > Status > Logs, source vfd-sf-express, pour voir la raison. Une requête échouée est relancée au bout de 10 minutes.

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

Erreur A1004 dans le journal: l'API d'interrogation des tarifs n'est pas ajoutée à votre application FengQiao.

Hong Kong: fonctionne avec la grille tarifaire et le coût de repli. L'interrogation des tarifs FengQiao ne concerne que les adresses de Chine continentale.

Les tarifs semblent obsolètes après une modification : enregistrez la page des réglages. Cela efface les tarifs SF Express mis en cache.

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

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 état connu.

Désinstallation

La désactivation de 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 l'état de licence de cette extension sont toujours supprimés. Les réglages, les méthodes de zone et les tarifs mis 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 de livraison.

SF Express est une marque de commerce de son propriétaire respectif. Cette extension n'est ni affiliée à SF Express ni approuvée par elle.