VibeFox Blue Express for OpenCart — 帮助
系统要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
Blue Express 账户（仅用于实时运费）：实时运费需要 Blue Express 电子商务账户及其 API 密钥（x-api-key）。请向 Blue Express 申请：developers.bluex.cl 或 gpo.integraciones@bx.cl。您使用的服务（EX、PY 或 MD）必须在您的 Blue Express 合同中已启用。如果您只使用固定运费，则无需 API 密钥。
智利地区：实时运费要求配送地址包含智利地区。如果您的商店缺少智利地区，扩展可以为您添加（参见「配置」）。
取件点：Blue Express 地图由顾客浏览器从 widget-pudo.blue.cl 加载。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件是一个包含两个 OpenCart 版本安装包的 zip 文件。请在您的计算机上解压。其中包含 README.txt、OpenCart 3 安装包 vfd_blue_express-oc3-(version).ocmod.zip 以及 OpenCart 4 安装包 vfd_blue_express.ocmod.zip。只安装与您 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。
OpenCart 3
1. 在管理后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_blue_express-oc3-(version).ocmod.zip。本扩展不添加 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用 Installer，而是将本安装包中 upload 文件夹的内容复制到商店的根目录中。
2. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Blue Express，点击 Install（绿色 + 按钮）。
3. 点击 Edit（铅笔按钮）打开设置页面。
4. 在 Edit 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key，然后点击 Activate（参见许可证密钥）。
5. 输入 API 密钥、服务、发货地区代码（例如 SCL）、如果商店货币不是 CLP 则输入 CLP 汇率，以及固定运费（例如 CL=4500）。送货上门请开启 Enable/Disable，如需提供 Blue Express 网点取件，请开启 Pickup point option。点击 Save。参见配置。
OpenCart 4
1. 在管理后台进入 Extensions > Installer，点击 Upload，选择文件 vfd_blue_express.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包将无法工作。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择扩展类型 Shipping。找到 VibeFox Blue Express，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 的步骤 4 和 5 输入许可证密钥和设置。两个版本的设置页面及其字段相同。
安装时，扩展会为订单的取件点创建一张数据表。在您开启送货上门或取件选项并保存之前，该方式保持关闭。如果您卸载后重新安装扩展，之前保留的 Blue Express 设置将再次生效。
配置
所有设置都位于扩展页面：Extensions > Extensions > Shipping > VibeFox Blue Express > Edit。各部分列在左侧。点击一次 Save 按钮即可保存整个页面，无需重新加载。每次保存也会清除缓存的 Blue Express 运费和公社数据。只有拥有本扩展修改权限的管理员用户才能保存设置。以下条件、价格和税类适用于两个选项。
无效值会被拒绝并显示错误，且不会保存任何内容：名称为空或包含字符 < > ; = # { }、名称超过 64 个字符、负数或无效数字、Min weight (kg) 大于 Max weight (kg)、不是整数的 Sort order，或未知的税类或地理区域。
页面顶部会显示可能隐藏选项或实时运费的设置警告：没有 API 密钥、商店货币不是 CLP 且未设置汇率、固定运费表为空、智利没有任何区域，以及商店没有千克（kg）重量类别或厘米（cm）长度类别，且扩展无法识别其默认单位（此时重量按 kg、尺寸按 cm 读取）。
常规
Enable/Disable: 开启或关闭 Blue Express 送货上门。
Name: 结账时送货上门所显示的配送方式名称。默认：Blue Express。必填，最多 64 个字符。
Tax class: 运费的税类，或 None (no tax on shipping)（默认）。Blue Express 价格含 IVA。如果您不希望 OpenCart 在其之上再加税，请选择 None。两个选项均适用。
Sort order: Blue Express 在结账配送方式中的位置。整数。
Blue Express 网点取件（PUDO）
Pickup point option: 提供由顾客选择的 Blue Express 网点配送，作为送货上门旁边的第二个选项。默认关闭。
Pickup point name: 结账时 Blue Express 网点取件所显示的配送方式名称。默认：Blue Express pickup point。必填，最多 64 个字符。
Blue Express API（实时运费需要）
API key: 您的 Blue Express API 密钥（请求头 x-api-key）。没有它时只使用固定运费。保存后该字段保持为空，并显示 A key is saved - leave empty to keep it. 仅在需要更改时才输入新值。
Remove the saved API key: 开启并保存即可删除已保存的密钥。
Service: 用于运费计算的 Blue Express 服务：Express (EX)（默认）、Prioritario (PY) 或 SameDay (MD)。必须在您的 Blue Express 合同中已启用。
Origin district code: 您发货所在地的 Blue Express 地区代码，例如圣地亚哥的 SCL（默认）。如不确定，请咨询 Blue Express。
CLP per 1 (your currency): 标签会显示您商店的默认货币，例如 CLP per 1 EUR。Blue Express 价格以智利比索（CLP）计价。请输入商店默认货币 1 个单位等于多少 CLP，例如 1050。未填写时不会使用实时运费。商店货币为 CLP 时将被忽略。
价格
Rate source: 价格的计算方式。实时运费要求智利地址包含地区和公社（城市）。错误会写入日志，绝不会显示给顾客。
Fixed prices: 每个国家一行，格式为 国家代码=价格，使用商店默认货币，不含税，例如 CLP 商店中的 CL=4500，或 EUR 商店中的 CL=4.50。小数点可使用逗号或句点。无效的行会被忽略，并在保存时的警告中列出。没有对应行的国家没有固定运费，因此需要固定运费时，这些选项将对该国隐藏。固定运费可用于任何国家。
Fixed price per: Order（默认）按订单收取一次价格。Item (price x quantity) 则按购物车中的商品数量相乘。这仅适用于固定运费。Blue Express API 的运费始终针对整个发货。
条件
Min weight (kg): 购物车重量低于此值时隐藏该方式。0 表示不限制（默认）。
Max weight (kg): 购物车重量高于此值时隐藏该方式。默认：100。0 表示不限制，留空即为 100 kg。
Minimum order subtotal: 仅当购物车小计（商店货币、需要配送的商品、扣除优惠券后、不含税）达到此值时才显示该方式。留空则始终显示。
免运费
Free shipping: 购物车小计达到一定金额后开启免运费。
Free from subtotal: 购物车小计（商店货币、需要配送的商品、扣除优惠券后、不含税）达到此值后免运费。此时不会向 Blue Express 发送请求。仅在 Free shipping 开启时使用。
可用性
Geo zone: 仅为该地理区域内的地址提供 Blue Express。All zones（默认）表示不限制。地理区域在 System > Localisation > Geo Zones 中管理。使用 Ignore shipping zones 时不检查。
Ignore shipping zones: 在每个地理区域都提供两个选项。国家将由下方的列表限定。
Countries: 该模式适用的目的国家。留空则允许所有国家。仅与 Ignore shipping zones 一起使用。
智利地区（仅在您的商店缺少智利地区时显示）
Blue Express 的实时运费需要智利地址的地区（RM、VS 等）。地区从地址所属的区域中获取，依据其代码或名称。本部分会显示您的商店中智利有多少个区域，以及缺少哪些地区（标准的 OpenCart 3.0.5 商店拥有 16 个中的 15 个，缺少 Ñuble）。点击 Add Chilean regions，即可将缺少的地区以 Blue Express 使用的代码添加为智利的区域。您已有的地区（按代码或名称判断）不会重复添加。点击按钮之前不会更改任何内容。您也可以在 System > Localisation > Zones 中自行添加。
高级
Debug log: 将请求和决策记录到 storage/logs/vfd_blex_debug.log.php。该文件无法通过网页读取。API 错误始终会被记录。API 密钥和顾客地址绝不会被记录。使用完毕后请关闭日志。日志达到 5 MB 时会被轮转。
Log: 显示日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall: 开启时，卸载扩展会删除设置、缓存的运费和日志。关闭时（默认），这些数据会保留以便重新安装。订单中保存的取件点始终保留。
导入 / 导出
Export: 点击 Download JSON，将设置保存为 JSON 文件。API 密钥不会被导出。
Import: 粘贴之前导出的 JSON，然后点击 Import 恢复设置，例如在另一家商店中使用。数值会像普通保存一样进行检查。已保存的 API 密钥会被保留。
结账时的工作方式
OpenCart 显示配送方式时，会为每个已启用的选项向扩展请求价格。如果设置了 Geo zone（且 Ignore shipping zones 关闭）且地址不在其中，则不会提供 Blue Express。开启 Ignore shipping zones 时，由 Countries 列表决定。只有 Requires Shipping 设为 Yes 的商品才计入：其他商品不增加重量，也不计入小计。扩展随后检查购物车重量和 Minimum order subtotal。小计是需要配送的商品价格，扣除优惠券之后、税前计算。礼品卡、积分和商店余额不计入。若适用免运费，价格为 0，且不会向 Blue Express 发送请求。
对于实时运费，地址必须位于智利，并包含地区和城市（公社）。扩展首先请求 Blue Express 识别公社，然后请求服务、发货地区、目的地和包裹的价格。每件商品都会按其重量和尺寸（从重量和长度类别换算为 kg 和 cm）发送。没有重量或尺寸的商品按 0.01 kg、10 x 10 x 10 cm 发送。申报价值以 CLP 发送。CLP 价格会换算为商店默认货币，按其小数位数取整，并以顾客的货币显示，同时加上所选 Tax class 的税款。
运费缓存 1 小时，公社数据最长缓存 12 小时，但不会超过 OpenCart 的缓存时间（默认 1 小时）。API 调用失败会记录 5 分钟，超时时间为 10 秒，因此缓慢或不可用的 API 不会拖慢每一次结账页面刷新。API 错误绝不会显示给顾客：该选项会被隐藏，或在备用模式下使用固定运费。原因会写入日志。
扩展不会在 Blue Express 中创建发货单或面单，不分配追踪号，也不显示物流更新。请在您的 Blue Express 账户中创建发货。没有按公社划分的区域运费表：请使用 Blue Express API 运费或按国家设置的固定运费。实时运费仅适用于智利。
在 OpenCart 4 中，顾客在结账页面的配送方式区块中点击 Choose，并在 Shipping method options 窗口中选择 Blue Express 或 Blue Express pickup point。这些选项的工作方式与 OpenCart 3 相同；取件点框在取件点中说明。
取件点
开启取件选项后，在 OpenCart 结账的 Delivery Method 步骤中，Blue Express pickup point 下方会出现一个框，其中有 Choose pickup point 按钮。该按钮会打开 Blue Express 官方地图，顾客可在其中选择网点。所选网点会显示其名称和地址，按钮变为 Change pickup point。该网点会保存到结账会话中，运费也会按 Blue Express 取件（PUDO）价格重新计算。如果价格有变化，该选项会显示新价格。如果该网点不再提供此选项，配送步骤会重新加载。在选定网点之前，该选项会显示送货上门的运费。
顾客必须选择网点才能继续：配送步骤中的 Continue 会被拒绝，并显示 Please choose a Blue Express pickup point. 这会在浏览器中检查，并且商店会再次检查。格式错误的网点代码会被拒绝，并显示 The selected Blue Express pickup point is not valid. Please choose it again on the map.，之前的选择会保留。如果保存失败，顾客会看到 The pickup point could not be saved. Please try again.
在 OpenCart 4 中，顾客在结账页面的配送方式区块中点击 Choose。选中该选项时，Shipping method options 窗口会在 Blue Express pickup point 下显示相同的框，其中包含 Choose pickup point 按钮。选择网点后价格若有变化，窗口中的选项会显示新价格；如果取件选项已为结账保存，配送方式字段和订单确认区块也会一并更新。如果该网点不再提供此选项，窗口会关闭，并重新加载配送方式列表。在窗口中未选择网点就点击 Continue，会在框中显示 Please choose a Blue Express pickup point. 并由商店再次检查。OpenCart 4 为结账保留一个订单，并在每次确认时更新；订单的取件点会随之更新，当订单改用其他配送方式时该取件点会被移除。
下单后，该网点会连同 Blue Express 代理编码、名称、地址和地区一起保存到订单中。它也会在取件选项名称之后添加到订单的配送方式中，例如 Blue Express pickup point: Blue Point Providencia, Av. Providencia 1234，因此顾客可在订单邮件和其账户的订单页面中看到。
在管理员订单页面（Sales > Orders、View）中，网点会显示在 Blue Express pickup point 面板中，包括其代码和地区。如果订单没有网点，面板会显示 Not chosen。点击 Edit，可使用 Choose on the Blue Express map 选择其他网点，或手动输入 Agency code、Name 和 Address，然后点击 Save pickup point。订单的配送方式文本也会更新，并且该变更会添加到订单历史中，不会通知顾客（Blue Express pickup point changed: 旧代码 -> 新代码）。更改网点只需要订单的修改权限，无需访问扩展设置。现有订单会保留其取件点数据。
许可证密钥
本扩展需要来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox Blue Express 许可证区块位于 Extensions > Extensions > Shipping > VibeFox Blue Express > Edit 页面的最上方，位于设置上方。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从本商店移除密钥）。其下方为 Product: opencart-shipping-blue-express 行和 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有拥有本扩展修改权限的管理员用户才能更改密钥。区块中的文本跟随管理后台语言（包括英文和俄文）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached 或带日期的 License expired on。商店地址变更后，或在您的账户中释放了域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展将继续使用最后一次已知的状态运行。
一个密钥只能用于一个域名：即 OpenCart 配置中的商店地址。从商店中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Blue Express，也不会计算运费。在同一浏览器中登录后台的管理员用户仍会在商店中看到该方式，并标注为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试扩展。打开一次 Edit 页面后，管理后台的 Dashboard 上会出现提醒。点击 × 关闭，可隐藏 7 天。现有订单不受影响。
许可证到期后，扩展仍会继续运行，但更新和支持需要续费。打开管理后台的 Dashboard 或 Edit 页面时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时总会删除许可证密钥和许可证状态。
故障排除
Blue Express 未出现在结账页面：请检查许可证是否有效，且 Enable/Disable（或 Pickup point option）已开启。阅读扩展页面顶部的警告。检查 Geo zone（或 Ignore shipping zones 和 Countries）、重量限制、Minimum order subtotal，并且如果您使用固定运费或备用方式，请检查 Fixed prices 中是否有该国家的行。检查商品的 Requires Shipping 是否设为 Yes。
实时运费未显示：使用 Blue Express API only 时，若没有运费，选项会被隐藏。开启 Debug log，重新加载结账页面，然后查看扩展页面上的 Log 字段。常见原因：没有 API 密钥、商店货币不是 CLP 且未设置 Exchange rate、地址缺少地区或公社、Blue Express 无法识别该公社，或 API 错误（例如 API 密钥被拒绝时的 HTTP 401 或 403）。使用 Blue Express API, fixed price if the API gives no rate 时，您在解决问题期间，顾客仍会获得固定运费。
智利地址没有地区：页面会显示关于缺少地区的警告。请在扩展页面点击 Add Chilean regions。保存时没有地区的顾客地址，需要由顾客编辑地址并选择地区。
Blue Express 价格之上又加了税：Blue Express 价格含 IVA。请将 Tax class 设为 None (no tax on shipping)。
地图无法打开：地图由顾客浏览器从 widget-pudo.blue.cl 加载，因此该地址必须可以访问，且未被您的网站屏蔽。
修改后运费看起来过时：在扩展页面点击 Save。这会清除缓存的运费和公社数据。
页面显示「Warning: You do not have permission to modify VibeFox Blue Express!」：您的管理员用户组可能只有查看设置的权限。请在 System > Users > User Groups 中为该组授予 extension/shipping/vfd_blue_express（OpenCart 3）或 extension/vfd_blue_express/shipping/vfd_blue_express（OpenCart 4）的修改权限。
开发者须知：Blue Express API 和地图地址可通过设置 vfd_blex_api_url 和 vfd_blex_widget_url（用于测试）替换；设置页面上没有对应字段。
卸载
进入 Extensions > Extensions，选择类型 Shipping，然后点击 VibeFox Blue Express 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会重置 Sort order、Tax class 和 Geo zone，以及该方式的状态。缓存的运费总会被删除。如果 Remove data on uninstall 已开启，Blue Express 设置和日志也会被删除。如果关闭，其他设置会保留，并在您重新安装扩展时再次使用。订单中保存的取件点数据永远不会被删除，现有订单的配送方式文本仍会保留取件点。
在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Blue Express 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。
Blue Express 是其各自所有者的商标。本扩展与 Blue Express 无关联，也未获得 Blue Express 的认可。