VibeFox Ninja Van for OpenCart — Aide

Prérequis

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

PHP : 8.0 ou ultérieur.

Grille tarifaire Ninja Van : les prix de votre compte expéditeur Ninja Van ou ceux fournis par l'équipe commerciale de Ninja Van, saisis dans le tableau des prix. Aucune clé d'API n'est requise. Les tarifs facultatifs en temps réel en Indonésie utilisent la Tariff API de Ninja Van, publique et ne nécessitant aucune authentification.

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

Installation

Le téléchargement est un fichier zip unique contenant les paquets des deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 vfd_ninja_van-oc3-(version).ocmod.zip et le paquet OpenCart 4 vfd_ninja_van.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_ninja_van-oc3-(version).ocmod.zip. L'extension n'ajoute aucune modification OCMOD : vous n'avez donc pas à actualiser Extensions > Modifications. Au lieu de l'installateur, vous pouvez copier le contenu du dossier upload de ce paquet dans le dossier racine de votre boutique.

2. Allez dans Extensions > Extensions et choisissez le type d'extension Shipping. Repérez VibeFox Ninja Van 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. Saisissez vos tarifs Ninja Van dans le tableau des prix. Pour l'Indonésie, vous pouvez éventuellement activer Live rates (voir Configuration). Activez Enable Ninja Van puis cliquez sur Save.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier vfd_ninja_van.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 tire le code de l'extension du 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 Ninja Van, 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 et 5 pour OpenCart 3. La page des réglages et ses champs sont identiques dans les deux versions.

Après l'installation, la méthode reste désactivée tant que vous n'avez pas activé Enable Ninja Van et enregistré. Si vous réinstallez l'extension après une désinstallation, les réglages Ninja Van 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 Ninja Van > Edit. Les sections sont listées à gauche. Un bouton Save en bas enregistre toute la page sans la recharger. Rien n'est enregistré et une erreur s'affiche lorsque Method title est vide, dépasse 64 caractères ou contient < > ; = # { }, lorsqu'un champ numérique contient du texte ou un nombre négatif, lorsque IDR conversion rate vaut 0, lorsque Minimum weight (kg) est supérieur à Maximum weight (kg), ou lorsque Sort order n'est pas un nombre entier. Si votre boutique ne dispose d'aucune classe de poids en kg et que l'unité de la classe de poids par défaut n'est pas connue de l'extension, un avertissement indique que les poids des produits sont considérés comme des kilogrammes : ajoutez une classe de poids kg dans System > Localisation > Weight Classes. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification pour cette extension peuvent enregistrer les réglages.

Général

Les réglages s'appliquent à toutes les zones géographiques. Vous pouvez limiter la méthode à une zone géographique dans Conditions, ou utiliser Ignore shipping zones.

Enable Ninja Van : affiche ou masque Ninja Van au moment du paiement. Par défaut : désactivé.

Method title : le nom de la méthode de livraison affiché au client dans le panier et lors du paiement. Par défaut : Ninja Van. Obligatoire, 64 caractères maximum.

Tax class : la classe de taxe des frais de livraison, ou No tax (par défaut). Choisissez No tax si les prix du tableau incluent déjà la taxe (GST, SST, VAT).

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

Prix (dans la devise par défaut de votre boutique, hors taxes)

Saisissez les tarifs de votre grille tarifaire Ninja Van dans la devise par défaut de votre boutique. Si votre grille est en SGD, MYR, IDR ou une autre devise, convertissez-la d'abord. Ce tableau sert pour toute destination 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 le bouton × pour en supprimer une. Choisissez * All other countries pour tous les pays sans ligne propre. Chaque ligne comporte un prix 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 vers ce pays. « 9.99 » et « 9,99 » sont tous deux acceptés. Les lignes sans prix sont supprimées à l'enregistrement, et seule la première ligne de chaque pays est conservée.

Price for countries not in the table : utilisé lorsque le tableau 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 vide pour masquer la méthode dans ce cas. 0 signifie livraison gratuite.

Price applies : la manière dont les prix sont calculés. Cela vaut aussi pour les tarifs en temps réel.

Tarifs en temps réel (API) — Indonésie

La Tariff API de Ninja Van renvoie les frais de livraison standard, sans suppléments ni remises, pour les colis expédiés en Indonésie. Ninja Van ne le propose que pour l'Indonésie. Lorsque Live rates est activé, les lignes d'état sous le titre de la section indiquent la zone d'expédition, un taux de conversion manquant et la dernière réponse de la Tariff API (environnement, heure et résultat). Elles sont mises à jour après chaque enregistrement.

Live rates : obtenez 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'expédition, par exemple ID_A00007_01 et ID_B00069_01, tirés du référentiel des codes de zone de Ninja Van (CSV) dont l'adresse s'affiche sous le champ. Saisissez les deux : l'adresse de la boutique dans OpenCart ne comporte pas de ville ni de rue distinctes, la zone d'expédition ne peut donc pas être détectée à partir d'elle. Les codes sont convertis en majuscules. Un code au mauvais format est effacé avec un avertissement. Si un seul code est saisi, un avertissement vous demande d'en saisir deux, et une ligne d'état indique que les tarifs en temps réel ne sont pas demandés. Une ligne d'état avertit aussi lorsque les deux codes ne forment pas une paire dans le référentiel des codes de zone.

IDR conversion rate : la Tariff API renvoie le montant en roupies indonésiennes (IDR). Si la devise par défaut de votre boutique est l'IDR, laissez ce champ vide. Sinon, indiquez la valeur de 1 IDR dans la devise de votre boutique, par exemple 0.000058. Elle doit être supérieure à 0. Sans elle, les tarifs en temps réel ne sont pas utilisés et c'est le tableau qui s'applique.

Conditions

Minimum weight (kg) : masque la méthode lorsque le panier pèse moins. Les poids des produits sont convertis depuis leur classe de poids OpenCart en kilogrammes. 0 signifie aucune limite (par défaut).

Maximum weight (kg) : masque la méthode lorsque le panier pèse plus. Par défaut : 30. 0 ou un champ vide signifient aucune limite. Ce poids ne peut pas être inférieur à Minimum weight (kg).

Minimum order amount : affiche la méthode uniquement lorsque le sous-total des produits nécessitant une expédition (après le coupon, avant taxes) atteint ce montant. Laissez vide pour l'afficher en permanence.

Free shipping from : le sous-total des produits nécessitant une expédition (après le coupon, avant taxes) à partir duquel la livraison Ninja Van est gratuite. Laissez vide pour qu'il n'y ait pas de livraison gratuite.

Geo zone : proposez Ninja Van uniquement pour les adresses situées dans cette zone géographique. All zones (par défaut) signifie aucune limite. Elle n'est pas vérifiée lorsque Ignore shipping zones est activé. Les zones géographiques se gèrent dans System > Localisation > Geo Zones.

Disponibilité sans zones d'expédition

Ignore shipping zones : proposez Ninja Van pour les pays ci-dessous, quelle que soit la Geo zone. Lorsque l'option est désactivée (par défaut), la zone géographique décide et la liste des pays n'est pas utilisée.

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

Avancé

Debug log : écrit les calculs de tarifs dans storage/logs/vfd_njvn_debug.log.php (sur OpenCart 4 system/storage/logs/vfd_njvn_debug.log.php). Le fichier n'est pas accessible depuis le web. Aucune adresse de client ni aucun code de zone n'est enregistré. Les requêtes échouées vers la Tariff API sont journalisées même lorsque cette option est désactivée. Désactivez-la une fois vos vérifications terminées. Lorsque le fichier atteint 5 Mo, il est déplacé vers vfd_njvn_debug.old.log.php et un nouveau journal est démarré.

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

Remove data on uninstall : lorsqu'elle est activée, la désinstallation de l'extension supprime les réglages Ninja Van et le journal. Désactivée (par défaut), ils 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. L'extension ne contient aucune clé secrète : tout est donc exporté.

Import : collez un JSON exporté précédemment et cliquez sur Import pour restaurer les réglages, par exemple sur une autre boutique. Les valeurs sont vérifiées comme lors d'un enregistrement normal.

Fonctionnement lors du paiement

Lorsque OpenCart affiche les méthodes de livraison, il demande à l'extension le tarif Ninja Van. Si une Geo zone est définie (et que Ignore shipping zones est désactivé) et que l'adresse se trouve en dehors, Ninja Van n'est pas proposé. 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 montant de la commande. L'extension vérifie ensuite les conditions : la liste des pays de Ignore shipping zones (si l'option est activée), le poids du panier et le montant minimum de commande. Le montant de la commande correspond au prix des produits nécessitant une expédition, après la remise du coupon et avant taxes. Les cartes cadeaux, les points de fidélité et le crédit boutique ne sont pas pris en compte. Si la livraison gratuite s'applique, le prix est 0 et aucune requête n'est envoyée à Ninja Van.

Le prix provient de la ligne du pays (ou de la ligne *) : d'abord la colonne de poids, sinon le prix de base, sinon Price for countries not in the table. S'il n'y a aucun prix, la méthode est masquée pour ce panier. Le prix est calculé dans la devise par défaut de votre boutique, arrondi à ses décimales, puis affiché au client dans sa devise avec la taxe de la Tax class sélectionnée.

Lorsque Live rates est activé, une livraison en Indonésie est d'abord tarifée par Ninja Van. L'extension transforme l'adresse de livraison en codes de zone Ninja Van : la région (province) de l'adresse, le champ City (ville ou régence) et, pour les villes comptant plusieurs zones, le district (Kecamatan) indiqué dans Address 1 ou Address 2. Elle envoie vos codes d'expédition, les codes de livraison, le poids et le niveau de service, puis convertit le tarif de l'IDR vers la devise de votre boutique. Avec Per item, une requête est envoyée par poids d'article différent, jusqu'à 5 par panier. Si les poids différents sont plus nombreux, le tableau des prix est utilisé.

La Tariff API accepte 20 requêtes par minute ; les réponses sont donc mises en cache dans une table de l'extension : les prix pendant 6 heures, « pas de tarif pour cet itinéraire » pendant 1 heure et les échecs pendant 5 minutes. L'enregistrement des réglages ne vide pas ce cache. 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, renvoie une erreur, n'a pas de tarif pour l'itinéraire ou si l'adresse ne peut pas être associée, le prix du tableau est utilisé. Les erreurs vont dans le journal, jamais au client.

Sur OpenCart 4, le client clique sur Choose dans le bloc du mode de livraison de la page de paiement et choisit Ninja Van dans la fenêtre Shipping method options. La méthode fonctionne de la même manière que sur OpenCart 3.

L'extension calcule uniquement 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 COD. Utilisez pour cela le Dashboard Ninja Van. Il n'existe pas de sélecteur de points relais (Ninja Points) : la méthode est une livraison à domicile. L'extension n'ajoute rien aux commandes : la commande affiche le nom de la méthode et les frais de livraison comme pour toute autre méthode de livraison OpenCart. Les tarifs en temps réel ne sont pas disponibles en dehors de l'Indonésie.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Ninja Van est le premier bloc de Extensions > Extensions > Shipping > VibeFox Ninja Van > 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) 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: opencart-shipping-ninja-van et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les utilisateurs administrateurs disposant de l'autorisation de modification pour l'extension peuvent changer 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é une place 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 seul domaine : l'adresse de la boutique dans la configuration d'OpenCart. Retirer la clé de la boutique ne libère pas sa place de domaine. Libérez la place dans votre compte vibefox.net.

Sans clé active, la méthode de livraison Ninja Van n'est pas affichée aux clients lors du paiement et aucun tarif n'est calculé. Un administrateur connecté à l'administration dans le même navigateur voit toujours la méthode dans la boutique, marquée (unlicensed — visible to admins only), afin que vous puissiez configurer et 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 à l'administration, donc sans clé active la méthode est 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 le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement lorsque vous ouvrez le Dashboard de l'administration ou la page Edit : 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 licence.

Dépannage

Ninja Van n'apparaît pas lors du paiement : vérifiez que la licence est active et que Enable Ninja Van est activé. Contrôlez Geo zone (ou Ignore shipping zones et Countries), les limites de poids et Minimum order amount, et que le pays, la ligne * ou Price for countries not in the table comporte un prix. Vérifiez que les produits ont Requires Shipping réglé sur Yes.

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, région (province), ville ou régence dans City et, pour les villes comptant plusieurs zones, le district (Kecamatan) dans une ligne d'adresse. Sinon, le prix du tableau est utilisé. Activez le Debug log, rechargez la page de paiement et consultez le champ Log sur la page de l'extension.

Les tarifs en temps réel ne sont pas demandés du tout : les lignes d'état sous Tarifs en temps réel (API) — Indonésie indiquent la raison : les codes de zone d'expédition sont absents, un seul des deux codes est saisi, les codes saisis ne forment pas une paire dans le référentiel des 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. L'enregistrement des réglages ne met pas fin à la pause.

Dans quelle devise sont les prix : le tableau et les conditions sont exprimés dans la devise par défaut 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.

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

Pour les développeurs : une boutique disposant de son propre champ de district (Kecamatan) peut fournir les codes de zone grâce à l'événement OpenCart vfd_ninja_van/tariff_zone (déclencheur catalog/vfd_ninja_van/tariff_zone), y compris pour la zone d'expédition. L'adresse de la Tariff API peut être remplacée par le réglage vfd_njvn_api_url (pour les tests) ; il n'a pas de champ sur la page des réglages.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Shipping et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox Ninja Van. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart réinitialise toujours Enable Ninja Van, Sort order, Tax class et Geo zone. Les tarifs en cache sont toujours supprimés. Si Remove data on uninstall est activé, les réglages Ninja Van, le dernier état de la Tariff API et le journal de débogage sont également supprimés. S'il est désactivé, les autres réglages sont conservés et réutilisés lors d'une nouvelle installation de l'extension. 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 et cliquez sur Uninstall (le bouton orange −) à côté de VibeFox Ninja Van dans la liste des extensions installées, puis sur Delete (le bouton rouge en forme de corbeille) pour supprimer le paquet envoyé.

Ninja Van est une marque commerciale de son propriétaire respectif. Cette extension n'est ni affiliée ni approuvée par Ninja Van.