VibeFox Jadlog for Adobe Commerce — 도움말

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 and JSON extensions.

Jadlog contract (for live prices and Pickup points): live prices and the list of Pickup points come from the Jadlog Embarcador API. Your Jadlog franchise issues the access after the contract is signed. You need the Embarcador API token, the CNPJ (or CPF) of the shipper registered in the contract, the current account (conta corrente) and, if you have one, the contract number. If you only use fixed prices, you do not need a Jadlog contract.

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-jadlog-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/JadlogShipping/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_JadlogShipping 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 Jadlog. 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. Paste the API token, enter the CNPJ, current account, contract number and origin CEP, choose the home delivery service and, if the base currency of your store is not BRL, enter the BRL exchange rate. Add fixed prices or a fallback cost if you want them (see Configuration). To offer Jadlog Pickup points as well, set Jadlog Pickup to Yes. Set Enable Jadlog to Yes and click Save Config.

The module adds the Jadlog shipping method to Magento with two kinds of options: home delivery and Jadlog Pickup points. Customers see home delivery as Jadlog - Jadlog (carrier title and home delivery name). The module is off after installation (Enable Jadlog = No). Home delivery is Yes and Jadlog Pickup is No by default, and Jadlog is offered for Brazil only until you change Ship to Specific Countries.

Configuration

All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox Jadlog, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website or a store view with the Scope switcher at the top of the page. For Remove data on uninstall only the value of the Default Config is used. Save Config saves the whole page and clears the cached Jadlog prices and Pickup point lists. Amounts accept "9.99" and "9,99".

If Carrier title, Home delivery name or Pickup method name is empty, longer than 64 characters or contains one of the characters < > ; = # { }, or Sort order is not a whole number, Magento shows an error and nothing on the page is saved. Other wrong values are reported with a warning while the rest of the page is saved: a number that is not valid (or a BRL exchange rate of 0) is cleared; a minimum weight above the maximum weight keeps both previous weights; an origin CEP without 8 digits or a CNPJ without 14 digits (or 11 for a CPF) is saved as typed so you can correct it; unknown countries are removed from the price table and invalid prices are cleared.

While Enable Jadlog is Yes, the Information row at the top of the group shows warnings for an incomplete setup: no API token (only fixed prices are used, and Pickup points cannot be listed), no API token and no fixed prices (no shipping methods are offered), no CNPJ or current account, no origin CEP, or no BRL exchange rate when the base currency is not BRL. The warnings are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods.

General

Enable Jadlog: shows or hides all Jadlog options at checkout. Default: No.

Carrier title: the carrier name shown in the cart and at checkout, above the Jadlog options. Default: Jadlog. Required, at most 64 characters.

Home delivery: offers Jadlog home delivery. Default: Yes.

Home delivery name: shown after the carrier title, as "Carrier title - Home delivery name". Default: Jadlog. Required, at most 64 characters.

Jadlog Pickup: offers Jadlog Pickup points (Jadlog service Pickup 40). It needs the API token. Default: No.

Pickup method name: the name before each Pickup point at checkout. Default: Jadlog Pickup. Required, at most 64 characters.

Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.

Api (Jadlog live prices)

Live prices are requested only for addresses in Brazil with a full 8-digit CEP.

API token: the Embarcador token from Jadlog. You can paste it with or without the word "Bearer". Leave it empty to use fixed prices only. Magento stores it encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved token, type a new value to change it. To delete the saved token, clear the field and click Save Config.

CNPJ / CPF: the CNPJ (14 digits) or CPF (11 digits) of the shipper registered in the Jadlog contract. Dots, slashes and dashes are allowed.

Current account: your Jadlog current account number (conta corrente). Without it and the CNPJ, Jadlog cannot quote and only fixed prices are used.

Contract number: your Jadlog contract number, if your franchise gave you one.

Origin CEP: the postal code the parcels are shipped from, 8 digits. It is saved in the format 00000-000. Leave it empty to use the postcode of the shipping origin (Stores > Configuration > Sales > Shipping Settings > Origin), but only when the origin country is Brazil.

Home delivery service: the service (modalidade) of your contract for home delivery: .Package (3, default), .Com (9), Expresso (0), Rodoviário (4), Econômico (5), Doc (6), Corporate (7), Internacional (10), Cargo (12) or Emergencial (14). Jadlog Pickup always uses the service Pickup (40).

Insurance: Normal (N) (default) or Additional (A), as agreed in your Jadlog contract.

Volumetric weight: Standard volumetric weight (default) or Do not use volumetric weight. Magento products have no standard dimensions, so the volumetric weight is not calculated and Jadlog is quoted by the actual cart weight with either option.

BRL exchange rate: Jadlog quotes in Brazilian reais. If the base currency of your store is BRL, this field is not needed. Otherwise enter how many units of the base currency 1 BRL is worth, for example 0.16. The Jadlog price is multiplied by this rate, and the declared order value sent to Jadlog is converted back to BRL. Without the rate live prices are not used and only fixed prices apply.

Show delivery time: adds the delivery time returned by Jadlog to the name of each Jadlog option at checkout, for example "3 business days". Default: Yes. The delivery time is always saved with the order.

Pickup points to show (1-10): how many Pickup points to offer. Default: 5.

Prices (fixed prices: used when there is no API token, for countries Jadlog does not serve, and whenever Jadlog returns no price)

Fixed prices are in the base currency of your store, tax excluded.

Country prices: a table with the columns Country, Base, XS, S, M, L and XL. Click Add country to add a row and Delete to remove one. The size column is chosen by cart weight: XS up to 1 kg, S up to 2 kg, M up to 3 kg, L up to 5 kg, XL above 5 kg. Base is used when the size column is empty or 0. Base 0 means free shipping for that country. Use * All other countries for all other countries. Rows without any price are removed when you save. If a country is listed twice, the first row is used.

Fallback cost: used when neither Jadlog nor the table gives a price. Leave it empty to hide the method in that case. 0 means free.

Price applies: Per order charges the price once. Per item (fixed prices only) multiplies it by the number of items that need shipping. Jadlog prices always cover the whole cart.

Conditions

Minimum weight (kg): hide Jadlog when the cart weighs less. 0 means no limit.

Maximum weight (kg): hide Jadlog when the cart weighs more. Default: 150. 0 or an empty field means no limit.

Minimum order amount: show Jadlog only when the cart subtotal reaches this amount. Leave empty to always show it.

Free shipping from: the cart subtotal from which delivery (home and Pickup) is free. No price request goes to Jadlog. Leave empty for no free shipping.

The subtotal is the amount of the products that need shipping, after discounts, before tax, in the base currency. Product weights are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs).

Ship to Applicable Countries: All Allowed Countries offers Jadlog for every country your store allows, Specific Countries (default) only for the countries below.

Ship to Specific Countries: the destination countries for Specific Countries. Default: Brazil. Live prices and Pickup points are for Brazil only; other countries use the fixed prices.

Advanced

Debug log: logs every Jadlog request and response to var/log/vfd_jdlg_debug.log.php in the Magento folder. The file cannot be opened from the web. API errors are always logged, even when this option is off. The token, CNPJ, account and contract are never logged and the customer CEP is shortened. Turn the log 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 deletes the Jadlog settings and the log (see Uninstall). The license key and the cached prices are always removed. The Jadlog data of placed orders is never deleted.

Shipping tax is not set in the module. If your store taxes shipping, Magento adds tax to the Jadlog price with the class in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping.

How it works at checkout

At the shipping step Magento asks the module for the Jadlog prices. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the subtotal. The module first checks the countries, the cart weight and Minimum order amount. If the cart subtotal reaches Free shipping from, delivery is free and no price request goes to Jadlog. A Magento cart price rule with free shipping also makes the price 0.

For a delivery address in Brazil with a full 8-digit CEP, the module sends Jadlog the origin and destination CEP, the weight, your CNPJ, current account, contract, service, insurance type and the declared order value. Carts without a weight are quoted as 0.1 kg. The returned price is converted to your base currency; Magento then shows it in the customer's currency and adds tax on shipping if your store charges it. If there is no live price (no token, an address outside Brazil, an incomplete CEP, no BRL exchange rate, a Jadlog error), the module uses the Country prices table, then the Fallback cost. If none of them gives a price, home delivery is hidden for that cart.

Each price is cached for 1 hour, so the same cart does not trigger a new request. A failed request is cached for 10 minutes. If Jadlog does not answer, returns a server error or rejects the token, the API is not called again for 10 minutes. The API timeout is 10 seconds. The customer never sees an API error. The reason is written to the log.

The module calculates prices and lists Pickup points only. It does not create Jadlog shipments, print labels, request collections, cancel shipments or track parcels. It does not show a map of Pickup points and does not request international quotes from Jadlog. Use fixed prices for other countries.

Pickup points

Jadlog Pickup is offered only for addresses in Brazil, and only when the API token is saved. When the customer has entered a full 8-digit CEP, the module asks Jadlog for the active Pickup points nearest to it and offers up to Pickup points to show points. Each point is a separate shipping option under the Jadlog carrier, in Jadlog's order, for example "Jadlog Pickup — point name — address — 3 business days", with its own price. The customer chooses a point by choosing its shipping option. There is no extra point list or map.

The price to each point is requested from Jadlog for the CEP of the point. If Jadlog gives no price for a point, the fixed price is used, and a point without any price is left out. Point lists are cached for 12 hours. Without an API token, without an 8-digit CEP, when Jadlog is unavailable or when there are no active points nearby, no Pickup options are shown. An order without a point could not be shipped.

When the customer continues from the shipping step and again when the order is placed, the module checks that the chosen service or point is still offered for the delivery address. If not, the customer sees This Jadlog service or Pickup point is no longer available. Please choose shipping again.

Orders

When an order is placed with Jadlog, the module saves the Jadlog service, the delivery time in business days (when Jadlog returned it) and, for Jadlog Pickup, the point's name, address and ID. The Jadlog service is added to the shipping description of the order, for example "Jadlog - Jadlog — Jadlog service: .Package (3)". For Jadlog Pickup the shipping description also contains the point's name and address, so the customer sees the point in the order in their account and in the order e-mails.

On the admin order page (Sales > Orders > View, Information tab) the Jadlog block shows Jadlog service, Delivery time and, for Jadlog Pickup, Pickup point, the point address and Pickup point ID. The block also works for older orders and when the module is switched off.

If a payment is cancelled and the cart is restored, the customer can place the order again with Jadlog. The earlier order keeps its own Jadlog data.

Book the shipment in the Jadlog system yourself. The order shows the service and the Pickup point ID you need for it.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Jadlog is the first row of the VibeFox Jadlog 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-jadlog 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 Jadlog options are not shown to customers at checkout and no price is calculated. The Magento storefront does not know that you are logged in to the Admin, so the options are 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

Jadlog does not appear at checkout: check that the license is active and Enable Jadlog is Yes for the website of the store, and that Home delivery or Jadlog Pickup is Yes. Check Ship to Applicable Countries and Ship to Specific Countries (Brazil only by default), the warnings in the Information row, the weight limits and Minimum order amount. If the customer has not entered a full 8-digit CEP yet, only fixed prices can be used, so add a Country prices row or a Fallback cost.

Only fixed prices are shown: turn on Debug log, reload the checkout and look at the Log field in the Advanced section. It shows the reason: no CNPJ or current account, no origin CEP, an incomplete destination CEP, no BRL exchange rate, or the Jadlog error message.

HTTP 401 or 403 in the log: Jadlog rejected the API token. Check it with your Jadlog franchise. The API is paused for 10 minutes after this error. Save Config clears the pause, so you can try again at once.

Pickup points do not appear: Jadlog Pickup needs Jadlog Pickup = Yes, the API token and a full 8-digit CEP in Brazil. If Jadlog has no active points near the CEP, no Pickup options are shown. Check the log for the reason.

Prices are in reais instead of my currency: enter the BRL exchange rate (how many units of your base currency 1 BRL is worth).

Prices look too low or too high: fill in product weights and check the weight unit of your store. Carts without a weight are quoted as 0.1 kg.

Tax is added to Jadlog prices: Jadlog prices are final carrier prices. Do not tax shipping in Tax Class for Shipping if Magento must not add tax to them.

Prices look outdated after a change: click Save Config on the Delivery Methods page. This clears the cached Jadlog prices and Pickup point lists.

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.

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_JadlogShipping. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_JadlogShipping to remove the data, then bin/magento module:disable Vibefox_JadlogShipping, delete the folder app/code/Vibefox/JadlogShipping and run bin/magento setup:upgrade.

The license key, the license status and the cached prices and Pickup point lists are always removed. If Remove data on uninstall is Yes, the Jadlog settings and the log are removed too. If it is No, the settings are kept for a re-install. The Jadlog service, delivery time and Pickup point saved with orders are always kept.

Jadlog is a trademark of its respective owner. This module is not affiliated with or endorsed by Jadlog.