VibeFox J&T Express for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块无法在更低版本的 PHP 上安装。
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 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox J&T Express，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥粘贴到 License key 中，然后点击 Activate（见“许可证密钥”）。
4. 填写价格表和/或备用运费。若要使用马来西亚实时报价，还需填写 J&T API 凭据、发件邮编；如果您店铺的默认货币不是 MYR，还需填写货币换算汇率（见“配置”）。点击 Save。
安装时，模块会创建 J&T Express 承运商，配送时间文字为 Courier delivery。该承运商分配给所有区域和所有客户群组。您可以在 Shipping > Carriers 中修改区域、客户群组、配送时间、Logo 和尺寸限制。请勿在那里设置价格：价格始终来自模块。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox J&T Express > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。每次保存也会清除缓存的 J&T 报价。如果实时报价只配置了一部分，页面顶部的警告会列出缺失的设置，或提示缺少货币换算汇率。不是 0 或更大数字的金额会被拒绝并报错，Currency conversion rate 为 0 以及 Min weight 大于 Max weight 同样会被拒绝。如果店铺的重量单位无法识别，警告会要求您在 International > Localization 中设置标准单位。
常规
本页的设置适用于所有区域。承运商的区域、客户群组和尺寸限制在 Shipping > Carriers 中设置（或使用下方的 Ignore shipping zones）。
Enable J&T Express：开启或关闭该承运商。这与 Shipping > Carriers 中的承运商状态是同一个开关。
Method title：在购物车和结账页面显示的承运商名称。默认：J&T Express。必填。
Tax：承运商的税务规则，或 No tax。税务规则会在运费上加上您店铺的运费税。如果 J&T 的价格已包含您想收取的全部费用，请选择 No tax。
J&T Express Malaysia API（实时报价）（可选，适用于马来西亚配送地址；四项凭据均为必填）
VIP customer code：您的 J&T Express VIP 客户代码。清空它也会清除已保存的 VIP API 密钥。
VIP API key：J&T Express 与 VIP 代码一同提供给您的 API 密钥（密码）。它从不写入日志。保存后，该字段保持为空，并显示 Saved — leave empty to keep it. 只有需要更改时才输入新值。
API account：您的 J&T Express API 账户名称。清空它也会清除已保存的私钥。
API private key：API 账户的私钥。它仅用于签署请求（SHA-256）。从不发送给 J&T，也从不写入日志。与 VIP API 密钥一样，保存后不会再次显示。
Sender postcode：包裹寄出的马来西亚邮编。如果店铺位于马来西亚，可留空以使用 Shop Parameters > Contact > Stores 中的店铺邮编。保存时会删除空格。
Currency conversion rate：J&T Express Malaysia 的报价以 MYR 计价。如果您店铺的默认货币不是 MYR，请输入 1 MYR 等于您货币的多少单位（1 MYR = X）。未填写时，不使用实时报价，而改用价格表或备用运费。如果您的默认货币是 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。
Max weight：购物车重量高于此值（单位 kg）时隐藏该承运商。默认：50。0 表示无限制。
不使用配送区域时的可用性
Ignore shipping zones：即使承运商未关联到下方国家所在的区域，也会为这些国家提供该承运商。开启后，承运商会关联到所有活跃区域，并且您之后创建的区域也会自动关联。关闭时，承运商仅在 Shipping > Carriers 中为其自身的区域提供。关闭后，承运商会恢复之前的区域。
Countries：该模式下的目的国家。留空则使用您配送的所有国家。仅在开启 Ignore shipping zones 时才使用此字段。
高级
Debug log：将运费计算写入模块文件夹中的 logs/vfd_jtex_debug.log.php。该文件无法通过网页打开。即使关闭此选项，J&T API 错误也始终会被记录。不会写入密钥、密码或顾客邮编。使用完毕后请关闭日志。
Log：显示日志的大小和最新条目。点击 Clear log 清空日志。
Remove data on uninstall：开启后，卸载模块会删除模块设置、承运商、缓存的报价和日志。关闭后，所有内容都会保留，以便重新安装。
结账时的工作方式
在配送步骤，PrestaShop 向模块请求 J&T Express 的价格。只有实物商品才计算在内：虚拟商品不增加重量，也不计入小计。模块首先检查条件：配送国家（结合 Ignore shipping zones）、购物车重量和最低小计。如果购物车小计达到 Free shipping from，价格为 0，不会向 J&T 发送请求。
否则，运费取自第一个提供价格的来源：
1. J&T 实时报价：仅当四项 API 凭据和发件邮编均已设置，配送国家为马来西亚，顾客输入了 5 位邮编，并且对于默认货币不是 MYR 的店铺已设置换算汇率时。模块会将发件和收件邮编以及购物车重量（至少 0.1 kg）发送给 J&T，请求标准服务 EZ、一个包裹的报价，并将返回的 MYR 价格换算为您店铺的默认货币。
2. 国家价格：配送国家对应的行，或 * 行，按购物车重量区间取价。
3. 备用运费。
如果以上来源都无法提供价格，该购物车会隐藏此承运商。Per item 仅适用于价格表和备用价格。价格以您店铺的默认货币计算，然后以顾客购物车的货币显示。
J&T 的每个响应缓存 1 小时，因此同一购物车不会触发新的请求。失败的请求缓存 10 分钟，使结账页面不会在每次刷新时都等待 J&T。请求超时时间为 10 秒。如果 J&T 返回错误、零价格或没有响应，顾客不会看到任何错误。系统将使用价格表或备用运费，并将原因写入日志。
如果承运商已有订单后，您在 Shipping > Carriers 中对其进行编辑，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
模块仅计算运费。它不会生成运单、面单或标签，不预约取件，不取消或跟踪货件，也不允许顾客选择自提点。请像平常一样在您的 J&T 账户中创建和跟踪货件。该模块是依据 J&T Express Malaysia 官方插件的请求格式开发的。正式上线前，请在您的 J&T 账户中确认价格。
许可证密钥
本模块需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox J&T Express 是 Modules > Module Manager > VibeFox J&T Express > Configure 页面中位于设置上方的第一个区块。请将密钥粘贴到 License key 中，然后点击 Activate。此后，该区块会以遮蔽形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方有 Product: presta-shipping-jt-express 一行和 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有拥有本模块 Configure 权限的员工才能更改密钥。区块中的文字遵循后台语言（包括英文和俄文）。
如果密钥未被接受，区块会显示原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加上一个日期。在店铺地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块将继续按最后已知的状态运行。
一个密钥只能用于一个域名：主店铺的域名，多店铺设置中同样如此。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，结账时不会向顾客显示 J&T Express 承运商，也不会计算运费。PrestaShop 前台无法知道您已登录后台，因此承运商对您也会隐藏：您可以在购买密钥前设置模块，但无法在结账时测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 J&T Express：请检查许可证是否有效，以及 Enable J&T Express 是否已开启。在 Shipping > Carriers 中检查该承运商是否覆盖顾客所在国家的区域以及顾客所属的客户群组（或者 Ignore shipping zones 已开启且该国家被允许）。检查重量限制和 Minimum subtotal。检查 Country prices 中是否有该国家的行或 * 行，或者 Fallback cost 是否已设置。商品也可能在商品页面被限制为特定承运商。请开启 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 报价。
页面显示未找到 J&T Express 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建。
开发者钩子：钩子 actionVfdJtexQuoteRequest 可修改报价请求内容（例如服务类型），actionVfdJtexApiUrl 可修改报价接口地址。
卸载
进入 Modules > Module Manager，打开 VibeFox J&T Express 旁边的菜单，选择 Uninstall。许可证密钥和许可证状态始终会被删除。缓存的报价始终会被删除。如果 Remove data on uninstall 已开启，承运商将被删除（订单保留其历史记录），并删除设置和日志。如果已关闭，承运商仅被停用，所有设置都会保留。重新安装模块后，已保存的承运商将恢复其之前的状态。
J&T Express 是其各自所有者的商标。本模块与 J&T Express 无关联，也未获得其认可。