VibeFox SF Express for OpenCart — Aide

Prérequis

OpenCart : 3.0.x (testé sur 3.0.5.0) ou 4.0.2 et ultérieur (testé sur 4.1.0.3).

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) et copiez le code client ainsi que le checkword. Les checkwords sandbox et production sont différents. Si vous n'utilisez que la grille tarifaire, vous n'avez pas besoin de compte SF Express.

Provinces chinoises (pour les tarifs en temps réel uniquement) : le tarif en temps réel nécessite la province de l'adresse de livraison, c'est-à-dire la zone OpenCart (Region / State) de l'adresse. OpenCart contient les zones de Chine, mais le Tibet manque. L'extension peut l'ajouter pour vous (voir Chinese provinces ci-dessous).

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un domaine.

Installation

Le téléchargement est un seul 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_sf_express-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_sf_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_sf_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 du paquet dans le dossier racine de votre boutique.

2. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox SF Express et cliquez sur Install (le bouton vert +).

3. Cliquez sur Edit (le bouton en forme de crayon) pour ouvrir la page des 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. 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 et, si la devise de votre boutique n'est pas le CNY, le taux de conversion de devise. Cliquez sur Add Chinese provinces si la page le demande. Testez d'abord avec Sandbox et des identifiants sandbox.

7. Activez Enable SF Express et cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_sf_express.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 prend le code de l'extension dans le 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 SF 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 des réglages et ses champs sont les mêmes dans les deux versions.

Après l'installation, la méthode reste désactivée tant que vous n'avez pas activé Enable SF Express et enregistré. Si vous réinstallez l'extension après une désinstallation, les réglages SF Express que vous avez conservés sont de nouveau utilisés.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Shipping > VibeFox SF Express > Edit. Les sections sont listées à gauche. Elles s'appliquent à toutes les zones géographiques. Un bouton Save en bas enregistre toute la page sans la recharger. Chaque enregistrement efface aussi les tarifs SF Express en cache. Seuls les administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages.

Lors de l'enregistrement, l'extension vérifie les valeurs. Un titre de méthode vide, de plus de 64 caractères ou contenant < > ; = # { }, une valeur qui n'est pas un nombre, un montant ou un poids négatif, un taux de conversion de devise égal à 0, un Min weight (kg) supérieur à Max weight (kg), un tarif erroné dans la grille tarifaire ou un ordre de tri qui n'est pas un nombre entier sont refusés avec un message, et rien n'est enregistré tant que vous ne les avez pas corrigés. Les avertissements affichés au-dessus des réglages indiquent quand les tarifs en temps réel sont partiellement configurés (les réglages manquants sont listés), quand le taux de conversion de devise manque, quand la boutique ne contient aucune zone de Chine, ou quand la boutique n'a pas d'unité de poids en kg ou de longueur en cm et que son unité par défaut n'est pas reconnue par l'extension.

Général

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

Method title : le nom de la méthode affiché dans le panier et au moment du paiement. Par défaut : SF Express. Obligatoire, 64 caractères maximum.

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

Sort order : la position de SF Express parmi les méthodes de livraison au moment du paiement. Un nombre entier.

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 sert uniquement à 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 les tests 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ù les colis sont expédiés, par exemple Guangdong / 广东. La première option utilise la région de votre boutique (System > Settings > Store > Local) lorsque la boutique se trouve en Chine. Elle affiche alors Same as the store region avec le nom de la province ; sinon, — Select —.

Sender city : le nom standard en chinois de la ville, par exemple 深圳市. Obligatoire pour les tarifs en temps réel : l'adresse de la boutique dans OpenCart est un texte libre, la ville n'en est donc jamais reprise.

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, saisissez combien d'unités de votre devise vaut un CNY (1 CNY = ? unités), par exemple 0.13. Sans ce taux, les tarifs en temps réel ne sont pas utilisés. Si la devise de votre boutique est le CNY, le champ indique qu'il n'est pas nécessaire et 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 combien des 32 provinces, régions autonomes et municipalités de SF Express sont des zones de Chine dans OpenCart, et lesquelles manquent. Les adresses situées dans une province manquante reçoivent le tarif de la grille. Cliquez sur Add Chinese provinces pour n'ajouter que les zones manquantes en tant que zones de Chine (code ISO, nom tel que "Tibet / 西藏"). Les zones existantes ne sont pas modifiées. Rien ne change sans ce clic. Les zones ajoutées ainsi restent dans la boutique après une désinstallation.

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 renvoie aucun tarif ; tarifs 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 le bouton de suppression pour en retirer une. La ligne * All other countries 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 : XS jusqu'à 1 kg, S jusqu'à 2 kg, M jusqu'à 3 kg, L jusqu'à 5 kg et XL au-delà de 5 kg. Un tarif Base de 0 signifie livraison gratuite. Un tarif de base vide signifie qu'il n'existe pas de tarif pour ce pays et que le coût de repli est utilisé. "9.99" comme "9,99" sont acceptés. Une ligne sans aucun tarif n'est pas enregistrée.

Fallback cost : utilisé lorsque ni SF Express ni la grille 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 grille et de repli sont facturés.

Les tarifs SF Express en temps réel portent toujours sur la commande entière.

Conditions

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

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 à partir de leur classe de poids. 0 signifie sans limite.

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

Geo zone : proposer SF Express uniquement pour les adresses de cette zone géographique. All zones (par défaut) signifie sans limite. Les zones géographiques se gèrent dans System > Localisation > Geo Zones. Elle n'est pas vérifiée lorsque Ignore shipping zones est activé.

Disponibilité sans zones de livraison

Ignore shipping zones : proposer SF 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 autoriser tous les pays activés. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.

Avancé

Debug log : écrit les calculs de tarifs dans storage/logs/vfd_sfex_debug.log.php. Le fichier ne peut pas être lu depuis le web. Les erreurs de l'API sont toujours journalisées, même lorsque cette option est désactivée. Aucun checkword ni adresse de client n'est écrit. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_sfex_debug.old.log.php et un nouveau journal est démarré.

Log : affiche la taille et les dernières entrées du journal. 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 et le journal. 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, sans le checkword.

Import : collez un JSON exporté précédemment et cliquez sur Import pour restaurer les réglages. Les valeurs sont vérifiées comme lors d'un enregistrement normal. Le checkword enregistré est conservé.

Fonctionnement au moment du paiement

Lorsque OpenCart affiche les méthodes de livraison, il demande à l'extension le tarif SF Express. Si une Geo zone est définie et que l'adresse se trouve en dehors, SF Express n'est pas proposé (sauf si Ignore shipping zones est activé). Seuls les produits dont Requires Shipping est réglé sur Yes comptent : les autres n'ajoutent aucun poids et ne sont pas inclus dans le sous-total. Le sous-total correspond au prix de ces produits après réduction du coupon et avant taxes. Les cartes-cadeaux, les points de fidélité et les avoirs de la boutique ne sont pas pris en compte. L'extension vérifie ensuite 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 un code client et un checkword renseignés, l'extension envoie à SF Express votre province et votre ville d'expédition, la province et la ville du client, le poids du panier (au moins 0,1 kg) et le volume du panier (à partir des produits ayant leurs trois dimensions). La requête est signée avec votre checkword. SF Express renvoie les tarifs en CNY ; l'extension convertit celui qui a été choisi dans la devise par défaut de votre boutique et l'arrondit selon ses décimales. Le tarif est ensuite affiché dans la devise du client, avec la taxe de la Tax class sélectionnée.

SF Express reconnaît les adresses grâce aux noms chinois standard. La province du client provient de la zone Region / State de l'adresse, identifiée par son nom. La zone "Hong Kong" n'est pas une province de Chine continentale et reçoit le tarif de la grille. 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.

En l'absence de tarif en temps réel, le tarif provient de la grille tarifaire, puis du Fallback cost. Si aucun ne s'applique, la méthode est masquée. Le client ne voit jamais d'erreur. L'erreur est écrite dans le journal.

L'extension ne calcule que des 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 de service ou une consigne SF. SF Express est utilisé comme service de livraison à domicile. 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 : confirmez donc les tarifs avec votre compte SF Express (d'abord en sandbox) avant la mise en production.

Sur OpenCart 4, le client clique sur Choose dans le bloc des méthodes de livraison de la page de paiement et choisit SF Express dans la fenêtre Shipping method options, où le titre de la méthode est affiché avec le prix. La méthode 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 SF Express est le premier bloc de Extensions > Extensions > Shipping > VibeFox SF Express > Edit, 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) 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 se trouvent la ligne Product: opencart-shipping-sf-express et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les 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é un emplacement 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 domaine : l'adresse de la boutique issue de la configuration d'OpenCart. 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, la méthode de livraison SF Express n'est pas affichée aux clients au moment du paiement, et aucun tarif n'est calculé. Un utilisateur administrateur connecté à l'administration dans le même navigateur voit toujours la méthode dans la boutique, marquée (unlicensed — visible to admins only), ce qui vous permet de configurer et de 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 administrateur ; sans clé active, la méthode est donc masquée pour tout le monde. Après avoir ouvert une fois la page Edit, 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 l'assistance nécessitent un renouvellement. Le statut est vérifié automatiquement à l'ouverture du Dashboard ou de la page Edit de l'administration : 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

SF Express n'apparaît pas au moment du paiement : vérifiez que la licence est active et que Enable SF Express est activé. Contrôlez Geo zone, ou activez Ignore shipping zones et contrôlez Countries. Vérifiez les limites de poids et Minimum subtotal. Vérifiez que la grille ou le Fallback cost ont un tarif pour le pays. Vérifiez que les produits ont Requires Shipping réglé sur Yes.

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 dont la devise n'est pas le CNY) le taux de conversion de devise. Lisez les avertissements en haut de la page de l'extension, puis activez le Debug log, rechargez le paiement et consultez le champ Log pour voir la raison. Une requête échouée est réessayée après 10 minutes.

Le journal affiche une erreur de signature : le checkword est erroné ou appartient à l'autre environnement. Vérifiez le réglage Sandbox. Si SF Express indique que l'API n'est pas autorisée, ajoutez l'API de requête de tarifs à votre application FengQiao.

Les adresses au Tibet reçoivent le tarif de la grille : cliquez sur Add Chinese provinces dans la section API de la page de l'extension.

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

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

La page affiche "Warning: You do not have permission to modify VibeFox SF Express!" : votre groupe d'utilisateurs administrateurs ne peut probablement que consulter les réglages. Accordez au groupe l'autorisation de modification pour extension/shipping/vfd_sf_express (OpenCart 3) ou extension/vfd_sf_express/shipping/vfd_sf_express (OpenCart 4) dans System > Users > User Groups.

Pour les développeurs : les événements OpenCart vfd_sf_express/quote_request et vfd_sf_express/api_url permettent à une autre extension de modifier la requête de tarif (par exemple vers un autre code produit) et l'URL de la passerelle.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox SF Express. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable SF Express, Sort order, Tax class et Geo zone. Les tarifs en cache sont toujours supprimés. Si Remove data on uninstall est activé, les autres réglages et le journal sont également supprimés. Sinon, ils sont conservés et réutilisés lors d'une nouvelle installation de l'extension. Les zones de Chine ajoutées avec Add Chinese provinces restent. Les commandes existantes conservent leur méthode 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, cliquez sur Uninstall (le bouton orange −) à côté de VibeFox SF 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é.

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