VibeFox Jadlog for OpenCart — 帮助

系统要求

OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。

PHP：8.0 或更高版本。

Jadlog 合同（用于实时运费和取件点）：实时运费和取件点列表来自 Jadlog Embarcador API。签订合同后，您的 Jadlog 特许经营商会为您开通访问权限。您需要 Embarcador API 令牌、合同中登记的发件人 CNPJ（或 CPF）、结算账户（conta corrente），以及合同编号（如有）。如果您只使用固定运费，则不需要 Jadlog 合同。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只适用于一个域名。

安装

下载文件是一个 zip 压缩包，包含两个 OpenCart 版本的安装包。请先在电脑上解压。其中包含 README.txt、OpenCart 3 安装包 vfd_jadlog-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_jadlog.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。

OpenCart 3

1. 在后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_jadlog-oc3-(version).ocmod.zip。本扩展不添加任何 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，直接将本安装包中 upload 文件夹的内容复制到商店的根目录。

2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Jadlog，点击 Install（绿色 + 按钮）。

3. 点击 Edit（铅笔按钮）打开设置页面。

4. 在 Edit 页面顶部许可证区块的 License key 栏中输入您的 VibeFox 许可证密钥，然后点击 Activate（参见“许可证密钥”）。

5. 粘贴 API 令牌，输入 CNPJ、结算账户、合同编号和发货 CEP，选择 Jadlog 服务；如果商店的默认货币不是 BRL，请输入 BRL 汇率。如需要，可添加固定运费或备用费用（参见“配置”）。

6. 开启 Enable Jadlog home delivery、Enable Jadlog Pickup，或两者都开启，然后点击 Save。

OpenCart 4

1. 在后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_jadlog.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包无法使用。

2. 安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。

3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Jadlog，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。

4. 按照 OpenCart 3 的第 4 至第 6 步输入许可证密钥和设置。两个版本的设置页面及其字段相同。

安装后，两个选项都保持关闭，直到您开启并保存。如果您在卸载后重新安装扩展，之前保留的 Jadlog 设置将再次生效。

配置

所有设置都在扩展页面中：Extensions > Extensions > Shipping > VibeFox Jadlog > Edit。这些设置同时适用于两个 Jadlog 选项。各部分列在左侧。点击一次 Save 即可保存整个页面，无需刷新。每次保存还会清除缓存的 Jadlog 价格和取件点列表。只有对本扩展拥有修改权限的管理员用户才能保存设置。

页面顶部，扩展会针对不完整的设置显示警告：没有 API 令牌（只使用固定运费，无法列出取件点）；没有 API 令牌且没有固定运费（该方式永远不会显示）；没有 CNPJ 或结算账户；没有发货 CEP；商店不以 BRL 销售却没有 BRL 汇率；商店中没有重量等级“kg”或长度等级“cm”（此时将按其等级的单位名称换算重量和尺寸；请检查 System > Localisation > Weight Classes 和 Length Classes）。

保存时，两个选项中任一标题无效（为空、超过 64 个字符或包含 < > ; = # { }）、Sort order 不是整数，或税务类别或地理区域不存在，都会导致保存失败并显示错误。其他错误值会以提示的形式保存在设置上方：无效或小于 0 的数字不会保存；最小重量大于最大重量时，保留两个已保存的重量；不是正数的 BRL 汇率会被清除；不足 8 位的 CEP 或不足 14 位的 CNPJ（CPF 为 11 位）会按输入内容保存并给出警告；价格表中国家未知的行会被删除，无效价格则留空。

常规

Jadlog 有两种配送选项：Jadlog home delivery（本部分）和 Jadlog Pickup（独立部分）。本页面的设置同时适用于两者。

Enable Jadlog home delivery：使用下方选择的服务，向顾客的地址提供 Jadlog 配送。默认：off。

Method title：结账时显示给顾客的送货上门选项名称。默认：Jadlog。必填，最多 64 个字符。

Sort order：Jadlog 在结账时配送方式中的排列位置。整数。

Tax class：配送费用的税务类别，或 No tax（默认）。Jadlog 价格是最终的承运商价格。如果您不希望 OpenCart 对其加税，请选择 No tax。此设置适用于两个选项。

Jadlog 实时运费

仅当地址位于巴西且邮政编码为完整的 8 位时，才会请求实时运费。

API token：Jadlog 提供的 Embarcador 令牌。您可以带或不带“Bearer”一词进行粘贴。留空则仅使用固定运费。保存后，该字段保持为空，并显示 Saved - leave empty to keep it. 只有需要更改时才输入新值。如果没有保存令牌，页面会显示 No token saved.

Remove the saved API token：勾选后点击 Save，即可删除已保存的令牌。

CNPJ：Jadlog 合同中登记的发件人 CNPJ（14 位）或 CPF（11 位），例如 00.000.000/0000-00。

Current account (conta corrente)：您的 Jadlog 结算账户号码。如果没有该号码，且没有 CNPJ，Jadlog 无法报价，只会使用固定运费。

Contract number：如果特许经营商为您提供了合同编号，请在此填写您的 Jadlog 合同编号。

Origin CEP：包裹的发货邮政编码，8 位（00000-000）。获取实时运费时必填：OpenCart 没有商店邮政编码，因此若不填写此字段，将只使用固定运费。

Jadlog service：您合同中送货上门的服务（modalidade）：.Package（3，默认）、.Com（9）、Expresso（0）、Rodoviário（4）、Econômico（5）、Doc（6）、Corporate（7）、Internacional（10）、Cargo（12）或 Emergencial（14）。Jadlog Pickup（40）是第二个选项。

Insurance type：根据您的 Jadlog 合同约定，选择 Normal (N)（默认）或 Own insurance policy (A - apolice)。

Volumetric weight：Jadlog 按实际重量与体积重量中较大者计费。

BRL exchange rate：Jadlog 以巴西雷亚尔报价。如果商店默认货币是 BRL，则无需此字段。否则，请输入 1 BRL 等于多少您的默认货币，例如 0.16。Jadlog 价格将乘以该汇率，发送给 Jadlog 的订单声明价值则会换算回 BRL。没有汇率时，不使用实时运费，只适用固定运费。

Delivery time：在结账时，在送货上门标题旁以及每个取件点旁显示 Jadlog 返回的配送时间（例如“Jadlog (3 business days)”）。默认开启。配送时间始终与订单一起保存。

Jadlog Pickup

第二个配送选项，使用 Jadlog Pickup（40）服务。需要 API 令牌。没有取件点时，该选项会被隐藏。

Enable Jadlog Pickup：提供配送至结账时选择的 Jadlog Pickup 取件点。默认：off。

Jadlog Pickup title：该选项在结账时的名称。默认：Jadlog Pickup。必填，最多 64 个字符。

Points to show：提供多少个取件点，范围 1 到 10。默认：5。

固定运费（在没有 API 令牌、Jadlog 不服务的国家，以及 Jadlog 未返回价格时使用）

Price per country：以商店默认货币表示，包含 Country、Price、XS、S、M、L 和 XL 列的表格。点击 Add country 添加一行，点击 × 按钮删除一行。尺寸列根据购物车重量选择：XS 最多 1 kg，S 最多 2 kg，M 最多 3 kg，L 最多 5 kg，XL 超过 5 kg。尺寸列为空时使用 Price。价格为 0 表示该国家免运费。对于其他所有国家，请使用 * Default (other countries)。

Fallback cost：当 Jadlog 和表格都不能提供价格时使用。留空则在这种情况下隐藏该方式。

Fixed price applies：Per order（默认）只收取一次价格。Per item (price x quantity) 则乘以购物车中的商品数量。此设置仅适用于固定运费和备用费用。Jadlog 价格已涵盖整个购物车。

条件

Minimum weight (kg)：低于此购物车重量时隐藏该方式。0 表示无限制（默认）。

Maximum weight (kg)：高于此购物车重量时隐藏该方式。默认：150。0 表示无限制。

Minimum order amount：仅当需要配送的商品小计（优惠券折扣后、税前）达到此金额时才显示该方式。留空则始终显示。

Free shipping from：小计（优惠券折扣后、税前）达到此金额时免运费。留空则不提供免运费。

可用性

Geo zone：仅向此地理区域内的地址提供 Jadlog。All zones（默认）表示无限制。开启 Ignore shipping zones 时不检查地理区域。地理区域在 System > Localisation > Geo Zones 中管理。

Ignore shipping zones：开启时，不检查 Geo zone，并且 Jadlog 将提供给下方列出的国家。关闭时（默认），仅应用 Geo zone。

Countries：该模式下的目的地国家。留空则允许所有国家。仅当 Ignore shipping zones 开启时使用此字段。

高级

Debug log：将每次 Jadlog 请求和响应记录到 storage/logs/vfd_jdlg_debug.log.php（OpenCart 4 中为 system/storage/logs/vfd_jdlg_debug.log.php）。该文件无法通过网页读取。API 错误以及没有取件点的 Jadlog Pickup 订单，即使此选项关闭也始终会被记录。令牌、CNPJ 和账户绝不会被记录，顾客的 CEP 会被缩短。完成后请关闭日志。

Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。

Remove data on uninstall：开启时，卸载扩展会删除所有 Jadlog 设置、日志，以及从未形成订单的结账中的取件点选择。关闭时（默认），设置会保留，以便重新安装。缓存的价格始终会被删除。订单中的 Jadlog 数据永远不会被删除。

导入 / 导出

Export：点击 Download JSON，将设置保存为 JSON 文件。API 令牌不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import，即可恢复设置，例如在另一个商店中使用。这些值的检查方式与正常保存相同。已保存的 API 令牌会被保留。

结账时的工作方式

OpenCart 显示配送方式时，会向扩展请求每个 Jadlog 选项的价格：送货上门和 Jadlog Pickup 作为两个选项显示在同一个 Jadlog 方式下。开启 Ignore shipping zones 时，只有在允许该国家的情况下才提供 Jadlog（不检查地理区域）。否则，如果设置了 Geo zone 且地址不在其中，则不提供 Jadlog。只有 Requires Shipping 设为 Yes 的商品才会计入：其他商品不增加重量，也不计入订单金额。订单金额是需要配送的商品的价格，扣除优惠券折扣后、税前。扩展会检查购物车重量和最低订单金额。如果小计达到 Free shipping from，则免费配送，并且不会向 Jadlog 发送价格请求。

对于位于巴西且邮政编码为完整 8 位的收货地址，扩展会向 Jadlog 发送发货和目的地 CEP、重量、您的 CNPJ、结算账户、合同、服务、保险类型以及订单声明价值。商品重量会从其 OpenCart 重量等级换算为 kg，尺寸会从其长度等级换算为 cm。没有重量的购物车按 0.1 kg 报价。返回的价格会换算为您的默认货币，按其小数位数取整，并以顾客的货币显示，同时包含所选 Tax class 的税款。如果没有实时价格（无令牌、地址不在巴西、CEP 不完整、没有 BRL 汇率、Jadlog 出错），扩展会使用 Price per country 表格，然后使用 Fallback cost。如果都不能提供价格，则该购物车将隐藏此选项。

每个价格缓存 1 小时，因此相同的购物车不会触发新的请求。失败的请求缓存 10 分钟。如果 Jadlog 无响应、返回服务器错误或拒绝令牌，则 10 分钟内不会再次调用 API。API 超时时间为 10 秒。顾客永远不会看到 API 错误，原因会写入日志。

在 OpenCart 4 中，顾客在结账页面的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择一个 Jadlog 选项。价格与 OpenCart 3 相同。

扩展仅计算价格并列出取件点。它不创建 Jadlog 运单、不打印面单、不申请上门取件、不取消运单，也不追踪包裹。它不显示取件点地图，也不向 Jadlog 请求国际报价。其他国家请使用固定运费。

取件点

只有在地址位于巴西、已开启 Enable Jadlog Pickup 且已保存 API 令牌时，才会提供 Jadlog Pickup 选项。顾客输入完整的 8 位 CEP 后，扩展会向 Jadlog 请求离其最近的有效取件点，并在该选项下列出最多 Points to show 个取件点，每个都带有价格，例如“取件点名称 — 价格（3 business days）— 地址”。如果列表尚未缓存，则会在顾客选择 Jadlog Pickup 时在后台加载，因此配送方式步骤不必等待 Jadlog。

每个取件点的价格都从 Jadlog 请求获得。如果 Jadlog 没有为某个取件点提供价格，则使用固定价格；没有任何价格的取件点会被排除。取件点列表缓存 12 小时。选项价格为所选取件点的价格。在选择取件点之前，显示的是有价格的最近取件点的价格。顾客选定取件点后，Jadlog Pickup 旁显示的价格会更新。

必须选择取件点。顾客在配送方式步骤中未选择取件点就点击 Continue 时，会看到 Please select a Jadlog Pickup point. 扩展会在服务器端检查该取件点是否存在于配送 CEP 的 Jadlog 列表中。如果不存在，顾客会看到 The selected Jadlog Pickup point is not in the Jadlog list for this CEP. Please choose the point again. 如果 CEP 不完整、附近没有取件点或 Jadlog 不可用，则会在该选项下方显示提示信息。

没有 API 令牌、Jadlog 不可用或附近没有有效取件点时，Jadlog Pickup 选项会被隐藏。没有取件点的订单将无法发货。

在 OpenCart 4 中，取件点列表显示在 Shipping method options 窗口中，位于 Jadlog Pickup 选项下方。列表在后台加载，先从缓存读取，然后再从 Jadlog 获取其他取件点的价格。顾客选择取件点后，窗口中 Jadlog Pickup 旁的价格会更新。窗口中的 Continue 按钮在未选择有效取件点时不会继续，并显示相同的提示信息。

订单

使用 Jadlog 选项下单时，扩展会保存 Jadlog 服务，并且（若 Jadlog 返回了该信息）保存以工作日计的配送时间。对于 Jadlog Pickup 订单，还会保存取件点的名称、地址和 ID。在 OpenCart 4 中，结账时只保留一个订单，顾客每次重新确认时都会更新该订单，订单中的 Jadlog 数据也随之更新。如果顾客将该订单改为其他配送方式，其 Jadlog 数据会被删除。

取件点会在选项标题之后添加到订单的配送方式中，例如 Jadlog Pickup:，后面跟着取件点名称和地址。此文本会出现在后台和顾客账户中的订单页面上，以及订单电子邮件和发票中。

管理员订单页面（Sales > Orders）会显示 Jadlog 面板，包含 Jadlog service、Delivery time，以及 Jadlog Pickup 的 Pickup point、Pickup point address 和 Pickup point ID。在 OpenCart 4 中，该面板显示在 History 上方。

请自行在 Jadlog 系统中预订运单。订单会显示您所需的服务和取件点 ID。

许可证密钥

本扩展使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Jadlog 是 Extensions > Extensions > Shipping > VibeFox Jadlog > Edit 页面中的第一个区块，位于设置上方。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会显示隐藏后的密钥、许可证状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店移除密钥）。其下方是 Product: opencart-shipping-jadlog 一行和 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有对本扩展拥有修改权限的管理员用户才能更改密钥。该区块的文字跟随后台语言显示（包括英文和俄文）。

如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带日期的 License expired on。商店地址变更后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展将继续按最后已知的状态运行。

一个密钥只适用于一个域名：即 OpenCart 配置中的商店地址。从商店中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效密钥时，结账时不会向顾客显示 Jadlog 配送选项，也不计算运费。在同一浏览器中登录后台的管理员仍可在商店中看到这些选项，并标记为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试本扩展。在 OpenCart 4 中此预览不可用：商店无法识别后台登录状态，因此没有有效密钥时，所有人都看不到 Jadlog 选项。打开过一次 Edit 页面后，后台 Dashboard 会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响。

许可证到期后，扩展仍会继续运行，但更新和支持需要续费。打开后台 Dashboard 或 Edit 页面时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时，许可证密钥和许可证状态始终会被删除。

故障排除

Jadlog 在结账时未出现：请检查许可证是否有效，以及 Enable Jadlog home delivery（或 Enable Jadlog Pickup）是否已开启。检查 Geo zone，或开启 Ignore shipping zones 并检查 Countries。检查扩展页面顶部的警告、重量限制、Minimum order amount，并确认商品的 Requires Shipping 设为 Yes。如果顾客尚未输入完整的 8 位 CEP，则只能使用固定运费，因此请添加 Price per country 行或 Fallback cost。

只显示固定运费：开启 Debug log，重新加载结账页面，并查看扩展页面的 Log 字段。该字段会显示原因：没有 CNPJ 或结算账户、没有发货 CEP、目的地 CEP 不完整、没有 BRL 汇率，或 Jadlog 的错误信息。

日志中出现 HTTP 401 或 403：Jadlog 拒绝了 API 令牌。请向您的 Jadlog 特许经营商核实。此错误发生后，API 将暂停 10 分钟。保存设置会清除暂停状态，因此您可以立即重试。

取件点不显示：Jadlog Pickup 选项需要开启 Enable Jadlog Pickup、API 令牌，以及巴西的完整 8 位 CEP。如果 Jadlog 在该 CEP 附近没有有效取件点，该选项会被隐藏。请查看日志了解原因。

价格以雷亚尔显示，而不是我的货币：请输入 BRL exchange rate（1 BRL 等于商店默认货币的多少）。

价格看起来过低或过高：请填写商品重量和尺寸。没有重量的购物车按 0.1 kg 报价，而体积重量需要尺寸。

Jadlog 价格被加上了税：将 Tax class 设为 No tax。

修改后价格仍显示旧数据：请在扩展页面点击 Save。这会清除缓存的 Jadlog 价格和取件点列表。

页面显示“Warning: You do not have permission to modify VibeFox Jadlog!”：您的管理员用户组可能只能查看设置。请在 System > Users > User Groups 中为该组授予 extension/shipping/vfd_jadlog（OpenCart 3）或 extension/vfd_jadlog/shipping/vfd_jadlog（OpenCart 4）的修改权限。

卸载

进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox Jadlog 旁边的 Uninstall（红色 − 按钮）。许可证密钥和该扩展的许可证状态始终会被删除。OpenCart 始终会重置扩展状态、Sort order、Tax class 和 Geo zone。缓存的价格和取件点列表始终会被删除。如果开启了 Remove data on uninstall，Jadlog 设置和日志也会被删除。如果关闭，其他设置会保留，并在您重新安装扩展时再次使用。订单中保存的 Jadlog 服务、配送时间和取件点始终保留，现有订单保留其配送方式和费用。

在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Jadlog 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。

Jadlog 是其所有者的商标。本扩展与 Jadlog 无关联，也未获得 Jadlog 认可。