VibeFox Estafeta for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本并启用 cURL 扩展。模块无法在较旧的 PHP 版本上或未启用 cURL 时安装。
DrEnvio 账户（仅用于实时运费）：Estafeta 的实时运费来自 DrEnvio，即 Estafeta 在墨西哥的合作伙伴。请在 drenvio.com 上创建账户，启用 Estafeta，在那里设置您的取件地址，并从 DrEnvio 面板复制 API 密钥。这与官方 DrEnvio 插件使用的密钥相同。如果您只使用自有价格，则无需 DrEnvio 账户。
商品：使用实时运费时，商品需要设置重量。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure，或之后在模块列表中找到 VibeFox Estafeta 并点击 Configure。
3. 在 Configure 页面顶部的许可证区块中的 License key 字段输入您的 VibeFox 许可证密钥，然后点击 Activate（见许可证密钥）。
4. 输入 DrEnvio API key，并可选择输入 Origin postcode。如果商店默认货币不是 MXN，请输入 MXN exchange rate。如果希望在 DrEnvio 没有运费时承运商仍然可见，请为 MX 设置国家价格或设置 Fallback cost。点击 Save。
安装时，模块会创建 Estafeta 承运商，配送时间文本为 Estafeta courier (Mexico)。该承运商分配给所有区域和所有客户组。您可以在 Shipping > Carriers 中更改区域、客户组、配送时间、徽标和尺寸限制。请不要在那里设置价格：价格始终来自模块。
配置
所有设置都在模块页面：Modules > Module Manager > VibeFox Estafeta > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。每次保存还会清除缓存的 DrEnvio 运费。
页面顶部，模块会显示以下警告：缺少 DrEnvio API 密钥；默认货币不是 MXN 且没有汇率；MX 没有国家价格，也没有备用费用（此时，没有实时运费时承运商会被隐藏，没有 API 密钥时则永远不显示）；或者商店使用了模块无法识别的重量单位（此时商品重量按 kg 计算；请在 International > Localization 的 Local units 中设置单位）。数字字段接受小数点或逗号作为小数分隔符。无效的数字在保存时会被清空并提示；其他设置仍会保存。
常规
承运商的区域、客户组和尺寸限制在 Shipping > Carriers 中设置。这些设置适用于每个区域。
Enable/Disable：开启或关闭 Estafeta 配送。这与 Shipping > Carriers 中承运商的状态是同一个开关。
Name：结账时向客户显示的承运商名称。默认：Estafeta。必填。无效名称会被提示，并保留之前的名称。
Tax：承运商的税务规则，或 No tax。商店会在运费上加收此税。DrEnvio 价格是否包含 IVA 取决于您的 DrEnvio 账户。如果价格已包含 IVA，请选择 No tax。
实时运费（DrEnvio API）
为该地址提供最便宜的 Estafeta 服务。没有密钥时，使用下一部分中的价格。
DrEnvio API key：DrEnvio 面板中的 API 密钥。保存后，该字段保持为空并显示 Saved — leave empty to keep it. 只有需要更改时才输入新值。
Remove the saved API key：仅在已保存密钥时显示。将其设为 Yes 并保存即可删除密钥。之后只使用 Country prices 和 Fallback cost。在上方字段中输入的密钥会替换已保存的密钥。
Origin country：取件地址的两位国家代码。默认：MX。仅与 Origin postcode 一起发送。
Origin postcode：取件地址的 5 位邮政编码。留空则使用您在 DrEnvio 账户中保存的发货地址。不是 5 位数字的邮政编码会在保存时被清空并提示。
MXN exchange rate：DrEnvio 以墨西哥比索报价。只有在商店默认货币不是 MXN 时才需要：1 MXN 等于您默认货币的金额，例如 0.05。没有它，就不会使用实时运费。
无实时运费时的价格
在没有 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 请求和运费计算写入模块文件夹中的 logs/vfd_est_debug.log.php。该文件无法通过网页打开。API 错误始终会记录。API 密钥和客户地址从不记录。使用完毕后请关闭日志。
Log：显示调试日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall：开启时，卸载模块会删除所有模块设置、承运商、订单中保存的 Estafeta 服务以及日志。关闭时，所有内容都会保留，以便重新安装。
结账时的工作方式
在配送步骤，PrestaShop 会向模块请求 Estafeta 价格。只计算实体商品：虚拟商品不增加重量，也不计入小计。模块首先检查条件：Countries 列表（当 Ignore shipping zones 开启时）、购物车重量和最低小计。如果适用免运费，价格为 0，并且不会向 DrEnvio 发送请求。
否则，模块会向 DrEnvio 发送目的国家和邮政编码、购物车重量、商品数量、以 MXN 计的小计，以及您设置的发货邮政编码（如果有）。墨西哥邮政编码必须为 5 位数字；在客户输入此类配送地址之前，不会发出请求。DrEnvio 会返回您账户中所有承运商的报价。模块只使用 Estafeta 的报价，忽略零价格，选择最便宜的一个，并将其转换为您的默认货币。之后，价格会以客户的购物车货币显示。
每个响应缓存 1 小时。失败的请求或没有 Estafeta 运费的路线会记录 5 分钟，因此缓慢或出错的 API 不会拖慢每次结账更新。API 超时时间为 12 秒。在这些情况下，客户不会看到错误：使用国家价格或备用费用，若两者都未设置，则隐藏承运商。原因会写入日志。
如果在承运商已有订单后，在 Shipping > Carriers 中编辑该承运商，PrestaShop 会将其保存为新的承运商版本。模块会自动跟随新版本。
模块只计算运费。它不创建发货单，不打印运单（guías），也不追踪包裹；请在您的 DrEnvio 或 Estafeta 账户中创建发货单。客户无法选择特定的 Estafeta 服务或 Estafeta 网点，汇率也不会自动更新。
订单
下达使用 Estafeta 承运商的订单时，模块会保存为其购物车计算的运费。之后的重新计算（例如在后台订单页面上）不会更改该运费。
Orders > Orders 中的订单页面会显示一个 Estafeta 区块：
Estafeta service：DrEnvio 报价中的 Estafeta 服务及其配送时间。仅对实时运费显示。
Price source：Live DrEnvio rate、Country price (no live rate)、Fallback cost (no live rate) 或 Free shipping threshold。
Calculated price (excl. tax)：以您的默认货币表示的配送价格。
许可证密钥
模块需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。License — VibeFox Estafeta 许可证区块位于 Modules > Module Manager > VibeFox Estafeta > Configure 页面中设置上方的第一个区块。在 License key 中输入密钥并点击 Activate。之后，该区块会以隐藏部分字符的方式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（将密钥从本店铺中移除）。其下方是 Product: presta-shipping-estafeta 一行和 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 账户中释放该名额。
没有有效的密钥时，结账时不会向顾客显示 Estafeta 承运商，也不会计算任何运费。PrestaShop 前台无法得知您已登录后台，因此该承运商对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试它。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。您在后台工作时会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，总会删除许可证密钥和许可证状态。
故障排除
结账时没有显示 Estafeta：请检查许可证是否有效，以及 Enable/Disable 是否开启。在 Shipping > Carriers 中，检查承运商是否覆盖客户所在国家的区域和客户的客户组（或 Ignore shipping zones 已开启且允许该国家）。检查模块页面顶部的警告、重量限制和 Minimum subtotal。没有 API 密钥或 DrEnvio 没有 Estafeta 运费时，承运商需要目的地的国家价格或备用费用。商品也可以在商品页面中被限制为特定承运商。
没有显示实时运费：开启 Debug log，重新加载结账页面，并查看模块页面上的 Log 字段。它会显示原因：没有 API 密钥；默认货币不是 MXN 的商店没有汇率；邮政编码缺失或无效；API 密钥被拒绝（DrEnvio 返回 HTTP 401 或 403，请检查 API 密钥）；该路线没有 Estafeta 运费（日志会列出 DrEnvio 返回的承运商）；或运费使用的货币不是 MXN。
价格是否包含 IVA？这取决于您的 DrEnvio 账户。如果 DrEnvio 价格已包含 IVA，请将 Tax 设置为 No tax。
更改后运费看起来过时：在模块页面点击 Save。这会清除缓存的 DrEnvio 运费。
页面提示未找到 Estafeta 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建。消息 The settings were saved, but the carrier could not be updated. 也适用同样的处理方法。
订单页面没有 Estafeta 区块：该区块只会显示在模块安装期间使用 Estafeta 承运商下的订单。在 Remove data on uninstall 开启的情况下卸载，会删除保存的服务。
卸载
进入 Modules > Module Manager，打开 VibeFox Estafeta 旁边的菜单，然后选择 Uninstall。许可证密钥和许可证状态始终会被删除。缓存的运费始终会被删除。如果 Remove data on uninstall 已开启，承运商将被删除（订单保留历史记录），并删除设置、订单中保存的 Estafeta 服务和日志。如果已关闭，承运商仅被禁用，设置和订单中保存的服务会保留。重新安装模块后，承运商会恢复卸载前的状态。
Estafeta 和 DrEnvio 是其各自所有者的商标。本模块与 Estafeta 或 DrEnvio 没有关联，也未获得其认可。