VibeFox Ninja Van 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.

Grille tarifaire Ninja Van : les tarifs de votre compte expéditeur Ninja Van ou fournis par l'équipe commerciale de 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 qui ne nécessite aucune authentification.

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 Ninja Van 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. Saisissez vos tarifs Ninja Van dans le tableau des prix. Pour l'Indonésie, vous pouvez activer en option Live rates (voir Configuration). Cliquez sur Save.

À l'installation, le module crée le transporteur Ninja Van avec le texte de délai de livraison Courier delivery. Le transporteur est activé, affecté à toutes les zones et à tous les groupes de clients, et n'a aucune règle de taxe. 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 à cet endroit : le prix provient toujours du module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Ninja Van > Configure. Ils s'appliquent à toutes les zones du transporteur. Chaque section possède son propre bouton Save, qui enregistre la page entière. Rien n'est enregistré et une erreur s'affiche 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 Method title dépasse 64 caractères. Si l'unité de poids de votre boutique n'est pas connue du module, un avertissement après l'enregistrement indique que les poids des produits sont pris en kilogrammes.

Général

Enable Ninja Van: 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é au client dans le panier et au moment du paiement. Par défaut : Ninja Van. Obligatoire, 64 caractères maximum.

Tax: la règle de taxe du transporteur, ou No tax (par défaut). Choisissez No tax si les prix du tableau incluent déjà les taxes (GST, SST, VAT).

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 est utilisé 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 l'icône de corbeille pour en supprimer une. Choisissez * All other countries pour tous les pays qui n'ont pas leur propre ligne. Chaque ligne contient 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. Les valeurs « 9.99 » et « 9,99 » sont toutes deux acceptées. Les lignes sans tarif sont supprimées à l'enregistrement, et seule la première ligne d'un 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 (ni de ligne *), ou lorsque la ligne n'a pas de tarif pour ce poids. Laissez vide pour masquer le transporteur dans ce cas. 0 signifie livraison gratuite.

Price applies: le mode de calcul des tarifs. 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 sous le titre de la section affichent la zone d'expédition, l'absence de taux de conversion et la dernière réponse de l'API Tariff (environnement, heure et résultat).

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 de la table de correspondance des codes de zone Ninja Van (CSV) dont l'adresse s'affiche sous le champ. Saisissez les deux, ou laissez-les vides pour les détecter à partir de l'adresse de la boutique dans Shop Parameters > Contact > Stores : Indonésie, province (state), ville et, si la ville compte plusieurs zones, le district (Kecamatan) dans la ligne d'adresse. Un code au format incorrect est effacé avec un avertissement. Si un seul code est saisi, un avertissement demande d'en saisir deux, et une ligne d'état indique que les tarifs en temps réel ne sont pas demandés.

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

Conditions

Minimum weight (kg) : masque le transporteur lorsque le panier pèse moins. Les poids des produits sont convertis de l'unité de poids de votre boutique en kilogrammes. 0 signifie aucune limite.

Maximum weight (kg) : masque le transporteur lorsque le panier pèse plus. Par défaut : 30. 0 signifie aucune limite. Ce montant ne peut pas être inférieur à Minimum weight (kg).

Minimum order amount : n'affiche le transporteur que lorsque le sous-total du panier (produits soumis à expédition, après remises, avant taxes) atteint ce montant. Laissez vide pour toujours l'afficher.

Free shipping from : le sous-total du panier (produits soumis à expédition, après remises, avant taxes) à partir duquel la livraison Ninja Van est gratuite. Laissez vide pour ne pas proposer de livraison gratuite.

Disponibilité sans zones de livraison

Ignore shipping zones : propose Ninja Van pour les pays ci-dessous même si le transporteur n'est pas lié à leur zone. Lorsque l'option est activée, le transporteur est lié à toutes les zones actives, y compris celles que vous créerez plus tard. Lorsque vous la désactivez, le transporteur retrouve les zones qu'il avait auparavant.

Countries : les pays de destination pour ce mode. Laissez 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 : enregistre les calculs de tarifs dans logs/vfd_njvn_debug.log.php, dans le dossier du module. Ce fichier ne peut pas être ouvert depuis le web. Aucune adresse de client n'est enregistrée. Les requêtes API Tariff en échec sont enregistrées même lorsque cette option est désactivée. Désactivez-la lorsque vous avez terminé.

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 : lorsque l'option est activée, la désinstallation du module supprime ses réglages, le transporteur, les tarifs en cache et le journal. Lorsqu'elle est désactivée, tout est conservé pour une réinstallation.

Fonctionnement au moment du paiement

À l'étape de livraison, PrestaShop demande au module le tarif Ninja Van. Seuls les produits physiques comptent : les produits virtuels n'ajoutent pas de poids et ne sont pas inclus dans le montant de la commande. Le module vérifie d'abord les conditions : la liste de pays de Ignore shipping zones (si l'option est activée), le poids du panier et le montant minimum de commande. Si la livraison gratuite s'applique, le tarif est 0 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. S'il n'y a pas de tarif, le transporteur est masqué pour ce panier. Le tarif est calculé dans la devise par défaut de la boutique, puis affiché dans la devise du panier du client.

Lorsque Live rates est activé, une livraison en Indonésie est d'abord tarifée par Ninja Van. Le module convertit les adresses d'expédition et de livraison en codes de zone Ninja Van : province (state), ville ou régence et, pour les villes à plusieurs zones, le district (Kecamatan) écrit dans une ligne d'adresse. Il envoie les codes, le poids et le niveau de service, et convertit les frais de 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. Avec davantage de poids différents, le tableau des prix est utilisé.

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. Le module n'envoie jamais plus de 18 requêtes par minute et, après une réponse HTTP 429, il 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 tarif du tableau est utilisé. Les erreurs sont enregistrées dans le journal, jamais montrées au client.

Si vous modifiez le transporteur dans Shipping > Carriers après qu'il a des commandes, PrestaShop l'enregistre comme une nouvelle version du transporteur. Le module suit automatiquement la nouvelle version.

Le module ne calcule que les tarifs. Il 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 transporteur assure une livraison à domicile. Les tarifs en temps réel ne sont pas disponibles hors Indonésie.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Ninja Van est le premier bloc de Modules > Module Manager > VibeFox Ninja Van > 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) 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 figurent la ligne Product: presta-shipping-ninja-van 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 : le domaine 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 Ninja Van n'est pas affiché aux clients au moment du paiement et aucun tarif n'est calculé. La vitrine 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 moment du 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 l'assistance nécessitent un renouvellement. Le statut est vérifié automatiquement pendant que vous travaillez dans le back-office : une fois par jour pendant les 14 premiers jours suivant la saisie de la clé, puis une fois par semaine. Aucune tâche cron n'est nécessaire. La désinstallation ou la réinitialisation du module supprime toujours la clé de licence et le statut de la licence.

Dépannage

Ninja Van n'apparaît pas au moment du paiement : vérifiez que la licence est active et que Enable Ninja Van 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 Minimum order amount, et vérifiez que le pays, la ligne * ou Price for countries not in the table a un tarif. Les produits peuvent aussi être limités à certains transporteurs sur la page produit.

Le tarif en temps réel n'est pas utilisé pour certaines adresses : la destination doit correspondre à une zone Ninja Van : Indonésie, province (state), ville ou régence et, pour les villes à plusieurs zones, le district (Kecamatan) dans une ligne d'adresse. Sinon, le tarif du tableau est utilisé. Activez Debug log, rechargez la page de paiement et consultez le champ Log sur la page du module.

Les tarifs en temps réel ne sont pas du tout demandés : les lignes d'état sous Tarifs en temps réel (API) — Indonésie 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), un seul des deux codes est saisi, les codes saisis ne forment pas une paire dans la table de correspondance des zones, ou IDR conversion rate est absent.

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.

Devise des tarifs : 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 indique que le transporteur Ninja Van est introuvable : le transporteur a été supprimé dans Shipping > Carriers. Réinitialisez le module dans Modules > Module Manager pour le recréer.

Développeurs : une boutique disposant de son propre champ de district (Kecamatan) peut fournir les codes de zone via le hook actionVfdNjvnTariffZone.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Ninja Van et choisissez Uninstall. La clé de licence et le statut de la 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) et les réglages, le dernier statut de l'API Tariff et le journal sont supprimés. Si l'option est désactivée, le transporteur est seulement désactivé et tous les réglages sont conservés. Une nouvelle installation du module rend au transporteur enregistré le statut qu'il avait avant la désinstallation.

Ninja Van est une marque commerciale de son titulaire respectif. Ce module n'est ni affilié à Ninja Van ni approuvé par cette dernière.