VibeFox 99Minutos for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

99minutos API 密钥（仅用于服务范围检查）：可向您的 99minutos 客户经理索取，或在 99minutos 开发者门户（developers.99minutos.com）获取。沙盒密钥和生产密钥不同。如果您只使用价格矩阵，则不需要 API 密钥。

国家：99minutos 配送至墨西哥、哥伦比亚、智利和秘鲁。您发货的国家必须在 System > Localisation > Countries 中启用。

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

安装

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

OpenCart 3

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

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

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

4. 在 Edit 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥粘贴到 License key 中，然后点击 Activate（参见许可证密钥）。

5. 填写 Price matrix（至少一行，例如 "* Default"），并可选择填写 API 密钥和服务范围检查模式（参见配置）。开启 Enable 99Minutos，然后点击 Save。

OpenCart 4

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

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

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

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

安装后，该配送方式保持关闭状态，直到您开启 Enable 99Minutos 并保存。如果卸载后再次安装该扩展，将重新使用您之前保留的 99minutos 设置。

配置

所有设置都位于扩展页面：Extensions > Extensions > Shipping > VibeFox 99Minutos > Edit。各分区列在左侧。点击一次 Save 即可保存整个页面，且无需重新加载。每次保存也会清除缓存的服务范围查询结果。如果某个值有误，则不会保存任何内容，页面会显示原因，例如 Enter a method title (1 to 64 characters).、提示某字段必须为 0 或更大数字的信息，或 Min weight (kg) 不能大于 Max weight (kg) 的信息。保存后，设置上方的警告会告诉您，在当前配置下该配送方式可能无法正常工作：价格矩阵为空、选择了服务范围检查模式但未设置 API 密钥、矩阵中包含 99minutos 不服务的国家，或者商店没有 "kg" 重量单位且其重量单位不被扩展识别（此时重量按千克处理）。只有拥有该扩展修改权限的管理员用户才能保存设置。

常规

设置适用于所有地理区域。99Minutos 仅针对墨西哥、哥伦比亚、智利和秘鲁作为目的国家提供。

Enable 99Minutos：在结账时显示或隐藏 99Minutos。默认：关闭。

Method title：顾客在购物车和结账时看到的配送方式名称。默认：99Minutos。必填，最多 64 个字符。

Tax class：运费的税率类别，或 No tax（默认）。选择税率类别后，OpenCart 会在矩阵价格上加收税费。

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

99minutos API（服务范围检查）（可选）

API 仅用于检查 99minutos 是否配送至顾客的邮政编码。价格始终来自价格矩阵。

Coverage check：是否检查邮政编码以及如何检查。

启用服务范围检查后，只有在顾客输入邮政编码之后，该配送方式才会出现。结果会被缓存：在服务范围内缓存 6 小时，不在服务范围内缓存 30 分钟，API 错误缓存 5 分钟；但缓存时间不会超过 OpenCart 缓存的有效期（默认 1 小时）。发送给 99minutos 的仅是邮政编码，转换为大写，且只包含字母和数字。

API key：您的 99minutos API 密钥，以 Bearer 令牌形式发送至 99minutos 服务范围查询接口。开启服务范围检查时为必填项。保存后，该字段保持为空，并显示 Saved — leave empty to keep it. 只有需要更改时才输入新值。密钥按输入原样保存，仅去除前后空格。

Remove the saved API key：仅在已保存密钥时显示。开启该选项后点击 Save 即可删除密钥。

Environment：Sandbox (test)（默认）或 Production。沙盒和生产环境使用不同的 API 密钥，请选择与您的密钥相符的环境。

运费

价格以商店默认货币计，不含税，并按您输入的数值使用。最终价格以顾客的货币显示。

Price matrix：目的国家与价格的表格。点击 Add country 添加一行，点击 × 按钮删除一行。每行包含 Country（* Default、墨西哥、哥伦比亚、智利或秘鲁）、Base price，以及 XS（最多 1 kg）、S（最多 2 kg）、M（最多 3 kg）、L（最多 5 kg）和 XL（超过 5 kg）尺寸的价格。尺寸价格为空或为 0 时，使用 Base price。* Default 行适用于没有自有行的国家。如果某个国家有多行，则使用第一行。小数分隔符可使用句点或逗号；空白、无效或负数价格将保存为 0。在矩阵至少有一行之前，结账时不会显示该配送方式。

Calculation：Per order — size by the total cart weight（默认）按整个购物车的包裹尺寸收取一个价格。Per item — each unit priced by its own weight 按每件商品自身重量对应的尺寸为其定价，然后相加。

Free shipping：开启订单金额达到一定额度即免运费。

Free shipping from：需要配送的商品小计（优惠券折扣后，税前）达到该金额时，运费为 0。仅在 Free shipping 开启时使用。

限制

Min weight (kg)：购物车低于该重量时隐藏该配送方式。0 表示无限制（默认）。不能大于 Max weight (kg)。商品重量按其重量单位换算。

Max weight (kg)：购物车超过该重量时隐藏该配送方式。默认：25。0 表示无限制；空字段表示 25 kg。

Minimum subtotal：仅当需要配送的商品小计（优惠券折扣后，税前）不低于该金额时才显示该配送方式。留空则始终显示。

Geo zone：仅向该地理区域内的地址提供 99Minutos。All zones（默认）表示无限制。地理区域在 System > Localisation > Geo Zones 中管理。

Restrict countries：仅向下方列出的国家提供该配送方式。这是在 Geo zone 之外的附加筛选条件。

Countries：99minutos 所服务国家（墨西哥、哥伦比亚、智利、秘鲁）中的选择。仅在 Restrict countries 开启时使用。留空则允许所有 99minutos 国家。

高级

Debug log：将运费计算记录写入 storage/logs/vfd_99m_debug.log.php。该文件无法通过网页读取。即使此选项关闭，API 错误也会被记录。API 密钥以及顾客姓名和地址永远不会写入日志。完成后请关闭日志。文件达到 5 MB 时，会被移至 vfd_99m_debug.old.log.php，并开始新的日志。

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

Remove data on uninstall：开启时，卸载扩展将删除 99minutos 设置、服务范围缓存和日志。关闭时（默认），这些数据会保留以便重新安装。无论如何，订单都会保留。

导入 / 导出

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

Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置，例如在另一家商店中使用。数值会像正常保存时一样进行检查。已保存的 API 密钥会被保留。

结账时的运行方式

OpenCart 显示配送方式时，会向扩展请求 99Minutos 的价格。如果设置了 Geo zone 且地址位于其范围之外，则不提供 99Minutos。只有 Requires Shipping 设为 Yes 的商品才会计算在内：其他商品不增加重量，也不计入订单金额。只有当配送国家为墨西哥、哥伦比亚、智利或秘鲁时才提供该配送方式（如果开启了 Restrict countries，则还需在 Countries 列表中）。随后，扩展会检查重量限制和 Minimum subtotal。订单金额是需要配送的商品价格，即扣除优惠券折扣后、税前的金额。礼品卡、积分和商店余额不计算在内。

如果开启了服务范围检查，扩展会向 99minutos API 查询该邮政编码是否在服务范围内。请求超时时间为 10 秒，且结果会被缓存，因此同一邮政编码不会重复发起请求。API 错误绝不会显示给顾客：在 Strict 模式下隐藏该配送方式，在 Soft 模式下使用矩阵价格。免运费不会绕过服务范围检查。

价格取自配送国家对应的矩阵行，或取自 * Default 行。如果两者都不存在，则隐藏该配送方式。如果 Free shipping 开启且订单金额达到 Free shipping from，则运费为 0。价格以商店默认货币计算，按其小数位数取整，并以顾客的货币显示，同时加上所选 Tax class 的税费。

扩展不会从 99minutos 获取实时运费报价：价格始终来自您的矩阵。它不会在 99minutos 中创建发货单或订单，不打印面单（guides），不跟踪包裹，不提供 Punto99 自提点，也不支持货到付款。它不会向订单添加任何内容：订单与其他 OpenCart 配送方式一样，显示配送方式名称和运费。请像平常一样在您的 99minutos 账户中创建发货单。

在 OpenCart 4 中，顾客在结账页面点击配送方式区块中的 Choose，并在 Shipping method options 窗口中选择 99Minutos。该配送方式的工作方式与 OpenCart 3 相同。

许可证密钥

该扩展需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox 99Minutos 是扩展 Extensions > Extensions > Shipping > VibeFox 99Minutos > Edit 页面中位于设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以隐藏形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此商店中移除密钥）。其下方是 Product: opencart-shipping-99minutos 一行和 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 账户中释放该名额。

没有有效密钥时，结账时不会向顾客显示 99Minutos 配送方式，也不会计算运费。以同一浏览器登录后台的管理员用户，仍会在商店中看到该配送方式，并标注 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置并测试扩展。在 OpenCart 4 中此预览不可用：商店看不到后台登录状态，因此没有有效密钥时，所有人都看不到该配送方式。打开一次 Edit 页面后，后台的 Dashboard 会出现提醒。点击 × 可关闭，并在 7 天内隐藏。现有订单不受影响。

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

故障排除

结账时不显示 99Minutos：请检查许可证是否有效，以及 Enable 99Minutos 是否已开启。配送国家必须为墨西哥、哥伦比亚、智利或秘鲁，并且已在 System > Localisation > Countries 中启用。检查 Geo zone 和 Restrict countries。检查 Price matrix 中是否有该国家的行或 * Default 行，并检查重量限制和 Minimum subtotal。检查商品的 Requires Shipping 是否设为 Yes。点击 Save 后显示的警告会指出隐藏该配送方式的设置。

只有输入邮政编码后才显示该配送方式：这在启用服务范围检查时属于正常现象。在 Strict 模式下，只有 API 确认在服务范围内时才会显示。

在 Strict 模式下该配送方式始终隐藏：开启 Debug log，重新加载结账页面，然后查看扩展页面上的 Log 字段。HTTP 401 或 403 错误表示 API 密钥被拒绝：请检查密钥，并确认 Environment 与之相符（沙盒密钥和生产密钥不同）。如果希望在 API 不可用时顾客仍能获得矩阵价格，请使用 Soft 模式。

价格与预期不符：请检查 Calculation（按订单或按商品），以及商品重量和重量单位。尺寸价格为空或为 0 时，使用 Base price。设置了 Tax class 时，税费会加在矩阵价格上。

修改后服务范围结果似乎过时：在扩展页面点击 Save。这将清除缓存的服务范围结果。

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

面向开发者：可通过设置 vfd_99m_api_url（用于测试）替换 99minutos API 地址；该设置在设置页面中没有对应字段。

卸载

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

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

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