VibeFox Estafeta for OpenCart — 帮助
要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本，并启用 cURL 扩展。
DrEnvio 账户（仅用于实时运费）：Estafeta 实时运费来自 DrEnvio，它是墨西哥的 Estafeta 合作伙伴。请在 drenvio.com 创建账户，启用 Estafeta，在那里设置您的取件地址，并从 DrEnvio 面板复制 API 密钥。这与官方 DrEnvio 插件使用的密钥相同。如果您只使用自己的价格，则不需要 DrEnvio 账户。
商品：使用实时运费时，商品需要设置重量。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载内容是一个 zip 文件，包含适用于两个 OpenCart 版本的安装包。请在您的电脑上解压。其中包含 README.txt、OpenCart 3 安装包 vfd_estafeta-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 vfd_estafeta.ocmod.zip。只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。
OpenCart 3
1.在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_estafeta-oc3-(version).ocmod.zip。该扩展不添加 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是把安装包中 upload 文件夹的内容复制到商店的根目录。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Estafeta，点击 Install（绿色的 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥粘贴到 License key，然后点击 Activate（见“许可证密钥”）。
5. 输入 DrEnvio API key，并可选择输入 Origin postcode。如果您的默认货币不是 MXN，请输入 MXN exchange rate。如果 DrEnvio 没有运费时仍希望显示该方式，请为 MX 设置国家价格或 Fallback cost。开启 Enable/Disable 并点击 Save。
OpenCart 4
1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 vfd_estafeta.ocmod.zip。请勿重命名该文件：OpenCart 4 会从文件名获取扩展代码，重命名后的安装包无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色的 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Estafeta，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 的第 4 和第 5 步输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装后，该方式保持关闭，直到您开启 Enable/Disable 并保存。如果您卸载后重新安装该扩展，将再次使用您保留的 Estafeta 设置。
配置
所有设置都在扩展页面上：Extensions > Extensions > Shipping > VibeFox Estafeta > Edit。各分区列在左侧。页面底部的一个 Save 按钮可在不刷新页面的情况下保存整个页面。每次保存还会清除缓存的 DrEnvio 运费。只有拥有该扩展修改权限的管理员用户才能保存设置。
页面顶部，扩展会显示以下警告：未填写 DrEnvio API 密钥；默认货币不是 MXN 且没有汇率；未设置 MX 的国家价格和备用费用（这样在没有实时运费时该方式会被隐藏，没有 API 密钥时则永远不会显示）；或没有单位为 kg 的重量类别（此时商品重量会按其重量类别的单位名称换算，未知单位按 kg 处理；请在 System > Localisation > Weight Classes 中添加一个 kg 类别）。数字字段接受小数点或逗号。保存时，错误的值会被提示，并按各字段说明被清空或重置，表单显示已保存的值，其他设置仍会保存（The other settings were saved.）。
常规
该方式会提供给下面选定的地理区域（或每个地址），或提供给 Availability without shipping zones 中的国家。
Enable/Disable：开启或关闭 Estafeta 配送。默认：关闭。
Name：结账时显示给客户的配送方式名称。默认：Estafeta。必填：1 至 64 个字符，不得包含 < > ; = # { }。名称无效时会提示，并保留之前的名称。
Tax class：添加到运费上的税类，或 No tax（默认）。DrEnvio 的价格是否包含 IVA 取决于您的 DrEnvio 账户。如果已包含 IVA，请选择 No tax。
Geo zone：仅对该地理区域内的地址提供 Estafeta，例如“墨西哥”地理区域。All zones（默认）表示不限制。地理区域在 System > Localisation > Geo Zones 中管理。开启 Ignore shipping zones 时不使用。
Sort order：Estafeta 在结账时配送方式中的位置。一个整数。
实时运费（DrEnvio API）
该分区说明如何获取密钥。系统为该地址提供最便宜的 Estafeta 服务。没有密钥时，使用 Prices without a live rate 中的价格。
DrEnvio API key：来自您 DrEnvio 面板的 API 密钥。保存后，该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。
Remove the saved API key：仅在已保存密钥时显示。开启并保存即可删除密钥。之后只使用 Country prices 和 Fallback cost。在上方字段中输入的密钥会替换已保存的密钥。
Origin country：取件地址的两位国家代码。默认：MX。仅在与出发邮政编码一起时发送。无效代码会被提示并重置为 MX。
Origin postcode：取件地址的 5 位邮政编码。留空则使用您 DrEnvio 账户中保存的发货地址。不是 5 位的邮政编码会在保存时被清除并提示。
MXN exchange rate：DrEnvio 以墨西哥比索报价。只有当您的默认货币不是 MXN 时才需要：1 MXN 对应的默认货币价值，例如 0.05。未设置时不会使用实时运费。必须大于 0。如果商店货币是 MXN，请留空。
无实时运费时的价格
在没有 API 密钥或 DrEnvio 未返回 Estafeta 运费时使用（API 无法访问、邮政编码未知、尚未输入邮政编码）。价格以您商店的默认货币计，不含税。
Country prices：每行一个目的地国家，格式为 CC:PRICE，例如 MX:150。使用小数点或逗号，不要使用千位分隔符。格式不同的部分会被忽略，并在保存时提示。
Fallback cost：没有实时运费也没有国家价格时的价格。留空则隐藏该方式；0 表示免运费。
Calculation type：Per order（默认）只收一次费用。Per item (price x number of items) 则按购物车商品数量相乘。这适用于 Country prices 和 Fallback cost。DrEnvio 实时运费始终是整个包裹的价格。
条件
Free shipping from：需要配送的商品小计（优惠券折扣后，税前）达到此金额时，该方式免运费。此时不会向 DrEnvio 发出请求。留空则从不提供免运费。
Minimum subtotal：只有当小计至少达到此金额时才显示该方式。留空则始终显示。
Min weight (kg)：该方式显示所需的最低购物车重量。0 表示不限（默认）。
Max weight (kg)：最高购物车重量。超过时该方式会被隐藏。默认：30。0 表示不限。
如果 Min weight 大于 Max weight，保存时会显示错误，两个重量都保持不变。商品重量会按每个商品的重量类别转换为 kg。
无配送区域时的可用性
Ignore shipping zones：不检查地理区域，为下面的国家提供该方式。默认：关闭。
Countries：该模式下的目的地国家。留空表示所有国家。仅在开启 Ignore shipping zones 时使用。
高级
Debug log：将 API 请求和运费计算写入 storage/logs/vfd_est_debug.log.php（OpenCart 4 上为 system/storage/logs/vfd_est_debug.log.php）。该文件无法通过网页读取。即使日志关闭，API 错误也始终会记录。API 密钥和客户地址永远不会被记录。完成后请关闭日志。文件达到 5 MB 时，会移至 vfd_est_debug.old.log.php，并开始新的日志。
Log：显示调试日志的大小和最新条目。点击 Clear log 可清空。
Remove data on uninstall：开启后，卸载扩展会删除其所有设置和日志。关闭时（默认），所有内容都会保留，以便重新安装。订单中保存的 Estafeta 服务始终保留。
导入 / 导出
Export：点击 Download JSON 可将设置保存为 JSON 文件。API 密钥不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置，例如在另一家商店中。这些值会像正常保存一样进行检查。已保存的 API 密钥会保留。
结账时的工作方式
OpenCart 显示配送方式时，会向扩展请求 Estafeta 的价格。如果设置了 Geo zone（且 Ignore shipping zones 关闭），而地址不在该区域内，则不提供 Estafeta。只有 Requires Shipping 设为 Yes 的商品才计入：其他商品不增加重量，也不计入小计。小计是这些商品在优惠券折扣之后、税前的价格；礼品卡、积分和商店余额不计入。然后扩展检查条件：Countries 列表（开启 Ignore shipping zones 时）、购物车重量和最低小计。如果适用免运费，价格为 0，且不会向 DrEnvio 发送请求。
否则，扩展会向 DrEnvio 发送目的地国家和邮政编码、购物车重量、商品数量、以 MXN 计的小计，以及您设置的发货邮政编码（如有）。墨西哥邮政编码必须为 5 位；在客户输入此类配送地址之前，不会发出请求。DrEnvio 会返回您账户下所有承运商的报价。扩展只使用 Estafeta 的报价，忽略零价格，选择最便宜的一个，并将其转换为您的默认货币。价格按该货币的小数位数取整，并以客户的货币显示，同时加上所选 Tax class 的税。
每次响应缓存 1 小时。失败的请求或没有 Estafeta 运费的路线会记住 5 分钟，因此缓慢或故障的 API 不会拖慢每次结账更新。API 超时时间为 12 秒。在这些情况下，客户不会看到错误：使用国家价格或备用费用，若两者都没有则隐藏该方式。原因会写入日志。
客户只看到配送方式名称和价格。扩展仅计算运费。它不会创建运单、打印面单（guías）或追踪包裹；请在您的 DrEnvio 或 Estafeta 账户中创建运单。客户无法选择具体的 Estafeta 服务或 Estafeta 网点，汇率也不会自动更新。
在 OpenCart 4 上，客户点击结账页面配送方式区块中的 Choose，然后在 Shipping method options 窗口中选择 Estafeta。该方式的工作方式与 OpenCart 3 相同。
订单
下单使用 Estafeta 时，扩展会保存显示给客户的运费，不会再向 DrEnvio 发出新请求。之后在后台对订单所做的修改不会改变它。在 OpenCart 4 上，结账会保留同一个订单，并在客户每次重新确认时更新它，因此保存的运费会被结账页面的最新运费替换。如果客户改选其他配送方式，该订单将不再显示此面板。
Sales > Orders 中的订单页面会显示 Estafeta 面板：
Estafeta service：DrEnvio 报价中的 Estafeta 服务及其配送时效。仅对实时运费显示。
Price source：Live DrEnvio rate、Country price (no live rate)、Fallback cost (no live rate) 或 Free shipping threshold。
Shipping cost：结账时以您的默认货币计算的运费，不含税。
许可证密钥
该扩展需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Estafeta 是 Extensions > Extensions > Shipping > VibeFox Estafeta > Edit 页面中的第一个区块，位于设置上方。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以隐藏形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店移除密钥）。其下方是 Product: opencart-shipping-estafeta 一行和 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 账户中释放该名额。
没有有效的密钥时，结账页面不会向客户显示 Estafeta，也不会计算任何运费。在同一浏览器中登录后台的管理员仍会在商店中看到该方式，并标注 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试扩展。在 OpenCart 4 上此预览不可用：商店看不到后台登录状态，因此没有有效密钥时，该方式对所有人都隐藏。打开一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响。
许可证到期后，扩展仍可继续运行，但更新和支持需要续订。当您打开后台 Dashboard 或 Edit 页面时，系统会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载扩展总会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 Estafeta：检查许可证是否有效，以及 Enable/Disable 是否已开启。检查 Geo zone，或者 Ignore shipping zones 和 Countries。检查扩展页面顶部的警告、重量限制和 Minimum subtotal。没有 API 密钥或 DrEnvio 没有 Estafeta 运费时，该方式需要目的地的国家价格或备用费用。检查商品的 Requires Shipping 是否设为 Yes。
实时运费没有显示：开启 Debug log，刷新结账页面，然后查看扩展页面上的 Log 字段。它会显示原因：没有 API 密钥；默认货币不是 MXN 的商店没有汇率；缺少或无效的邮政编码；API 密钥被拒绝（DrEnvio HTTP 401 或 403，请检查 API 密钥）；该路线没有 Estafeta 运费（日志会列出 DrEnvio 返回的承运商）；或者运费使用的货币不是 MXN。
价格是否包含 IVA？这取决于您的 DrEnvio 账户。如果 DrEnvio 价格已包含 IVA，请将 Tax class 设为 No tax。
修改后运费看起来过时：在扩展页面点击 Save。这会清除缓存的 DrEnvio 运费。
订单页面没有 Estafeta 面板：只有在扩展已安装并启用期间使用 Estafeta 下的订单才会显示该面板。
页面显示“Warning: You do not have permission to modify VibeFox Estafeta!”：您的管理员用户组可能只有查看设置的权限。请在 System > Users > User Groups 中为该组授予 extension/shipping/vfd_estafeta（OpenCart 3）或 extension/vfd_estafeta/shipping/vfd_estafeta（OpenCart 4） 的修改权限。
开发者说明：可以通过设置 vfd_est_api_url 替换 DrEnvio API 地址（用于测试）；该设置在设置页面上没有对应的字段。
卸载
进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox Estafeta 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态总会被删除。OpenCart 总是会重置 Enable/Disable、Sort order、Tax class 和 Geo zone。缓存的运费总会被删除。如果 Remove data on uninstall 已开启，Estafeta 设置和调试日志也会被删除。如果已关闭，其他设置会保留，并在您重新安装扩展时再次使用。无论哪种情况，订单中保存的 Estafeta 服务都会保留，订单也会保留其配送方式和运费。
在 OpenCart 4 上，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Estafeta 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
Estafeta 和 DrEnvio 是各自所有者的商标。本扩展与 Estafeta 或 DrEnvio 没有关联，也未获得它们的认可或支持。