VibeFox Ninja Van 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 Ninja Van : les tarifs de votre compte expéditeur Ninja Van ou fournis par l'équipe commerciale Ninja Van, saisis dans le tableau des prix. Aucune clé d'API n'est nécessaire. Les tarifs en temps réel facultatifs en Indonésie utilisent l'API Ninja Van Tariff, publique et sans authentification.
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_ninja_van dans /wp-content/plugins/ par FTP.
2. Cliquez sur Activate.
3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox Ninja Van, 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 tarifs Ninja Van dans le tableau des prix. Pour l'Indonésie, vous pouvez activer Live rates (voir Configuration).
6. Ajoutez VibeFox Ninja Van à une zone de livraison (par exemple « Singapour ») 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 Ninja Van. Ils s'appliquent à toutes les zones de livraison. Lorsque vous ajoutez le mode à 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.
Général
Enable/Disable: active ou désactive le mode dans toutes les zones à la fois.
Method title: le nom du mode de livraison affiché dans le panier et au paiement. Une zone peut le remplacer. Par défaut : Ninja Van.
Tarifs (dans la devise de votre boutique)
Saisissez les tarifs de votre grille Ninja Van dans la devise de votre boutique. Si votre grille est en SGD, MYR, IDR, PHP, THB ou VND, convertissez-la d'abord. Ce tableau sert pour toutes les destinations hors Indonésie et chaque fois qu'un tarif en temps réel n'est pas disponible.
Price table: une ligne par pays de destination. Cliquez sur + Add country pour ajouter une ligne et sur la croix pour en supprimer une. Choisissez * All other countries pour tous les pays qui n'ont pas leur propre ligne. Chaque ligne comporte un Base price 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 tarif de base. Un tarif de base de 0 signifie livraison gratuite vers ce pays. « 9.99 » et « 9,99 » sont tous deux acceptés. Les lignes sans tarif sont supprimées à l'enregistrement.
Price for countries not in the table: utilisé lorsque le tableau n'a pas de ligne pour le pays de destination (ni de ligne *), ou lorsque la ligne n'a pas de tarif pour ce poids. Laissez-le vide pour masquer le mode dans ce cas.
Price applies: la manière dont les tarifs sont calculés. Cela s'applique aussi aux tarifs en temps réel.
Tarifs en temps réel (API) — Indonésie
L'API Ninja Van Tariff renvoie les frais de livraison standard, sans suppléments ni remises, pour les colis expédiés en Indonésie. Ninja Van ne la propose que pour l'Indonésie. Lorsque Live rates est activé, les lignes d'état de cette section affichent la zone d'expédition, un taux de conversion manquant et la dernière réponse de l'API Tariff.
Live rates: obtient les tarifs Ninja Van en temps réel pour les livraisons en Indonésie. Par défaut : désactivé. Sans cette option, rien n'est envoyé à Ninja Van pendant le paiement.
Environment: Production (api.ninjavan.co) (par défaut) ou Sandbox — testing only (api-sandbox.ninjavan.co).
Service level: le service pour lequel le tarif est demandé : Standard (par défaut), Express, Same day ou Next day. Si Ninja Van n'a pas de tarif pour l'itinéraire et le service, le tableau des prix est utilisé.
Ship-from zone code L1 et Ship-from zone code L2: les codes de niveau L1 et L2 du district d'où vous expédiez, par exemple ID_A00007_01 et ID_B00069_01, tirés de la table de codes de zone Ninja Van (CSV) liée sur la page de réglages. Saisissez les deux, ou laissez-les vides pour les détecter à partir de l'adresse de la boutique dans WooCommerce > Settings > General : Indonésie, province, ville et, si la ville compte plusieurs zones, le district (Kecamatan) dans la ligne d'adresse. Un code au mauvais format est effacé avec un message d'erreur.
IDR conversion rate: l'API Tariff renvoie les frais en roupies indonésiennes (IDR). Si la devise de votre boutique est l'IDR, laissez le champ vide. Sinon, indiquez la valeur de 1 IDR dans la devise de votre boutique, par exemple 0.000058. Sans ce taux, les tarifs en temps réel ne sont pas utilisés et c'est le tableau des prix qui s'applique.
Conditions
Minimum weight (kg): masque le mode lorsque le panier pèse moins. 0 signifie aucune limite.
Maximum weight (kg): masque le mode lorsque le panier pèse plus. Par défaut : 30. 0 signifie aucune limite.
Minimum order amount: affiche le mode uniquement lorsque le sous-total du panier (après remises, avant taxes) atteint ce montant. Laissez le champ vide pour l'afficher toujours.
Free shipping from: le sous-total du panier (après remises, avant taxes) à partir duquel la livraison Ninja Van est gratuite. Laissez le champ vide s'il n'y a pas de livraison gratuite.
Excluded shipping classes: masque le mode lorsque le panier contient un produit appartenant à l'une de ces classes d'expédition WooCommerce.
Tax status: Taxable ajoute la taxe WooCommerce aux frais de livraison, None ne l'ajoute pas. Choisissez None si les tarifs du tableau incluent déjà les taxes (GST, SST, TVA).
Disponibilité sans zones de livraison
Ignore shipping zones: propose Ninja Van aux pays indiqués ci-dessous, même si le mode n'est ajouté à aucune zone de livraison.
Countries: les pays de destination pour ce mode. Laissez le champ vide pour utiliser tous les pays vers lesquels vous livrez. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.
Avancé
Debug log: enregistre les calculs de tarifs dans WooCommerce > Status > Logs (source vfd_ninja_van). Aucune adresse client n'est enregistrée. Les requêtes échouées vers l'API Tariff sont enregistrées même lorsque cette option est désactivée. Désactivez-la lorsque vous avez fini.
Remove data on uninstall: lorsqu'elle est activée, la suppression de l'extension efface tous les réglages Ninja Van et les modes de zone. 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, montant minimum de commande et classes d'expédition exclues. Si la livraison gratuite s'applique, le client voit le mode sans frais et aucune requête n'est envoyée à Ninja Van.
Le tarif provient de la ligne du pays (ou de la ligne *) : la colonne de poids, sinon le tarif de base, sinon Price for countries not in the table. Les poids des produits sont convertis de l'unité de poids de votre boutique en kilogrammes. S'il n'y a pas de tarif, le mode est masqué.
Lorsque Live rates est activé, une livraison en Indonésie est d'abord tarifée par Ninja Van. L'extension convertit les adresses d'expédition et de livraison en codes de zone Ninja Van : province, ville ou régence et, pour les villes comptant plusieurs zones, le district (Kecamatan) indiqué dans une ligne d'adresse. Elle envoie les codes, le poids et le niveau de service, puis convertit les frais de l'IDR vers la devise de votre boutique. Avec Per item, une requête est envoyée par poids d'article distinct, jusqu'à 5 par panier.
L'API Tariff autorise 20 requêtes par minute ; les réponses sont donc mises en cache pendant 6 heures, les échecs pendant 5 minutes et « aucun tarif pour cet itinéraire » pendant 1 heure. L'extension n'envoie jamais plus de 18 requêtes par minute et, après une réponse HTTP 429, elle se met en pause pendant une heure. Le délai d'attente de l'API est de 12 secondes. Si Ninja Van ne répond pas, répond par une erreur, n'a pas de tarif pour l'itinéraire ou si l'adresse ne peut pas être associée, le tarif du tableau est utilisé. Les erreurs sont consignées dans le journal, jamais montrées au client.
Le mode fonctionne avec le paiement classique et avec les blocs Panier et Paiement. Il est compatible avec le stockage des commandes haute performance de WooCommerce (HPOS).
L'extension ne fait que calculer les tarifs. Elle ne crée pas de commandes Ninja Van, n'imprime pas de lettres de transport aérien (AWB), ne réserve pas d'enlèvements, ne suit pas les colis et ne gère pas le paiement à la livraison (COD). Utilisez le Ninja Van Dashboard pour cela. Il n'y a pas de sélecteur de points de retrait (Ninja Points) : le mode est une livraison à domicile. Les tarifs en temps réel ne sont pas disponibles hors Indonésie.
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 Ninja Van. 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-le dans votre compte vibefox.net.
Sans clé active, Ninja Van n'est pas affiché aux clients au paiement. Les gestionnaires de la boutique connectés le voient toujours, marqué (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
Ninja Van n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé et que le mode est ajouté à 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, ainsi que la présence d'un tarif pour le pays, la ligne * ou Price for countries not in the table.
Le tarif en temps réel n'est pas utilisé pour certaines adresses : la destination doit être associée à une zone Ninja Van : Indonésie, province, ville ou régence et, pour les villes comptant plusieurs zones, le district (Kecamatan) dans une ligne d'adresse. Sinon, le tarif du tableau est utilisé. Activez Debug log pour en voir la raison et consultez les lignes d'état sous Tarifs en temps réel (API) — Indonésie.
Les tarifs en temps réel ne sont pas demandés du tout : les lignes d'état indiquent la raison : l'adresse de la boutique n'est pas en Indonésie ou la zone d'expédition n'a pas pu être détectée (saisissez les deux codes de zone), ou IDR conversion rate est manquant.
Limite de requêtes atteinte (HTTP 429) : les requêtes en temps réel sont suspendues pendant une heure et le tableau des prix est utilisé entre-temps.
Dans quelle devise sont les tarifs : le tableau est dans la devise de votre boutique. Les tarifs en temps réel sont en roupies (IDR), convertis avec IDR conversion rate, sauf si la devise de votre boutique est l'IDR.
Développeurs : un site disposant de son propre champ de district (Kecamatan) au paiement peut fournir les codes de zone avec le filtre vfd_njvn_tariff_zone.
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 modes de zone, le dernier état de l'API Tariff et les tarifs en temps réel 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.
Ninja Van est une marque commerciale de son titulaire. Cette extension n'est ni affiliée à Ninja Van ni approuvée par Ninja Van.