VibeFox J&T Express for OpenCart — 帮助
要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
J&T Express Malaysia API 权限（仅用于实时报价）：实时报价仅适用于 J&T Express Malaysia，且仅适用于马来西亚的配送地址。您需要四个值。请在 J&T Express Malaysia 网站上申请 J&T VIP 账户（扩展页面中有链接）：J&T 会提供 VIP 客户代码和 VIP API 密钥。API 账户以及用于签署请求的私钥由 J&T 为 API 集成而发放。请向您的 J&T 客户经理索取。J&T 菲律宾、印度尼西亚和其他国家没有公开的报价 API，因此请对这些国家使用价格表。如果您只使用价格表和备用费用，则无需 J&T API 权限。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请将其解压到您的计算机上。压缩包中包含 README.txt、OpenCart 3 安装包 vfd_jt_express-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_jt_express.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。
OpenCart 3
1. 在后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_jt_express-oc3-(version).ocmod.zip。该扩展不添加任何 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用 Installer，而是将本安装包中 upload 文件夹的内容复制到商店的根目录。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox J&T Express，点击 Install（绿色的 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥粘贴到 License key 中，然后点击 Activate（参见许可证密钥）。
5. 填写价格表和/或备用费用。如需马来西亚实时报价，还需填写 J&T API 凭据、发件邮编，如果商店默认货币不是 MYR，还需填写货币换算汇率（参见 Configuration）。开启 Enable J&T Express 并点击 Save。
OpenCart 4
1. 在后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_jt_express.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名中获取扩展代码，重命名后的安装包无法工作。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色的 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox J&T Express，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 的第 4 和第 5 步输入许可证密钥和设置。两个版本的设置页面及其字段完全相同。
安装后，在您开启 Enable J&T Express 并保存之前，该配送方式处于关闭状态。如果您卸载后重新安装该扩展，将重新使用您保留的 J&T Express 设置。
设置
所有设置都在扩展页面中：Extensions > Extensions > Shipping > VibeFox J&T Express > Edit。各分区列在左侧。页面底部的一个 Save 按钮可保存整个页面，无需重新加载。每次保存还会清除缓存的 J&T 报价。如果某个值有误，则不会保存任何内容，页面会显示原因：配送方式标题无效、金额不是 0 或更大的数字、Currency conversion rate 为 0、Min weight (kg) 大于 Max weight (kg)，或排序不是整数。只有对该扩展拥有修改权限的管理员用户才能保存设置。
设置上方的警告（每次保存后都会再次显示）会提示实时报价是否仅部分配置：它们会列出缺失的 API 设置，或说明您的商店货币不是 MYR 且缺少换算汇率。如果您的商店在 System > Localisation > Weight Classes 中没有单位为 kg 的重量类别，还会出现另一条警告。此时，商品重量将按其单位名称（kg、g、lb、oz）换算，其他单位按 kg 处理。
常规
该配送方式会提供给所选的地理区域，或 Ignore shipping zones 中的国家。本页的设置适用于所有区域。
Enable J&T Express：在结账时显示或隐藏该配送方式（即本扩展的状态）。默认：关闭。
Method title：顾客在购物车和结账时看到的配送方式名称。默认：J&T Express。必填，最多 64 个字符，且不能包含字符 < > ; = # { }。
Tax class：运费的税类，或 No tax（默认）。税类会在运费上加收您的运费税。如果 J&T 价格已包含您想收取的全部费用，请选择 No tax。
Sort order：该配送方式在结账时的配送方式列表中的位置。整数。
J&T Express Malaysia API（实时报价）（可选，适用于马来西亚配送地址；四项凭据均为必填）
每个马来西亚邮编都会向 J&T Express Malaysia 请求报价，并缓存一小时。若未填写凭据，或针对其他国家，则使用价格表和备用费用。
VIP customer code：您的 J&T Express VIP 代码。清空它也会清除已保存的 VIP API 密钥。
VIP API key：J&T Express 随 VIP 代码提供给您的 API 密钥（密码）。它绝不会写入日志。保存后，该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。若要删除，请清空 VIP customer code 并保存。
API account：您的 J&T Express API 账户名称。清空它也会清除已保存的私钥。
API private key：API 账户的私钥。它仅用于签署请求（SHA-256）。它绝不会发送给 J&T，也不会写入日志。与 VIP API 密钥一样，保存后不会再次显示。若要删除，请清空 API account 并保存。
Sender postcode：包裹寄出的马来西亚邮编，例如 50000。实时报价必填：OpenCart 中的商店地址为自由文本，因此绝不会从中提取邮编。
Currency conversion rate：J&T Express Malaysia 的报价以 MYR 计价。如果您的商店默认货币不是 MYR，请输入 1 MYR 等于您的货币多少单位（1 MYR = X），例如 0.20。如果没有此值，则不使用实时报价，而改用价格表或备用费用。如果您的默认货币是 MYR，该字段会注明，无需填写：直接使用报价。汇率必须大于 0。
价格表和备用（用于马来西亚以外的国家，当实时报价未配置或 J&T 未给出报价时使用；价格以商店默认货币计算，不含税）
Country prices：一个每个国家一行的表格。点击 Add country 添加一行，点击删除按钮删除一行。选择 * Any other country 可用于所有没有单独行的国家。每行包含一个 Base price 和五个重量档位：XS 最高 1 kg，S 最高 2 kg，M 最高 3 kg，L 最高 5 kg，XL 超过 5 kg。大于 0 的档位价格会替代该档位购物车的基础价格。档位为 0 时使用基础价格。基础价格为 0 表示免运费，空的基础价格会保存为 0。没有对应行的国家（当不存在 * 行时）不会获得价格表价格。
Fallback cost：当 J&T 和价格表都无法给出价格时使用的价格。在这种情况下留空可隐藏该配送方式。0 表示免运费。
Table / fallback price is：Per order（默认）只收取一次价格。Per item (multiplied by the number of items) 会将价格乘以购物车中的商品数量。J&T 实时报价始终针对整个订单。
条件
Free shipping from：购物车小计（需要配送的商品，扣除优惠券后，税前），达到该金额即免运费。若不设免运费，请留空。
Minimum subtotal：仅当购物车小计达到该金额时才显示该配送方式。留空则始终显示。
Min weight (kg)：购物车重量低于该值时隐藏该配送方式。商品重量按其重量类别换算。0 表示无限制（默认）。不能大于 Max weight (kg)。
Max weight (kg)：购物车重量高于该值时隐藏该配送方式。默认：50。0 表示无限制。
Geo zone：仅向该地理区域内的地址提供该配送方式。All zones（默认）表示无限制。地理区域在 System > Localisation > Geo Zones 中管理。当 Ignore shipping zones 开启时不使用该设置。
无配送区域时的可用性
Ignore shipping zones：无论地理区域为何，都为下列国家提供该配送方式。默认：关闭。
Countries：该模式下的目的国家，从您商店中已启用的国家中选择。留空则允许所有国家。仅当 Ignore shipping zones 开启时才使用此字段。
高级
Debug log：将价格计算写入 storage/logs/vfd_jtex_debug.log.php（在 OpenCart 4 上为 system/storage/logs/vfd_jtex_debug.log.php）。该文件无法通过网页读取。即使此选项关闭，J&T API 错误也始终会被记录。绝不会写入密钥、密码、客户代码或顾客邮编。完成后请关闭日志。当文件达到 5 MB 时，它会被移动到 vfd_jtex_debug.old.log.php，并开始新的日志。
Log：显示调试日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall：开启时，卸载扩展会删除 J&T Express 设置和日志。关闭时（默认），这些内容会保留，以便重新安装。缓存的报价始终会被删除。
导入 / 导出
Export：点击 Download JSON 可将设置保存为 JSON 文件。VIP API 密钥和私钥不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置，例如在另一家商店中。这些值会像普通保存一样进行检查。已保存的密钥会被保留。
结账时的工作方式
当 OpenCart 显示配送方式时，它会向扩展请求 J&T Express 的价格。如果设置了 Geo zone（且 Ignore shipping zones 关闭），并且地址不在该区域内，则不提供该配送方式。只有 Requires Shipping 设为 Yes 的商品才会计算在内：其他商品不增加重量，也不计入小计。然后扩展检查各项条件：允许的国家（使用 Ignore shipping zones 时）、购物车重量和最低小计。小计是需要配送的商品价格，扣除优惠券折扣后、税前计算。礼品卡、奖励积分和商店余额不计入。如果小计达到 Free shipping from，则价格为 0，且不会向 J&T 发送请求。
否则，费用将取自第一个提供价格的来源：
1. J&T 实时报价：仅当四项 API 凭据和一个发件邮编均已设置，配送国家为马来西亚，顾客输入了 5 位邮编，并且对于默认货币不是 MYR 的商店已设置换算汇率时才会使用。扩展会向 J&T 发送发件和收件邮编以及购物车重量（至少 0.1 kg），用于标准服务 EZ、一个包裹，并将返回的 MYR 价格换算为您的默认货币。
2. 国家价格：配送国家的行，或 * 行，按购物车重量档位取价。
3. 备用费用。
如果以上来源均未提供价格，则该购物车不显示该配送方式。Per item 仅适用于价格表和备用价格。价格以您的默认货币计算，按其小数位数取整，并以顾客的货币显示，同时加上所选 Tax class 的税费。
每个 J&T 响应都会缓存 1 小时，因此相同的购物车不会触发新的请求。失败的请求会缓存 10 分钟，这样结账时就不必每次刷新都等待 J&T。请求超时时间为 10 秒。如果 J&T 返回错误、零价格或没有响应，顾客不会看到任何错误。系统会使用价格表或备用价格，并将原因写入日志。
在 OpenCart 4 中，顾客在结账页面的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择 J&T Express。该配送方式的工作方式与 OpenCart 3 相同。
该扩展仅计算运费。它不会创建托运单、运单或面单，不预约取件，不取消或跟踪货件，也不允许顾客选择取件点。它不会向订单添加任何内容：订单与其他 OpenCart 配送方式一样，显示配送方式名称和运费。像往常一样在您的 J&T 账户中创建和跟踪货件。该扩展按照官方 J&T Express Malaysia 集成的请求格式开发。正式上线前，请与您的 J&T 账户核对价格。
许可证密钥
该扩展需要使用来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox J&T Express 许可证区块是 Extensions > Extensions > Shipping > VibeFox J&T Express > Edit 页面中位于设置上方的第一个区块。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now 重新检查状态，Change key 输入另一个密钥，Remove key 从本商店移除密钥。其下方是 Product: opencart-shipping-jt-express 一行，以及 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有对该扩展拥有 Modify 权限的管理员用户才能更改密钥。该区块的文本跟随后台语言显示（包括英文和俄文）。
如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带日期的 License expired on。更改商店地址后，或在您的账户中释放一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展将继续使用上次已知的状态工作。
一个密钥只能用于一个域名：OpenCart 配置中的商店地址。从商店中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效的密钥时，J&T Express 配送方式不会在结账时向顾客显示，也不会计算任何运费。在同一浏览器中登录后台的管理员用户，仍会在商店中看到该配送方式，并标有 (unlicensed — visible to admins only)，因此您可以在购买密钥前完成设置和测试。在 OpenCart 4 中，此预览功能不可用：商店无法识别后台登录状态，因此没有有效密钥时，该配送方式对所有人都隐藏。您打开一次 Edit 页面后，后台的 Dashboard 上会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响。
许可证到期后，扩展仍会继续工作，但更新和支持需要续费。当您打开后台的 Dashboard 或 Edit 页面时，系统会自动再次检查状态：输入密钥后的前 14 天内每天一次，之后每周一次。无需 cron 任务。卸载扩展时始终会删除许可证密钥和许可证状态。
故障排除
J&T Express 未在结账时出现：检查许可证是否有效以及 Enable J&T Express 是否已开启。检查 Geo zone（或 Ignore shipping zones 已开启且该国家在 Countries 中）、重量限制和 Minimum subtotal。检查 Country prices 中是否有该国家的行或 * 行，或者是否设置了 Fallback cost。检查商品的 Requires Shipping 是否设为 Yes。开启 Debug log，并查看扩展页面上的 Log 字段。
价格来自价格表，而非 J&T：实时报价需要四项 API 凭据、发件邮编、带有 5 位邮编的马来西亚配送地址，以及对于非 MYR 商店的 Currency conversion rate。请检查扩展页面顶部的警告。如果 J&T 拒绝请求或未响应，错误会被记录，并使用价格表或备用价格。失败的请求会在 10 分钟后重试。
菲律宾或印度尼西亚没有实时报价：J&T 不为这些国家提供公开的报价 API。请在这些国家使用价格表和备用费用。
某个国家错误地获得了免运费：其行的基础价格为 0（空的基础价格会保存为 0）。请输入基础价格或删除该行。同时检查 Free shipping from。
修改后价格看起来过时：点击扩展页面上的 Save。这会清除缓存的 J&T 报价。
页面显示 "Warning: You do not have permission to modify VibeFox J&T Express!"：您的管理员用户组可能只能查看设置。请在 System > Users > User Groups 中为该组授予 extension/shipping/vfd_jt_express（OpenCart 3）或 extension/vfd_jt_express/shipping/vfd_jt_express（OpenCart 4）的修改权限。
开发人员：其他扩展可以使用 OpenCart 事件 vfd_jt_express/quote_request 修改报价请求正文（例如服务类型），并使用 vfd_jt_express/api_url 修改报价端点地址。
卸载
进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox J&T Express 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会重置 Enable J&T Express、Sort order、Tax class 和 Geo zone。缓存的报价始终会被删除。如果 Remove data on uninstall 已开启，J&T Express 设置和调试日志也会被删除。如果已关闭，其他设置会保留，并在您重新安装扩展时再次使用。现有订单保留其配送方式和运费。
在 OpenCart 4 中，若还要删除扩展的文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox J&T Express 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
J&T Express 是其各自所有者的商标。本扩展与 J&T Express 无关，也未获得其认可或背书。