VibeFox 99Minutos for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在更低版本的 PHP 上安装。
99minutos API 密钥（仅用于覆盖检查）：可向您的 99minutos 客户经理索取，或在 99minutos 开发者门户（developers.99minutos.com）获取。沙盒密钥和正式密钥不同。如果您只使用价格矩阵，则不需要 API 密钥。
国家：99minutos 配送至墨西哥、哥伦比亚、智利和秘鲁。您发货的国家必须在 International > Locations 中处于启用状态。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox 99Minutos，然后点击 Configure。
3. 在 Configure 页面顶部许可证区块的 License key 中输入您的 VibeFox 许可证密钥，然后点击 Activate（参阅许可证密钥）。
4. 填写 Price matrix（至少一行，例如“* Default”），并可选择填写 API 密钥和覆盖检查模式（请参阅配置）。点击 Save。
安装时，模块会创建 99Minutos 承运商，配送时效文本为 Courier delivery。该承运商分配给所有区域和所有客户组。您可以在 Shipping > Carriers 中更改区域、客户组、配送时效、徽标和尺寸限制。墨西哥、哥伦比亚、智利和秘鲁的区域必须对该承运商保持启用。请勿在那里设置价格：价格始终来自模块。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox 99Minutos > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。每次保存还会清除缓存的覆盖结果。保存后，如果价格矩阵为空、包含 99minutos 不服务的国家的行、选择了覆盖检查模式却没有 API 密钥，或者模块无法识别商店的重量单位（此时重量按千克计算），页面会发出警告。如果 Method title 超过 64 个字符、某个重量或金额字段不是 0 或更大的数字，或者 Min weight (kg) 大于 Max weight (kg)，则不会保存任何内容，并显示错误。如果页面显示 The 99Minutos carrier was not found — reset the module to create it again.，请参阅故障排除。
常规
Enable 99Minutos:开启或关闭承运商。这与 Shipping > Carriers 中的承运商状态是同一个开关。
Method title:顾客在购物车和结账时看到的承运商名称。默认：99Minutos。必填，最多 64 个字符。
Tax:承运商的税务规则，或 No tax。设置税务规则后，PrestaShop 会在矩阵中的运费上加收税款。
99minutos API（覆盖检查）（可选）
API 仅用于检查 99minutos 是否配送至顾客的邮政编码。价格始终来自矩阵。
Coverage check:是否检查邮政编码以及检查方式。
启用覆盖检查时，承运商只会在顾客输入邮政编码后出现。结果会被缓存：覆盖 6 小时，不覆盖 30 分钟，API 错误 5 分钟。仅将邮政编码发送至 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 千克）、S（最多 2 千克）、M（最多 3 千克）、L（最多 5 千克）和 XL（超过 5 千克）的价格。尺寸价格为空或为 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 千克。
Minimum subtotal:仅当购物车小计（折扣后，不含税）不低于此金额时才显示承运商。留空则始终显示。
Restrict countries:仅对下列国家提供承运商。这是对承运商区域的额外筛选。当一个区域包含多个国家时非常有用。
Countries:选择 99minutos 支持的国家（墨西哥、哥伦比亚、智利、秘鲁）。按住 Ctrl（Cmd）可多选。仅在 Restrict countries 开启时使用。留空则允许 99minutos 的所有国家。
高级
Debug log:将费率计算写入模块文件夹中的 logs/vfd_99m_debug.log.php。该文件无法通过网页打开。即使此项关闭，API 错误仍会记录。API 密钥以及顾客姓名和地址从不写入日志。使用完毕后请关闭日志。
Log:显示调试日志的大小和最新条目。点击 Clear log 清空日志。
Remove data on uninstall:开启时，卸载模块会删除设置、承运商、覆盖缓存和日志。关闭时，所有内容都会保留，以便重新安装。无论如何，订单都会保留。
结账时的工作方式
在配送步骤，PrestaShop 会向模块请求 99Minutos 价格。只有实体商品计入：虚拟商品不增加重量，也不计入购物车小计。仅当收货国家为墨西哥、哥伦比亚、智利或秘鲁时才提供该承运商（若开启了 Restrict countries，还须在 Countries 列表中）。然后模块检查重量限制和 Minimum subtotal。
如果启用了覆盖检查模式，模块会向 99minutos API 查询邮政编码是否在覆盖范围内。请求超时为 10 秒，结果会被缓存，因此同一邮政编码不会触发新的请求。API 错误绝不会显示给顾客：在 Strict 模式下隐藏承运商，在 Soft 模式下使用矩阵价格。免运费不会绕过覆盖检查。
价格取自收货国家对应的矩阵行，或取自 * Default 行。如果两者都不存在，则隐藏承运商。如果 Free shipping 开启且购物车小计达到 Free shipping from，运费为 0。价格以您商店的默认货币计算，然后以顾客的购物车货币显示。
如果您在承运商已有订单后在 Shipping > Carriers 中编辑它，PrestaShop 会将其保存为承运商的新版本。模块会自动跟随新版本。
模块不会从 99minutos 获取实时运费报价：价格始终来自您的矩阵。它不会在 99minutos 中创建运单或订单，不打印面单（guides），不跟踪包裹，不提供 Punto99 取件点，也不处理货到付款。请像平常一样在您的 99minutos 账户中创建运单。
许可证密钥
本模块需要来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox 99Minutos 许可证区块是 Modules > Module Manager > VibeFox 99Minutos > Configure 页面中位于设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、许可状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now（再次检查状态）、Change key（输入另一个密钥）和 Remove key（从本商店移除密钥）。其下方是 Product: presta-shipping-99minutos 一行，以及链接 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 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 99Minutos 承运商，也不会计算运费。PrestaShop 前台无法得知您已登录后台，因此承运商对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响。
许可证到期后，模块仍会继续工作，但更新和支持需要续订。在后台工作时，系统会自动再次检查状态：输入密钥后的前 14 天每天检查一次，之后每周检查一次。无需 cron 任务。卸载或重置模块总会删除许可证密钥和许可状态。
故障排除
结账时没有 99Minutos：请检查许可证是否有效，以及 Enable 99Minutos 是否开启。收货国家必须是墨西哥、哥伦比亚、智利或秘鲁，并在 International > Locations 中处于启用状态。在 Shipping > Carriers 中，检查承运商是否覆盖顾客所在国家的区域以及顾客所在的客户组。检查 Price matrix 中是否有该国家的行或 * Default 行，并检查重量限制、Minimum subtotal 和 Restrict countries。商品页面中也可能将商品限制为某些承运商。
只有输入邮政编码后才会出现承运商：启用覆盖检查时，这是正常现象。在 Strict 模式下，只有当 API 确认覆盖时才会出现。
Strict 模式下承运商始终隐藏：开启 Debug log，重新加载结账页面，然后查看模块页面上的 Log 字段。HTTP 401 或 403 错误表示 API 密钥被拒绝：请检查密钥，以及 Environment 是否与之匹配（沙盒和正式密钥不同）。如果在 API 不可用时顾客仍应看到矩阵价格，请使用 Soft 模式。
价格与您的预期不符：请检查 Calculation（按订单或按商品）、商品重量以及商店的重量单位（International > Localization）。空白或为 0 的尺寸价格会使用 Base price。如果 Tax 中设置了税务规则，则税款会加在矩阵价格上。
修改后覆盖结果看起来过时：请在模块页面点击 Save。这会清除缓存的覆盖结果。
页面提示未找到 99Minutos 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块，以重新创建它。消息 The settings were saved, but the carrier could not be updated. Reset the module to create it again. 也适用同样的处理方法。
卸载
进入 Modules > Module Manager，打开 VibeFox 99Minutos 旁边的菜单，然后选择 Uninstall。许可证密钥和许可状态始终会被删除。覆盖缓存也始终会被删除。如果 Remove data on uninstall 已开启，则承运商会被删除（订单保留其历史记录），设置和日志也会被删除。如果已关闭，则承运商仅被停用，所有设置都会保留。重新安装模块时，已保存的承运商会恢复卸载前的状态，因此 Reset 不会开启已停用的承运商。
99minutos 是其各自所有者的商标。本模块与 99minutos 无关联，也未获得 99minutos 的认可。