VibeFox Blue Express for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在较旧的 PHP 版本上安装。
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 购买。一个密钥只能用于一个域名。
安装
1. 进入后台，前往 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Blue Express，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥粘贴到 License key 中，然后点击 Activate（参见许可证密钥）。
4. 输入 API 密钥、服务、出发地区代码（例如 SCL）、如果店铺币种不是 CLP 则输入 CLP 汇率，以及固定价格（例如 CL=4500）。如果您想提供 Blue Express 网点自提，请开启 Pickup point carrier。点击 Save。参见配置。
安装时，模块会创建两个承运商：Blue Express（送货上门，配送时间文本 Home delivery，已启用）和 Blue Express pickup point（配送时间文本 Pickup at a Blue Express point，在您启用之前处于关闭状态）。两者都分配给智利区域以及所有顾客群组。您可以在 Shipping > Carriers 中更改区域、顾客群组、配送时间、Logo 和尺寸限制。请勿在那里设置价格：价格始终来自模块。
配置
所有设置都在模块页面：Modules > Module Manager > VibeFox Blue Express > Configure。每个部分都有各自的 Save 按钮，保存的是整个页面。每次保存也会清除缓存的 Blue Express 运费和市镇数据。页面顶部会显示警告，提示可能隐藏承运商或实时运费的设置：没有 API 密钥、店铺币种不是 CLP 且未设置汇率、固定价格表为空、智利没有地区、店铺的重量或尺寸单位模块无法识别（此时重量按千克、尺寸按厘米读取），或承运商已被删除。无效值会被拒绝并显示错误，且不会保存任何内容：承运商名称为空或无效、名称超过 64 个字符、数字为负数或无效，或 Min weight (kg) 大于 Max weight (kg)。以下条件和价格适用于两个承运商。
常规
Enable/Disable: 开启或关闭送货上门承运商。这与 Shipping > Carriers 中的承运商状态使用同一个开关。
Name: 结账时送货上门显示的承运商名称。默认：Blue Express。必填，最多 64 个字符。
Tax status: None (no tax on shipping)，或使用您的某条税务规则的 Taxable。Blue Express 价格包含 IVA。如果不希望 PrestaShop 在其上再加税，请选择 None。适用于两个承运商。
Blue Express 网点自提（PUDO）
Pickup point carrier: 在送货上门之外作为第二个承运商，提供送到顾客所选 Blue Express 网点的配送。默认关闭。这与 Shipping > Carriers 中 Blue Express pickup point 承运商的状态使用同一个开关。
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 unit of store currency: 当店铺默认币种不是 CLP 时，标签会显示它，例如 CLP per 1 EUR。Blue Express 价格以智利比索（CLP）计价。请输入店铺默认币种一个单位对应多少 CLP，例如 1050。如未设置，则不使用实时运费。当店铺币种为 CLP 时忽略此项。
价格
Rate source: 价格的计算方式。实时运费需要包含地区和市镇（城市）的智利地址。错误会写入日志，绝不会显示给顾客。
Fixed prices: 每个国家一行，格式为 COUNTRY_CODE=PRICE，使用店铺默认币种，不含税，例如 CLP 店铺中的 CL=4500 或 EUR 店铺中的 CL=4.50。小数点可以用逗号或句点。无效的行会被忽略，并在保存时列在警告中。没有对应行的国家没有固定价格，因此在需要固定价格时，这些国家的承运商会被隐藏。固定价格可用于任何国家。
Fixed price per: Order 按一次收取价格。Item (price x quantity) 按购物车中的商品数量相乘。这仅适用于固定价格。API 运费始终针对整个发货。
条件
Min weight (kg): 购物车重量低于此值时隐藏承运商。0 表示无限制。
Max weight (kg): 购物车重量高于此值时隐藏承运商。默认：100。0 表示无限制，空字段表示 100 kg。Min weight (kg) 不能大于 Max weight (kg)。
Minimum order subtotal: 仅当购物车小计达到此金额时才显示承运商（店铺币种，扣除折扣后，不含税）。留空则始终显示。
免运费
Free shipping: 开启购物车小计达到一定金额即免运费的功能。
Free from subtotal: 免运费的购物车小计起点（店铺币种，扣除折扣后，不含税）。仅在 Free shipping 开启时使用。
无配送区域时的可用性
Ignore shipping zones: 在每个区域都提供两个承运商。此时国家受下方列表限制。之后创建的区域也会被添加。再次关闭时，承运商会恢复到之前拥有的区域。
Countries: 此模式下的目的国家。留空则使用您发货的所有国家。仅在 Ignore shipping zones 下使用。
高级
Debug log: 将请求和决策记录到模块文件夹中的 logs/vfd_blex_debug.log.php。该文件无法通过网页打开。API 错误始终会被记录。API 密钥和顾客地址从不记录。完成后请关闭日志。
Log: 显示日志的大小和最新条目。点击 Clear log 可清空日志。
Remove data on uninstall: 开启时，卸载模块会删除设置和承运商。订单中保存的自提网点会保留。
智利地区（仅当您的店铺没有可用的智利地区时显示）
Blue Express 的实时运费需要智利地址的地区（RM、VS 等）。PrestaShop 默认不包含智利地区。点击 Add Chilean regions，即可将 16 个智利地区以 Blue Express 使用的代码添加为智利的州（states），并在智利地址表单中显示地区字段。按代码或名称已存在的地区不会重复添加。在您点击按钮之前，不会更改任何内容。您也可以在 International > Locations > States 中自行添加，代码为 RM、VS 等。
结账时的工作方式
在配送步骤中，PrestaShop 会向模块请求每个 Blue Express 承运商的价格。只有实体商品才计入：虚拟商品不增加重量，也不计入小计。模块会检查 Countries（配合 Ignore shipping zones）、购物车重量和 Minimum order subtotal。如果适用免运费，价格为 0，且不会向 Blue Express 发送请求。
实时运费要求地址位于智利，并包含地区和城市（市镇）。模块会先请求 Blue Express 识别市镇，然后请求服务、出发区域、目的地和包裹的价格。每件商品都会以换算为千克和厘米的重量和尺寸发送。没有重量或尺寸的商品按 0.01 kg、10 x 10 x 10 cm 发送。申报价值以 CLP 发送。CLP 价格会换算为店铺默认币种，然后以顾客购物车的币种显示。
运费缓存 1 小时，市镇数据缓存 12 小时。API 调用失败后会记住 5 分钟，超时时间为 10 秒，因此缓慢或不可用的 API 不会拖慢每次结账刷新。API 错误绝不会显示给顾客：承运商会被隐藏，或在备用模式下使用固定价格。原因会写入日志。
如果您在 Shipping > Carriers 中编辑已有订单的承运商，PrestaShop 会将其保存为新版本的承运商。模块会自动跟随新版本。
模块不会在 Blue Express 中创建发货或面单，不分配运单号，也不显示物流跟踪更新。请在您的 Blue Express 账户中创建发货。没有按市镇划分的区域运费表：请使用 Blue Express API 运费或每个国家的一个固定价格。实时运费仅适用于智利。
自提网点
当顾客在配送步骤中选择 Blue Express pickup point 时，其下方会出现一个框，带有 Choose pickup point 按钮。该按钮会打开官方 Blue Express 地图，顾客可在其中选择网点。所选网点会显示其名称和地址，按钮变为 Change pickup point。网点会保存在购物车中，运费将按 Blue Express 自提（PUDO）价格重新计算。如果价格发生变化，页面会刷新以显示新价格。在选择网点之前，承运商会显示送货上门的包裹价格。
顾客在未选择网点时无法继续：Please choose a Blue Express pickup point. 当顾客在配送步骤点击 Continue 时，店铺会进行此检查。格式不正确的网点代码会被拒绝，并显示 The selected Blue Express pickup point is not valid. Please choose it again on the map.，之前的选择保持不变。
下单时，网点会连同其 Blue Express 代理点代码、名称和地址一起保存到订单中。在后台订单页面，它显示在 Blue Express pickup point 区块中。点击 Edit，可使用 Choose on the Blue Express map 选择其他网点，或手动输入 Agency code、Name 和 Address，然后点击 Save pickup point。此更改会作为私密订单消息记录。更改网点只需要订单的编辑权限，无需访问模块页面。顾客会在订单确认页、订单详情页以及订单确认邮件中，在承运商名称旁看到该网点。来自 Mail alerts 模块的发给店铺的新订单邮件也会显示代理点代码。现有订单保留其自提网点数据。
许可证密钥
模块需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Blue Express 位于 Modules > Module Manager > VibeFox Blue Express > Configure 页面中设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以隐藏方式显示密钥、许可证状态（例如许可证有效期截止日期以及您的域名），并提供以下按钮：Check now 用于重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本商店移除密钥。其下方是 Product: presta-shipping-blue-express 一行，以及 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 账户中释放该名额。
如果没有有效的密钥，Blue Express 承运商不会在结账时显示给顾客，也不会计算任何运费。PrestaShop 前台无法得知您已登录后台，因此这些承运商对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时没有 Blue Express：请检查许可证是否有效，以及 Enable/Disable（或 Pickup point carrier）是否已开启。在 Shipping > Carriers 中，检查承运商是否覆盖顾客所在国家的区域和顾客群组，或开启 Ignore shipping zones 并检查 Countries。阅读模块页面顶部的警告。检查重量限制、Minimum order subtotal，如果您使用固定价格或备用方案，还要检查 Fixed prices 中是否有该国家的一行。商品也可能在商品页面中被限定为特定承运商。
实时运费不显示：使用 Blue Express API only 时，没有运费则会隐藏承运商。请开启 Debug log，重新加载结账页面，并查看模块页面上的 Log 字段。常见原因：没有 API 密钥、店铺币种不是 CLP 且没有汇率、地址中缺少地区或市镇、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 status 设置为 None (no tax on shipping)。
地图无法打开：地图在顾客的浏览器中从 widget-pudo.blue.cl 加载，因此该地址必须可以访问，且未被您的网站屏蔽。
修改后运费似乎过时：请在模块页面点击 Save。这会清除缓存的运费和市镇数据。
页面提示缺少 Blue Express 承运商：该承运商已在 Shipping > Carriers 中被删除。请在 Modules > Module Manager 中重置模块以重新创建。重置会保留您的设置和承运商状态。
卸载
进入 Modules > Module Manager，打开 VibeFox Blue Express 旁边的菜单，然后选择 Uninstall。许可证密钥、许可证状态和缓存的运费始终会被删除。如果 Remove data on uninstall 已开启，两个承运商都会被删除（订单保留其历史记录），并且设置、日志以及未关联订单的自提网点都会被删除。如果已关闭，承运商仅会被禁用，所有设置都会保留。重新安装模块会以之前的状态恢复承运商。订单中保存的自提网点永远不会被删除。
Blue Express 是其各自所有者的商标。本模块与 Blue Express 无关联，也未获得 Blue Express 的认可。