VibeFox Jadlog for OpenCart — Help
Requirements
OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).
PHP: 8.0 or later.
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 download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package vfd_jadlog-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_jadlog.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.
OpenCart 3
1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_jadlog-oc3-(version).ocmod.zip. The extension adds no OCMOD modifications, so you do not need to refresh Extensions > Modifications. Instead of the Installer, you can copy the contents of the upload folder of this package into the root folder of your store.
2. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox Jadlog and click Install (the green + button).
3. Click Edit (the pencil button) to open the settings page.
4. Paste your VibeFox license key into License key in the license block at the top of the Edit page and click Activate (see License key).
5. Paste the API token, enter the CNPJ, current account, contract number and origin CEP, choose the Jadlog service and, if your store default currency is not BRL, enter the BRL exchange rate. Add fixed prices or a fallback cost if you want them (see Configuration).
6. Turn on Enable Jadlog home delivery, Enable Jadlog Pickup or both, and click Save.
OpenCart 4
1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_jadlog.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.
2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.
3. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox Jadlog, click Install (the green + button), then Edit (the pencil button).
4. Enter the license key and the settings as in steps 4 to 6 for OpenCart 3. The settings page and its fields are the same in both versions.
After install both options are off until you turn them on and save. If you install the extension again after an uninstall, the Jadlog settings you kept are used again.
Configuration
All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox Jadlog > Edit. They apply to both Jadlog options. The sections are listed on the left. One Save button saves the whole page without reloading it. Every save also clears the cached Jadlog prices and Pickup point lists. Only admin users with the modify permission for this extension can save the settings.
At the top of the page the extension 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 (the method is never shown), no CNPJ or current account, no origin CEP, no BRL exchange rate for a store that does not sell in BRL, and no weight class "kg" or length class "cm" in the store (then weights and dimensions are converted by the unit name of their class; check System > Localisation > Weight Classes and Length Classes).
When you save, an invalid title of either option (empty, longer than 64 characters or with < > ; = # { }), a Sort order that is not a whole number, or a tax class or geo zone that does not exist stops the save with an error. Other wrong values are saved with a remark above the settings: a number that is not valid or is below 0 is not saved, a minimum weight above the maximum weight keeps both saved weights, a BRL exchange rate that is not a positive number is cleared, a CEP without 8 digits or a CNPJ without 14 digits (or 11 for a CPF) is saved as typed with a warning, and in the price table a row with an unknown country is removed and an invalid price is left empty.
General
Jadlog has two delivery options: Jadlog home delivery (this section) and Jadlog Pickup (its own section). The settings on this page apply to both.
Enable Jadlog home delivery: offers Jadlog delivery to the customer's address with the service chosen below. Default: off.
Method title: the name of the home delivery option shown to the customer at checkout. Default: Jadlog. Required, up to 64 characters.
Sort order: the position of Jadlog among the shipping methods at checkout. A whole number.
Tax class: the tax class of the shipping cost, or No tax (default). Jadlog prices are final carrier prices. Choose No tax if OpenCart must not add tax to them. It applies to both options.
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. After saving, the field stays empty and shows Saved - leave empty to keep it. Type a new value only to change it. When no token is saved, the page shows No token saved.
Remove the saved API token: tick it and click Save to delete the saved token.
CNPJ: the CNPJ (14 digits) or CPF (11 digits) of the shipper registered in the Jadlog contract, for example 00.000.000/0000-00.
Current account (conta corrente): your Jadlog current account number. 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 (00000-000). Required for live prices: OpenCart has no store postcode, so without this field only fixed prices are used.
Jadlog 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 (40) is the second option.
Insurance type: Normal (N) (default) or Own insurance policy (A - apolice), as agreed in your Jadlog contract.
Volumetric weight: Jadlog charges the greater of the real and the volumetric weight.
BRL exchange rate: Jadlog quotes in Brazilian reais. If your store default currency is BRL, this field is not needed. Otherwise enter how much 1 BRL is in your default currency, 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.
Delivery time: shows the delivery time returned by Jadlog at checkout, next to the home delivery title (for example "Jadlog (3 business days)") and next to each Pickup point. On by default. The delivery time is always saved with the order.
Jadlog Pickup
A second delivery option with the Jadlog service Pickup (40). It needs the API token. Without points the option is hidden.
Enable Jadlog Pickup: offers delivery to a Jadlog Pickup point chosen at checkout. Default: off.
Jadlog Pickup title: the name of this option at checkout. Default: Jadlog Pickup. Required, up to 64 characters.
Points to show: how many Pickup points to offer, from 1 to 10. Default: 5.
Fixed prices (used when there is no API token, for countries Jadlog does not serve, and whenever Jadlog returns no price)
Price per country: a table with the columns Country, Price, XS, S, M, L and XL, in your store default currency. Click Add country to add a row and the × button 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. Price is used when the size column is empty. Price 0 means free shipping for that country. Use * Default (other countries) for all other countries.
Fallback cost: used when neither Jadlog nor the table gives a price. Leave it empty to hide the method in that case.
Fixed price applies: Per order (default) charges the price once. Per item (price x quantity) multiplies it by the number of items in the cart. This applies only to fixed prices and the fallback cost. Jadlog prices already cover the whole cart.
Conditions
Minimum weight (kg): hide the method below this cart weight. 0 means no limit (default).
Maximum weight (kg): hide the method above this cart weight. Default: 150. 0 means no limit.
Minimum order amount: show the method only when the subtotal of the products that need shipping (after the coupon, before tax) reaches this amount. Leave it empty to always show it.
Free shipping from: the subtotal (after the coupon, before tax) from which delivery is free. Leave it empty for no free shipping.
Availability
Geo zone: offer Jadlog only for addresses in this geo zone. All zones (default) means no limit. The geo zone is not checked when Ignore shipping zones is on. Geo zones are managed in System > Localisation > Geo Zones.
Ignore shipping zones: when on, the Geo zone is not checked and Jadlog is offered for the countries below. When off (default), only the Geo zone applies.
Countries: the destination countries for that mode. Leave it empty to allow all countries. This field is used only when Ignore shipping zones is on.
Advanced
Debug log: logs every Jadlog request and response to storage/logs/vfd_jdlg_debug.log.php (on OpenCart 4 system/storage/logs/vfd_jdlg_debug.log.php). The file cannot be read from the web. API errors and Jadlog Pickup orders without a point are always logged, even when this option is off. The token, CNPJ and account 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 on, uninstalling the extension deletes all Jadlog settings, the log and the point choices of checkouts that never became orders. When off (default), the settings are kept for a re-install. Cached prices are always removed. The Jadlog data of orders is never deleted.
Import / Export
Export: click Download JSON to save the settings as a JSON file. The API token is not exported.
Import: paste previously exported JSON and click Import to restore the settings, for example on another store. The values are checked like a normal save. The saved API token is kept.
How it works at checkout
When OpenCart shows the shipping methods, it asks the extension for the price of each Jadlog option: home delivery and Jadlog Pickup appear as two choices under one Jadlog method. With Ignore shipping zones on, Jadlog is offered only when the country is allowed (the geo zone is not checked). Otherwise, if a Geo zone is set and the address is outside it, Jadlog is not offered. Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the order amount. The order amount is the price of the products that need shipping, after the coupon discount and before tax. The extension checks the cart weight and minimum order amount. If the subtotal reaches Free shipping from, delivery is free and no price request goes to Jadlog.
For a delivery address in Brazil with a full 8-digit CEP, the extension sends Jadlog the origin and destination CEP, the weight, your CNPJ, current account, contract, service, insurance type and the declared order value. Product weights are converted from their OpenCart weight class to kg and dimensions from their length class to cm. Carts without a weight are quoted as 0.1 kg. The returned price is converted to your default currency, rounded to its decimals, and shown in the customer's currency with the tax of the selected Tax class. If there is no live price (no token, an address outside Brazil, an incomplete CEP, no BRL exchange rate, a Jadlog error), the extension uses the Price per country table, then the Fallback cost. If none of them gives a price, the option 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.
On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks a Jadlog option in the window Shipping method options. The prices are the same as on OpenCart 3.
The extension 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
The Jadlog Pickup option is offered only for addresses in Brazil, and only when Enable Jadlog Pickup is on and the API token is saved. When the customer has entered a full 8-digit CEP, the extension asks Jadlog for the active Pickup points nearest to it and lists up to Points to show points under the option, each with its price, for example "point name — price (3 business days) — address". If the list is not cached yet, it is loaded in the background when the customer selects Jadlog Pickup, so the delivery method step does not wait for Jadlog.
The price to each point is requested from Jadlog. 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. The option price is the price of the chosen point. Before a point is chosen, it is the price of the nearest point that has a price. After the customer chooses a point, the price shown next to Jadlog Pickup is updated.
A point is required. When the customer clicks Continue in the delivery method step without a point, they see Please select a Jadlog Pickup point. The extension checks on the server that the point is in the Jadlog list for the delivery CEP. If not, the customer sees The selected Jadlog Pickup point is not in the Jadlog list for this CEP. Please choose the point again. When the CEP is incomplete, there are no points nearby or Jadlog is unavailable, a message is shown under the option.
Without an API token, when Jadlog is unavailable or when there are no active points nearby, the Jadlog Pickup option is hidden. An order without a point could not be shipped.
On OpenCart 4 the list of Pickup points appears in the window Shipping method options, under the Jadlog Pickup option. It is loaded in the background, first from the cache and then with the prices of the other points from Jadlog. After the customer chooses a point, the price next to Jadlog Pickup in the window is updated. The Continue button of the window does not go on without a valid point, with the same messages.
Orders
When an order is placed with a Jadlog option, the extension saves the Jadlog service and, when Jadlog returned it, the delivery time in business days. For a Jadlog Pickup order it also saves the Pickup point name, address and ID. OpenCart 4 keeps one order for the checkout and updates it each time the customer confirms again, and the Jadlog data of the order is updated with it. If the customer switches that order to another shipping method, its Jadlog data is removed.
The point is added to the shipping method of the order after the option title, for example Jadlog Pickup: followed by the point name and address. This text appears on the order pages in the admin and in the customer account, in the order e-mails and on the invoice.
The admin order page (Sales > Orders) shows a Jadlog panel with Jadlog service, Delivery time and, for Jadlog Pickup, Pickup point, Pickup point address and Pickup point ID. On OpenCart 4 the panel is shown above History.
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 extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Jadlog is the first block on Extensions > Extensions > Shipping > VibeFox Jadlog > Edit, 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: opencart-shipping-jadlog and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin language (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 extension keeps working on the last known status.
One key works on one domain: the store address from the OpenCart configuration. 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 shipping options are not shown to customers at checkout and no rate is calculated. An admin user who is logged in to the admin in the same browser still sees them in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the Jadlog options are hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected.
When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension always removes the license key and license status.
Troubleshooting
Jadlog does not appear at checkout: check that the license is active and Enable Jadlog home delivery (or Enable Jadlog Pickup) is on. Check Geo zone, or turn on Ignore shipping zones and check Countries. Check the warnings at the top of the extension page, the weight limits, Minimum order amount and that the products have Requires Shipping set to Yes. If the customer has not entered a full 8-digit CEP yet, only fixed prices can be used, so add a Price per country row or a Fallback cost.
Only fixed prices are shown: turn on Debug log, reload the checkout and look at the Log field on the extension page. 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. Saving the settings clears the pause, so you can try again at once.
Pickup points do not appear: the Jadlog Pickup option needs Enable Jadlog Pickup, the API token and a full 8-digit CEP in Brazil. If Jadlog has no active points near the CEP, the option is hidden. Check the log for the reason.
Prices are in reais instead of my currency: enter the BRL exchange rate (how much 1 BRL is in your store default currency).
Prices look too low or too high: fill in product weights and dimensions. Carts without a weight are quoted as 0.1 kg, and the volumetric weight needs dimensions.
Tax is added to Jadlog prices: set Tax class to No tax.
Prices look outdated after a change: click Save on the extension page. This clears the cached Jadlog prices and Pickup point lists.
The page says "Warning: You do not have permission to modify VibeFox Jadlog!": your admin user group may only view the settings. Give the group the modify permission for extension/shipping/vfd_jadlog (OpenCart 3) or extension/vfd_jadlog/shipping/vfd_jadlog (OpenCart 4) in System > Users > User Groups.
Uninstall
Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox Jadlog. The license key and license status of this extension are always removed. OpenCart always resets the extension status, Sort order, Tax class and Geo zone. The cached prices and Pickup point lists are always removed. If Remove data on uninstall is on, the Jadlog settings and the log are deleted as well. If it is off, the other settings are kept and are used again when you install the extension again. The Jadlog service, delivery time and Pickup point saved with orders are always kept, and existing orders keep their shipping method and cost.
On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox Jadlog in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.
Jadlog is a trademark of its respective owner. This extension is not affiliated with or endorsed by Jadlog.