VibeFox Ninja Van for Adobe Commerce — Ajuda
Requirements
Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.
PHP: 8.1 to 8.4, with the cURL, JSON and mbstring extensions.
Ninja Van rate card: the prices of your Ninja Van shipper account or from the Ninja Van sales team, entered in the price table. No API keys are needed. The optional live prices within Indonesia use the Ninja Van Tariff API, which is public and needs no authentication.
VibeFox license key: bought on vibefox.net. One key works on one domain.
Installation
The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.
1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-ninja-van-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/NinjaVanShipping/, so that registration.php is directly in that folder.
2. Run bin/magento module:enable Vibefox_NinjaVanShipping and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.
3. In the Admin go to Stores > Configuration > Sales > Delivery Methods and open VibeFox Ninja Van. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).
4. Enter your Ninja Van prices in the price table. For Indonesia, optionally set Live rates to Yes (see Configuration). Set Enable Ninja Van to Yes and click Save Config.
The module adds the Ninja Van shipping method to Magento. Customers see it as Ninja Van - Shipping (method title and method name). After installation it is off (Enable Ninja Van = No), the price table and the fallback cost are empty and Live rates is No.
Configuration
All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox Ninja Van, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Method title and Method name also for a store view. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page and clears the cached Ninja Van prices. Amounts accept "9.99" and "9,99". Opening or saving the settings never sends a request to Ninja Van.
If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Method title or Method name, longer than 64 characters or with one of the characters < > ; = # { }; a Sort order that is not a whole number; a number field that holds text or a negative number; an IDR conversion rate of 0; a Minimum weight (kg) greater than the Maximum weight (kg). A ship-from zone code in the wrong format is cleared with a warning, the rest is saved.
While Enable Ninja Van is Yes, messages after saving remind you of settings that matter: a weight unit the module does not know (weights are then taken as kilograms), and, with Live rates on, a ship-from zone that is missing or not valid and a missing conversion rate. The messages are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods.
General
Enable Ninja Van: shows or hides Ninja Van at checkout. Default: No.
Method title: the carrier name shown in the cart and at checkout. Default: Ninja Van. Required, at most 64 characters.
Method name: shown after the method title, as "Method title - Method name". Default: Shipping. Required, at most 64 characters.
Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.
The module has no tax field. If your store charges tax on shipping, choose the tax class in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping. If your rate card already includes tax (GST, SST, VAT), do not tax shipping there, so tax is not charged twice.
Rates (in the base currency of your store, tax excluded)
Enter the prices of your Ninja Van rate card in the base currency of your store. If your rate card is in SGD, MYR, IDR or another currency, convert it first. Magento shows the price to the customer in their currency. This table is used for every destination outside Indonesia, and whenever a live price is not available.
Country prices: one row per destination country. Click Add country to add a row and Delete to remove one. Choose * All other countries for every country without its own row. Each row has a Price (the base price) and weight columns: XS up to 1 kg, S up to 2 kg, M up to 3 kg, L up to 5 kg and XL over 5 kg. An empty (or 0) weight column uses the base price. Price 0 means free shipping to that country. Invalid cells are cleared, rows without prices are dropped when you save, and only the first row of a country is kept.
Fallback cost: used when the table has no row for the destination country (and no * row), or the row has no price for this weight. Leave it empty to hide the method in that case. 0 means free shipping.
Calculation type: the way prices are counted. This also applies to live prices.
Live rates (API)
The Ninja Van Tariff API returns the standard delivery fee, without surcharges and discounts, for parcels sent within Indonesia. Ninja Van offers it for Indonesia only. Without it nothing is sent to Ninja Van during checkout.
Live rates: get live Ninja Van prices for deliveries within Indonesia. Default: No. If the API fails, the price table is used.
Environment: Production (default, api.ninjavan.co) or Sandbox (api-sandbox.ninjavan.co), for testing only.
Service level: the service the price is requested for: Standard (default), Express, Same day or Next day. The customer does not choose a service at checkout. If Ninja Van has no price for the route and service, the price table is used.
Ship-from zone code L1 and Ship-from zone code L2: the L1 and L2 tier codes of the district you ship from, for example ID_A00007_01 and ID_B00069_01, from the Ninja Van zone code mapping. Enter both, or leave both empty to detect them from the shipping origin of your store in Stores > Configuration > Sales > Shipping Settings > Origin: country Indonesia, the region (province), the city and, if the city has several zones, the district (Kecamatan) in one of the street address lines. A code in the wrong format is cleared with a warning. If only one code is entered, or the two codes are not a pair in the included mapping, live prices are not requested and the status line says so.
IDR conversion rate: the Tariff API returns the fee in Indonesian rupiah (IDR). If the base currency of your store is IDR, leave it empty. Otherwise enter how much 1 IDR is in your base currency, for example 0.000058 (up to 10 decimals). It must be greater than 0. Without it live prices are not used and the price table is.
Tariff API status: shown while Live rates is Yes. It shows the ship-from zone (or why it could not be found), a warning when the conversion rate is missing and the last real Tariff API answer: environment, time and result (OK, no price for this route and service, HTTP 429, or failed). Answers from the cache do not change it. Flushing the whole Magento cache can clear the last answer.
Availability
Minimum weight (kg): hide the method when the cart weighs less. 0 means no limit.
Maximum weight (kg): hide the method when the cart weighs more. Default: 30. Empty or 0 means no limit. It cannot be lower than Minimum weight (kg).
Product weights are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs). The price uses the actual weight (the sum of product weights). Magento products have no standard dimensions, so volumetric weight is not calculated.
Minimum order amount: show the method only when the cart subtotal (products that need shipping, after discounts, before tax, in the base currency) reaches this amount. Leave empty to always show it.
Free shipping from: the cart subtotal (calculated the same way) from which Ninja Van shipping is free. It is checked before the live price and the price table, so no price is needed for free shipping. Leave empty for no free shipping.
Ship to Applicable Countries: All Allowed Countries offers Ninja Van for every country your store allows, Specific Countries only for the countries below.
Ship to Specific Countries: the destination countries for Specific Countries. Live prices cover Indonesia only; the price table can cover any country you choose.
Advanced
Debug log: writes rate calculations to var/log/vfd_njvn_debug.log.php in the Magento folder. The file cannot be opened from the web. Warnings and errors, such as failed Tariff API requests, are always logged, even when this is off. Customer addresses and zone codes are never logged. Turn it off when you are done.
Log: shows the size and the latest entries of the log. Click Clear log to empty it.
Remove data on uninstall: when Yes, uninstalling the module with its data also deletes the Ninja Van settings and the log (see Uninstall). The license key, the cached prices, the request limiter and the API status are always removed.
How it works at checkout
At the shipping step Magento asks the module for the Ninja Van price. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the order amount. The module first checks the countries, the cart weight and Minimum order amount. If Free shipping from applies, the price is 0 and no request goes to Ninja Van. A Magento cart price rule with free shipping also makes the price 0 without a request to Ninja Van; the weight limits, the minimum order amount and the countries still apply.
The price comes from the row of the country (or the * row): the weight column, else the base price, else Fallback cost. If there is no price, the method is hidden for that cart. The price is calculated in the base currency of your store; Magento shows it in the customer's currency and adds tax on shipping if your store charges it.
With Live rates on, a delivery within Indonesia is priced by Ninja Van first. The module turns the ship-from and delivery addresses into Ninja Van zone codes: region (province), city or regency and, for cities with several zones, the district (Kecamatan) written in a street address line. It sends the codes, the weight and the service level, and converts the fee from IDR to your base currency. With Per item, one request is sent per distinct item weight, up to 5 per cart. With more different weights the price table is used.
The Tariff API allows 20 requests a minute, so answers are cached for 6 hours, failures for 5 minutes and "no price for this route" for 1 hour. The module never sends more than 18 requests a minute, and after an HTTP 429 answer it pauses for an hour. The API timeout is 12 seconds. If Ninja Van does not answer, answers with an error or a zero fee, has no price for the route, or the address cannot be matched, the table price is used. Errors go to the log, never to the customer.
The order and the order e-mail show the method name (for example Ninja Van - Shipping) and the shipping price, as with any Magento shipping method. They do not depend on whether the module is enabled later.
The module calculates prices only. It does not create Ninja Van orders, print airway bills (AWB), book pickups, track parcels or handle COD. Use the Ninja Van Dashboard for that. There is no pickup point (Ninja Points) selector: the method is door-to-door delivery. Live prices are not available outside Indonesia.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Ninja Van is the first row of the VibeFox Ninja Van group in Stores > Configuration > Sales > Delivery Methods, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this store. Below them are the line Product: magento-shipping-ninja-van and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Delivery Methods configuration section can change the key. The texts of the block follow the Admin interface locale (English and Russian are included).
If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.
One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.
Without an active key, the Ninja Van method is not shown to customers at checkout and no rate is calculated. The Magento storefront does not know that you are logged in to the Admin, so the method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. Existing orders are not affected.
When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.
Troubleshooting
Ninja Van does not appear at checkout: check that the license is active and Enable Ninja Van is Yes for the website of the store. Check Ship to Applicable Countries and Ship to Specific Countries, the weight limits and Minimum order amount, and that the country, the * row or Fallback cost has a price.
The live price is not used for some addresses: the destination must be matched to a Ninja Van zone: Indonesia, region (province), city or regency and, for cities with several zones, the district (Kecamatan) in a street address line. Otherwise the table price is used. Turn on Debug log, reload the checkout and look at the Log field in the Advanced section.
Indonesian provinces are not in a list: if your Magento has no province list for Indonesia, the State/Province field is a text field. The province must then be entered as its code, for example JK (or ID-JK) for Jakarta or JB for Jawa Barat, in the shipping origin and in the customer's address. A full province name is not recognized, and the table price is used.
Live prices are not requested at all: the Tariff API status line in Live rates (API) shows the reason: the shipping origin is not in Indonesia or the ship-from zone could not be detected (enter both zone codes), only one of the two codes is entered, the entered codes are not a pair in the zone code mapping, or IDR conversion rate is missing.
Rate limit reached (HTTP 429): live requests are paused for an hour and the price table is used meanwhile.
Which currency are the prices in: the table and the conditions are in the base currency of your store. Live prices are in rupiah (IDR), converted with IDR conversion rate unless your base currency is IDR.
Prices look outdated after a change: click Save Config on the Delivery Methods page. This clears the cached Ninja Van prices.
The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.
Developers: a store with its own district (Kecamatan) field can supply the zone codes with the Magento event vfd_njvn_tariff_zone. The module checks the returned pair against the mapping.
Uninstall
Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:
Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_NinjaVanShipping. It removes the data and the code.
Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_NinjaVanShipping to remove the data, then bin/magento module:disable Vibefox_NinjaVanShipping, delete the folder app/code/Vibefox/NinjaVanShipping and run bin/magento setup:upgrade.
The license key, the license status, the cached prices, the request limiter and the last Tariff API status are always removed. If Remove data on uninstall is Yes, the Ninja Van settings and the log are removed too. If it is No, the settings are kept for a re-install. Orders keep their shipping method and price.
Ninja Van is a trademark of its respective owner. This module is not affiliated with or endorsed by Ninja Van.